Payment Processing

Taking a Payment

A payment can be taken once a payment has been prepared.

Test Cards

The cards to use are:

Test Cards
Card Number	Card Type
4929 0000 0000 6	VISA
4462 0000 0000 0003	VISA DEBIT
5186 1506 6000 0009	MASTERCARD
5185 6900 6000 0001	MASTERCARD DEBIT

Billing and Policy Address Same

In the above screenshot there is a card payment where the billing address and policy address are the same.

Request

curl -X 'POST' \
  'https://st.igate-test.co.uk/api/v1/payments/0394a070-4afe-4be3-89c3-bf5626686289/take-payment/' \
  -H 'Authorization: Bearer abc123xyz...' \
  -H 'accept: application/json'
  -d '{
    "card_details": {
        "card_holder": "J SMITH",
        "card_number": "1234567890121234",
        "expiry_date": "1028",
        "cv2": "123",
        "card_type": "VISA"
      },
      "billing_use_policy_address": true
    }'

Response

There are two possibilities for the response. One that the payment was successfully taken during the take_payment transaction. The other is that the card has gone to a 3DS validation state.

In this case, the response would look like:

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-04T14:06:47.420292Z",
  "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": {
    "url": "https://st.igate-test.c.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_use_policy_address": true,
  "payment_status_state": "PAYMENT_SUCCESS",
  "payment_status": 6,
  "client_feedback": "Your payment was successful",
  "creq": null,
  "acsurl": null,
  "three_ds_session_data": null
}

After this state, the payment flow should continue with polling of the payment endpoint until the a concluding (success or error) state is returned.

In the case of a 3DS flow, the response would look like:

{
  "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-04T14:06:47.420292Z",
  "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": {
    "url": "https://st.igate-test.c.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_use_policy_address": true,
  "payment_status_state": "PAYMENT_3DAUTH",
  "payment_status": 5,
  "client_feedback": "Processing your payment",
  "creq": "ewogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcSIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjIuMCIsCiAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIiA6IzEiLAogICJhY3NUcmFuc0lEIiA6ICJjNTBiOWRmNC1kOTc0LTQ5ZDEtOTYyZC0zYjI2ODZiZTNmYTEiLAogICJjaGFsbGVuZ2VXaW5kb3dTaXplIiA6ICIwNSIKfQ",
  "acsurl": "https://test.sagepay.com/3ds-simulator/html_challenge",
  "three_ds_session_data": "111/3000105/B083/WEB"
}

The the status will be PAYMENT_3DAUTH along with creq, acsurl and three_ds_session_data being non-null in this flow.

These values must be taken, and in a web environment (such as a browser window) and a self-submitting form must be constructed:

<form action={acsurl} method="post">
    <input type="text" name="creq" value={creq}/>
    <input type="text" name="threeDSSessionData" value={three_ds_session_data}/>
</form>

This form once submitted will issue a redirect, within the window to a 3rd party banking system. In the test environment this will be a (Sagepay) test portal, but in a live environment this could be any bank or card issuing portal or flow. Once that flow has been completed (it can be anything, 2FA, a password etc) the window will redirect to a page on our service side. This is a completely empty page and will only contain:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Payment Complete</title>
    <script>
        window.parent.postMessage("PaymentComplete", "*");
    </script>
</head>
<body></body>
</html>

The client app should listen for the ``window.parent.postMessage `` (see https://developer.mozilla.org/en-US/docs/Web/API/Window/message_event) in the flow and end the external window flow and return to the app.

After this event, the payment flow should continue with polling of the payment endpoint until the a concluding (success or error) state is returned.

Different Billing Address

A user can select that they have a different billing address to the policy address. A user performs an address lookup or a manual entry, but the billing_address is required as billing_use_policy_address is false.

For the billing_address entry use the address entry form standard throughout the application with the user able to use the address lookup endpoint to aide address entry.

Request

curl -X 'POST' \
  'https://st.igate-test.co.uk/api/v1/payments/0394a070-4afe-4be3-89c3-bf5626686289/take-payment/' \
  -H 'Authorization: Bearer abc123xyz...' \
  -H 'accept: application/json'
  -d '{
  "card_details": {
    "card_holder": "J SMITH",
    "card_number": "1234567890121234",
    "expiry_date": "1024",
    "cv2": "588",
    "card_type": "VISA"
  },
  "billing_use_policy_address": false,
  "billing_address": {
    "house": "23",
    "street": "North Lake str.",
    "city": null,
    "county": "Norfolk",
    "postcode": "PE301KM"
  }
}'

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-04T14:06:47.420292Z",
  "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": {
    "url": "https://st.igate-test.co.uk/api/v1/user/address/fad30aaf-218d-4f41-b3f1-8e1ece07b746/",
    "uuid": "fad30aaf-218d-4f41-b3f1-8e1ece07b746",
    "created_at": "2025-02-03T21:41:45.856587Z",
    "updated_at": "2025-02-03T21:41:45.856665Z",
    "house": "23",
    "street": "North Lake str.",
    "city": null,
    "county": "Norfolk",
    "postcode": "PE301KM"
  },
  "billing_use_policy_address": false,
  "payment_status_state": "CONVERTING_POLICY",
  "payment_status": 10,
  "client_feedback": "Finalizing your policy"
}

