Process a transaction using saved card details (charge stored card) - [UK Specific]

This API flow is mandatory in the UK for processing a transaction using a saved card. As 3DS is mandatory due to the regulatory compliance requirements around the processing of card transactions where 3DS is mandatory on Customer-Initiated-Transactions for eCommerce, charge stored card and on the first transaction.

Note - 3DS is mandatory in the UK for processing a transaction using saved card details if it is a Customer-Initiated-Transaction.

API Steps to implement - Process a transaction using saved card details [UK]

Process a transaction using saved card details
1. When you submit a CIT request the function will process a 3DS real-time card transaction on the card account currently registered to the payer. This will then require a challenge for the end user to complete the 3DS challenge or be completed frictionless.
2. If it is an MIT payment request, this will not prompt 3DS and will not go through a challenge.
If a 3DS challenge is required a re-directUrl is returned in the response to direct the user to complete the 3DS challenge. Redirect the user and store the redirectId as this is required to finalise the transaction in step 4.
Once the 3DS challenge is complete, the user will be directed back to the CallbackURL to trigger the notification that the submission is complete. Finalise the 3DS transaction by retrieving the result

Step 1 - Process a transaction using saved card details

API

POST 3DS - Process a transaction using saved card details

Minimum API property requirements
- ‘ProcessType’
- ‘Reference’
- ‘Amount’
- ‘CallbackUrl’
- ‘BrowserInfo’
  - ‘UserAgent’
  - ‘AcceptHeader’
  - ‘Language’
  - ‘TimeZone’
  - ‘ColorDepth’
  - ‘ScreenHeight’
  - ‘ScreenWidth’
- ‘CardstorageType’
- ‘CardAuthorizationType’

Sample

Example Request

JSON

{{url}}/businesses/{{business-id}}/payers/{{payer-reference}}/transactions/card

JSON

{
    "ProcessType": "COMPLETE",
    "Reference": "TestStoredRef1a",
    "Amount": 10.00,
    "Description": "This is a test transaction",
    "Audit": {
      "Username": "Example-User",
      "UserIP": "1.2.3.4"
    },
    "CallBackUrl": "http://test.com",    
    "BrowserInfo": {
      "UserAgent": "test",
      "AcceptHeader": "test",
      "Language": "test",
      "TimeZone": "-300",
      "ColorDepth": 10,
      "ScreenHeight": 10,
      "ScreenWidth": 10      
    },
    "CardStorageType": "CIT_PAYFAC_STORED",
    "CardAuthorizationType": "ONEOFF"
}

Example Response for 3DS challenge required

JSON

{
    "transactionId": null,
    "reference": "TestStoredRef1",
    "statusCode": "V",
    "subStatusCode": "VCR",
    "statusDescription": "3-D Secure Required - send your customer to the 'RedirectUrl'",
    "processedAmount": 0.0,
    "cardType": "Visa",
    "redirectId": "7595a884ca3744ac83f5a033d48a2896",
    "redirectUrl": "https://sandbox.rest.paymentsapi.io/businesses/8C81D848-1E9D-45B3-8382-0C108FDB9C9C/services/tokenize-card/3dsecure/redirect2/7595a884ca3744ac83f5a033d48a2896",
    "cardAuthorizationReference": null
}

Stored Card Transaction Model

Property	Type	Description
`processType`*	Card Process Type	How the transaction is to be processed
`reference`*	string(100)	Unique reference you provide to identify the transaction (must be unique across all your transactions)
`amount`*	decimal	Amount of the transaction (include decimal point for currencies with cents).
`description`	string(128)	You can provide additional information to describe the transaction
`serviceDate`	DateTime	Date the service will be provided, ie Booking date. Optional.
`CallbackUrl`**	string(128)	For handling of the challenge scenario, you must provide a URL for your website that your customer will be redirected back to after the verification process. The URL should contain an id/reference that uniquely identifies the transaction that you are attempting to process so you can pick up where you left off when the customer is redirected back to your site
`BrowserInfo`**	BrowserInfoModel	When using 3-D Secure, in order for the card's issuing bank to provide a challenge UI to your customer that is rendered appropriately for the device that your customer is using, the 3-D Secure system requires you to collect and pass-through information on the following information about the browser that your customer is using
`CardStorageType`**	enum	Used to specify if you are storing the card you are providing, and whether or not it is CIT or MIT. See here for possible values.
`CardAuthorizationType`**	enum	Used to specify the nature of the authorization. See below for allowed values. See here for possible values.
`audit`	Audit	Can be used to provide tracking information of the user of your system who is performing the action

*Required

**Required for UK

Step 2 - If a 3DS challenge is required, redirect the user to the redirectUrl to complete challenge

Re-direct the user to the redirectUrl.
1. Example from above:
  1. "redirectUrl": "https://sandbox.rest.paymentsapi.io/businesses/8C81D848-1E9D-45B3-8382-0C108FDB9C9C/services/tokenize-card/3dsecure/redirect2/7595a884ca3744ac83f5a033d48a2896"
Store the redirectId to finalise the transaction.
1. Example from above:
  1. "redirectId": "7595a884ca3744ac83f5a033d48a2896",

Step 3 - Finalise the 3DS transaction

API

POST ChargeStoredCard - 3D Secure Finalize Transaction

Call this endpoint when the user is redirected back to your callbackUrl

Sample

Example Request

JSON

{{url}}/businesses/{{business-id}}/transactions/saved-card-payments/finalize/{{redirect-id}}

Example Response

JSON

{
    "transactionId": "RT1272656",
    "reference": "TestStoredRef4abc",
    "statusCode": "S",
    "subStatusCode": null,
    "statusDescription": null,
    "processedAmount": 10.53,
    "cardType": "Visa",
    "redirectId": null,
    "redirectUrl": null,
    "cardAuthorizationReference": null
}

3DS Test Cards to test different cases

When testing the 3DS supports a few different card numbers for triggering different scenarios:

Frictionless Success	Frictionless Fail	Challenge Required
4907639999909022	5283901906612672	4918914107195005
4016360000000010	4016360000000028	4016360000000093

What to do if the payment is failed / rejected?

Depending on the scenario and reason for the rejection, you can simply re-attempt payment via the same API workflow. However, if the payment has failed due to ‘insufficient funds’, it is recommended to have the business contact the payer before re-attempting payment to ensure sufficient funds are available to reduce the risk of the payment failing once more.

This concludes the API workflow of implementing the Process a transaction using saved card (charge stored card) to your application. Refer to our other methods available for accepting payments.