Prepare Payment

Preparations must be completed before a payment can be taken. This is performed by performing a POST request to the Payment (Create) endpoint. Once a payment hs been created, the newly created payment is polled until ready_for_payment is true indicating that the user may proceed.

API

Payment (Create)

Request

curl -X 'POST' \
  'https://st.igate-test.co.uk/api/v1/payments/' \
  -H 'Authorization: Bearer abc123xyz...' \
  -H 'accept: application/json'
  -d '{
    "quote": "https://st.igate-test.co.uk/api/v1/quote-requests/quotes/a40c13be-b9a8-48da-bd94-400a6676c390/"
    }'

Response

Type: 201 Created

{
  "uuid": "0394a070-4afe-4be3-89c3-bf5626686289",
  "url": "https://st.igate-test.co.uk/api/v1/payments/0394a070-4afe-4be3-89c3-bf5626686289/",
  "created_at": "2025-02-04T13:04:48.374818Z",
  "updated_at": "2025-02-04T13:04:48.381564Z",
  "quote": "https://st.igate-test.co.uk/api/v1/quote-requests/quotes/0e02575f-f9e1-4061-8408-f960f2a91173/",
  "payment_status_state": "PENDING_PREPARE",
  "payment_status": 1,
  "client_feedback": "Setting up your policy"
}

Notes

The URL to perform the Payment (Polling) in this case is https://st.igate-test.co.uk/api/v1/payments/0394a070-4afe-4be3-89c3-bf5626686289/.
client_feedback can be used during polling to update the user about the current state of the process.

Payment Status States

As part of the above there are different states the payment can be in.

Payment States
Status ID: `payment_status`	Status Name: `payment_status_state`	Description
1	PENDING_PREPARE	The initial state of the payment once it has been created.
2	PREPARE_INFLIGHT	When the payment is currently processing before payment can be taken.
3	PENDING_PAYMENT	The payment is ready to be taken from the user.
4	PAYMENT_INFLIGHT	The payment is currently being processed.
5	PAYMENT_3DAUTH	The payment requires 3D Authentication.
6	PAYMENT_SUCCESS	Payment has been taken successfully.
7	PAYMENT_FAILED	Payment has failed.
8	TERMINAL_ERROR	There has been an error during payment that is unrecoverable.
9	TIMED_OUT	Payment has timed out.
10	CONVERTING_POLICY	Payment has been successfully taken and a policy is being created.
11	POLICY_CONVERTED	The policy has been successfully created and the payment process is completed.

Notes

3D Authentication workflow is in active development and will be discussed in a future release.

Payment (Polling)

Once a payment has been created the payment url should be polled until the payment is ready. The payment_status_state at this point will transition from PENDING_PREPARE -> PREPARE_INFLIGHT -> PENDING_PAYMENT.

When payment_status_state is PENDING_PAYMENT it is possible to take a payment.

Request

curl -X 'GET' \
  'https://st.igate-test.co.uk/api/v1/payments/0394a070-4afe-4be3-89c3-bf5626686289/' \
  -H 'Authorization: Bearer abc123xyz...' \
  -H 'accept: application/json'

Response

Type: 200 OK

{
  "uuid": "0394a070-4afe-4be3-89c3-bf5626686289",
  "url": "https://st.igate-test.co.uk/api/v1/payments/0394a070-4afe-4be3-89c3-bf5626686289/",
  "created_at": "2025-02-04T13:04:48.374818Z",
  "updated_at": "2025-02-04T13:04:55.662618Z",
  "quote": "https://st.igate-test.co.uk/api/v1/quote-requests/quotes/0e02575f-f9e1-4061-8408-f960f2a91173/",
  "policy": null,
  "policy_address": {
    "url": "https://st.igate-test.co.uk/api/v1/user/address/f79ac47d-ae58-4c2d-8cc4-b70d2b5ba7be/",
    "uuid": "f79ac47d-ae58-4c2d-8cc4-b70d2b5ba7be",
    "created_at": "2025-02-04T13:04:48.379559Z",
    "updated_at": "2025-02-04T13:04:48.379625Z",
    "house": "21b",
    "street": "Tuesday Market Place",
    "city": "King's Lynn",
    "county": "Norfolk",
    "postcode": "PE301JW"
  },
  "billing_address": {
    "house": "",
    "street": "",
    "city": "",
    "county": "",
    "postcode": ""
  },
  "billing_use_policy_address": true,
  "payment_status_state": "PENDING_PAYMENT",
  "payment_status": 3,
  "client_feedback": "Enter your payment details"
}