Successful Payment

A successful payment is where payment statuses are one of the below:

Successful Payment States
Status ID: `payment_status`	Status Name: `payment_status_state`	Description
6	PAYMENT_SUCCESS	Payment has been taken successfully.
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.

The last state of a successful payment is POLICY_CONVERTED, where the flow of the states are PAYMENT_SUCCESS -> CONVERTING_POLICY -> POLICY_CONVERTED.

When the payment_status_state in the response is one of the success states, but not POLICY_CONVERTED, the payment url (in our example https://st.igate-test.co.uk/api/v1/payments/0394a070-4afe-4be3-89c3-bf5626686289/ ) should be polled until the state is POLICY_CONVERTED:

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

{
  "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-04T14:06:54.926854Z",
  "quote": "https://st.igate-test.co.uk/api/v1/quote-requests/quotes/0e02575f-f9e1-4061-8408-f960f2a91173/",
  "policy": {
    "uuid": "05fec120-1e76-4d00-a357-978687c3514e",
    "url": "https://st.igate-test.co.uk/api/v1/policies/05fec120-1e76-4d00-a357-978687c3514e/",
    "created_at": "2025-02-04T14:06:54.925069Z",
    "updated_at": "2025-02-04T14:06:54.925160Z",
    "vehicle": {
      "url": "https://st.igate-test.co.uk/api/v1/user/vehicles/b55797bc-e75d-473f-a66c-606e9fb2abda/",
      "uuid": "b55797bc-e75d-473f-a66c-606e9fb2abda",
      "created_at": "2025-02-01T13:47:05.559715Z",
      "updated_at": "2025-02-01T13:47:05.559805Z",
      "vehicle_type": 1,
      "reg_no": "RE23EA",
      "abi_code": 16545701,
      "year_of_manufacture": 2010,
      "cc": 1242,
      "number_of_doors": 3,
      "number_of_seats": 4,
      "make": "Fiat",
      "model": "500",
      "gearbox_type_id": "002",
      "gearbox_type_name": "Manual",
      "body_type_id": "02",
      "body_type_name": "Hatchback",
      "fuel_type_id": "002",
      "fuel_type_name": "Petrol"
    },
    "policy_number": "199/9955048/Z307/WEB",
    "insurer_name": "Trinity Lane",
    "scheme_code": "9999",
    "scheme_name": "Trinity Lane - Short Term Test",
    "policy_start_date": "2025-02-04T14:06:48.747685Z",
    "policy_end_date": "2025-02-08T12:00:00Z",
    "policy_progress": 0
  },
  "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": {
    "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_use_policy_address": true,
  "payment_status_state": "POLICY_CONVERTED",
  "payment_status": 11,
  "client_feedback": "Your policy is ready"
}

Notes

Once the payment status is POLICY_CONVERTED policy is configured and not null.

The payment is considered complete and the documentation should be followed for the payment complete section.

Unsuccessful Payments

A payment is unsuccessful when the payment state is listed below:

Successful Payment States
Status ID: `payment_status`	Status Name: `payment_status_state`	Description
7	PAYMENT_FAILED	Payment has failed.

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-04T14:06:47.420292Z",
  "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": {
    "url": "https://st.igate-test.co.uk/api/v1/user/address/fad30aaf-218d-4f41-b3f1-8e1ece07b746/",
    "uuid": "fad30aaf-218d-4f41-b3f1-8e1ece07b746",
    "created_at": "2025-02-03T21:41:45.856587Z",
    "updated_at": "2025-02-03T21:41:45.856665Z",
    "house": "23",
    "street": "North Lake str.",
    "city": null,
    "county": "Norfolk",
    "postcode": "PE301KM"
  },
  "billing_use_policy_address": false,
  "payment_status_state": "PAYMENT_FAILED",
  "payment_status": 7,
  "client_feedback": "There was a problem with your payment"
}

If this is the case the user may retry a payment with different card details by using the take a payment endpoint again.

Notes

A user is allowed to retry as many times as they need.

Error Payment States

There are payment states where there have been errors while taking the payment. These are listed below.

Error Payment States
Status ID: `payment_status`	Status Name: `payment_status_state`	Description
8	TERMINAL_ERROR	There has been an error during payment that is unrecoverable.
9	TIMED_OUT	Payment has timed out.

When these states are encountered there is an error in the service. When these states are encountered numerous times consider that the payment cannot be taken and the app should take the appropriate action.