Home Sign out

Introduction

The Adflex payment API is a comprehensive set of RESTful based web services that allow you to implement card payment processing into your applications. Our APIs are delivered through seamless cloud integration to cover a wide range of payment processing methods and security measures such as tokenization, strong customer authentication (SCA) and card on file (CoF). We also cover the full spectrum of card processing environments, including customer-not-present, customer present, eCommerce, B2B level 3 and travel enhanced data.

APIs are grouped into two types, Core and PayPage.

Core - A collection of foundation layer payment APIs not bound by any session state mechanism.

Paypage - A session-based API set designed to satisfy PCI DSS compliance. Works in conjunction with a JavaScript widget to capture the card outside of your system and inside our PCI compliant system.

Both API groups can be used together in creating a PCI compliant hybrid payment process. For example, capturing and tokenizing a card using the PayPage API followed by authorising and settlement using the Core API

PCI DSS Compliance

Adflex is a fully PCI DSS compliant payment processor at the highest level.

To minimise your PCI burden and achieve PCI SAQ-A compliance, use our Paypage solution.

If you intend to capture and store the card details yourself, you can use our Core API. However this would bring you into scope of PCI-DSS SAQ A-EP or PCI DSS SAQ D compliance.

Click here for further information on PCI DSS SAQ (Self Assessment Questionnaire)

API Description

The Adflex RESTful API uses a JSON format for both requests and responses. HTTP works as a request-response protocol between the client and server. The following table details the HTTP methods that are used in conjunction with the resource end points detailed in the API documentation

HTTP Verb CRUD Description
POST
Create
Used for creating resource.
GET
Read
Used for retrieving resource.
DELETE
Delete
Used for deleting resource.

Testing

In order to get you up and running quickly, we recommend that you use a free tool called Postman. This allows you to execute API calls from a collection of predefined method templates.

Click here to download Postman application.

Once installed, import the following two files to complete your Adflex API evaluation environment;

  • The Postman Environment file, containing your secret, access keys and adflex account code provided when you register for an Adflex Sandbox account.
  • Click here to download the Adflex API Postman Collection file, containing the complete Adflex API method templates for each resource and including the javascript to create the JWT authentication token.
Test Cards

We have made available a range of test cards in order for you to test a wide range of processing scenarios, including Authorised, declined and Errored of Debit, Credit and B2B purchasing cards.

Level 1 CREDIT Cards
Outcome MasterCard MasterCard 2 Range Visa Amex Retail
Auth 5185 5110 0000 0010 2223 0000 1001 1804 4012 0010 3627 5556 3782 8224 6310 005
Decline 5185 5150 0000 0045 2223 0000 1001 0095 4012 0010 3629 8889 3782 8224 6317 000
Refer 5185 5150 0000 0052 2223 0000 1001 0202 4012 0010 3685 3337 3782 8224 6320 004
Error 5185 5110 0000 0002 2223 0000 1001 0194 4012 0010 3698 3332 3782 8224 6319 006
Level 3 CREDIT Cards
Outcome MasterCard Visa Amex CPC
Auth 5569 5100 0000 0018 4715 0570 0000 0107 3742 9048 2911 992
Decline 5569 5000 0000 2296 4715 0570 0000 0123 3742 9048 2907 990
Refer 5569 5000 0000 2312 4715 0570 0000 0164 3742 9048 2920 993
Error 5569 5000 0000 2338 4715 0599 9900 0437 3742 9048 2919 995
Level 1 DEBIT Cards
Outcome MasterCard Visa Visa Electron Maestro Intl Maestro
Auth 5573 4899 0000 0028 4137 3356 0011 7780 4844 2155 0011 5643 5033 9619 8900 0008 18 6799 9901 0000 0000 019
Decline 5573 4899 0000 0721 4137 3356 0011 0785 4844 2155 0011 7649 5033 9619 8900 0381 15 6799 9901 0000 0000 076
Refer 5573 4899 0000 2024 4137 3356 0011 2088 4844 2155 0012 0643 5033 9619 8900 0320 19 6799 9901 0000 0000 209
Error 5573 4899 0000 1927 4137 3356 0011 1981 4844 2155 0011 9645 5033 9619 8900 0319 12 6799 9901 0000 0000 191
3DS v1 Test Cards
PAN Enrolment Status Error Code Response
4012001038443335
N
51674 (TDSNotSupportedByCard)
Cardholder is not enrolled for 3D Secure
4012001038488884
U
51675 (TDSFailedVERES)
Unable to process
4012001037141112
Y
50001 (Ok)
Successful Payer Authentication
Notes
  • Use any date in future for Card Expiry Date.
  • Adflex test cards must not be used in any live environment.
  • For cards that have an outcome of Authorised support the special use of the CSC (Card Security Code) value as follows;
Position Name Values
1 CSC 1=Unchecked, 2=Matched, 4=NotMatched
2 AVS Postcode 1=Unchecked, 2=Matched, 4=NotMatched
3 AVS Address 1=Unchecked, 2=Matched, 4=NotMatched
4 Force Decline 0=No, 1=Yes

Example 1: CSC=2220 responds with CVC=Matched, Postcode=Matched, Address=Matched and Authorised

Example 2: CSC=2421 responds with CVC=Matched, Postcode=NotMatched, Address=Matched and Declined

In all the above cases do not use any numbers in the address/postcode fields as this will result in unexpected results.


Getting Started

To get started create an Adflex sandbox account. Click here

Once registered you will receive the following;

  • A Postman Environment JSON file, containing your secret, access keys and adflex account code
  • A Postman JSON Collection file, containing the complete Adflex API method templates for each resource and including the javascript to create the JWT authentication token.
Authentication

We uses a robust authentication methodology. It starts with a secret key that is created by Adflex and issued to the merchant at the point of account set up. The main purpose of this key is to sign the authentication token for each API call. This secret key has to be treated as secret, securely encrypted on your system and never transmitted.

The secret key is accompanied by an accessKey. This is used in the header of the REST message along with the JWT authentication token.

Keys
Role Created By Key Name Prefix Length Resource Lifetime API AHPP Transmission
Secret Key Adflex secretKey sk_* <=4000 From Adflex Static, ~1year y n Never passed!
Safe Pointer to Secret Key Adflex accessKey ak_* <=4000 From Adflex Static, ~1year y n API call header
API Authentication Customer authenticationToken none variable Create JWT Dynamic, per api call, max 240 mins y n API call header
AHPP Session Adflex sessionID sn_* <=4000 /ahpp/session Dynamic, per AHPP transaction, max 240 mins y n Merchant js lib

Adflex uses JWT authentication mechanism with signatured keys in order to verify the requests. There are many libraries supporting every language which is available at https://jwt.io/


Creating a JWT Token

{ "alg" : "HS256" , "typ" : "JWT" , }

Description: alg: Algorithm (HS256). typ: Type.

Create a body for JWT token, all shown elements are mandatory.

Payload { "jti" : "df30eba7-5062-4804-9061-4e321585540b" , "aud" : "https://api-dev.adflex.co.uk/v2/tokens" , "iss" : "Adflex" , "iat" : "1558452885" , }

Description: jti: Unique GUID per call. aud: The fully qualified resource endpoint the JWT will be used for. For example: "https://api-test.adflex.co.uk/v2/transactions/authorisation". iss: Issuer, must be set to "Adflex. iat: Issued time, use NumericDate format as per RFC 7519.

Create JWT token and pass it in the "Authorization" header as "Bearer {JWTtoken}"

You need to get the secret key in bytes using UTF-8; encoding secKey.getBytes("UTF-8")

The Authentication Flow
The Authentication Flow

Processing Scenarios

When you make a payment by Credit or Debit card, you fire off a complex sequence of operations, just a few seconds later the payment will be Authorised or Declined. But in those few seconds, a whole series of security checks, communications and analysis of the trustworthiness of the transaction will be taken place. Until the payment is actually in your bank, the sale will not be completed.

It all happens quietly behind the scenes. You may see that it is fast approval and rapid payment. A customer may dispute a payment, leading to a chargeback, for example. That is when a broad understanding of what is going on can help you.

In payment processing, the full process to complete a card payment usually takes about three working days, during which it passes through important stages eg. authorisation, clearing and settlement.

Card Processing Model

Card processing is typically broken down into three phases.

Authentication - Where the customer is using their card directly, eg. eCommerce. This step will attempt to authenticate the user is the real card owner.

Authorisation - The amount to charge is ring-fenced on the card as the potential charge to be made to the card on the settlement. There is no transfer of funds between the cardholder and the merchant but will reduce the spending limit on the card by the transaction amount.

Settlement - This will execute the transfer of authorised funds between the cardholder to the merchant.

Card AVS and CSC

AVS is a Cardholder not Present (CNP) fraud detection process based on passing the address information captured during the checkout process directly to the cardholders issuing bank for checking. Once checked the issuer then returns a code indicating the certainty of the address match. This code is then passed through our rules-based checking system to contribute to a transaction acceptance score. Please note that AVS does not work so well for corporate cards where the card may be registered at a different address to that of the cardholder.

CSC also referred to CVC and CVV is a three to four-digit security code that should only be known to the cardholder. This code is requested during the checkout process and is passed over to the cardholders issuing bank for checking. The response is then passed through our rules-based checking system to contribute to a transaction acceptance score. A failed CSC transaction should never be accepted.

When is an AVS/CSC check performed? AVS/CSC rules are agreed at the time of signing up with Adflex and are set at the merchant account level. These rules will be applied across all transactions processed under the merchant account. If the outcome of the rule rejects the transaction, then Adflex will attempt a reversal to cancel the transaction.

Position Name Values
1 CSC 1=Unchecked, 2=Matched, 4=NotMatched
2 AVS Postcode 1=Unchecked, 2=Matched, 4=NotMatched
3 AVS Address 1=Unchecked, 2=Matched, 4=NotMatched
4 Force Decline 0=No, 1=Yes

Delayed shipment and charge model

There are several ways to deal with a delayed shipment and charge model.
Here are a few options:

Option 1 : To reserve, but not take the funds from the card (ring-fence) the charge value at the point of order entry.

  1. Create an /ahpp/session, taking care to set the "tokenLifetime" "saveCardOption" and "tokenLifetime" "ttlDays" values to the required card storage values.
  2. Invoke the https://paypage-test-cdn.adflex.co.uk/MerchantLibrary/lib.min.js widget to capture and tokenise the card.
  3. Immediately after the card is captured, call /ahpp/authorisation/token with the property "processMode" set to "authOnly"
  4. Later, at the point of dispatch, call /transactions/settle to take the ring-fenced funds from the card. Note this step should be called with 4-10 days of the original authOnly transaction.

The impact on the cardholder is their card spend limit will be reduced for the period prior to the dispatch of the goods and that the funds will only be taken once the goods are dispatched. This is commonly known as a "shadow" on the cardholder's card.

The net benefit for the merchant is that there is a high probability of receiving the ring-fenced funds on dispatch and settle.

If for any reason the dispatch phase is not run (eg order cancelled, or stock not available) then the impact on the card holder is that their cards spend limit will be reduced for a short period of time whilst the original authOnly naturally expires. This is not a limitation of Adflex, but the way the card authorise / settle processes and handled in the UK.

Note on the use of /transactions/reversal. The reversal process is designed to reverse (remove the reserved amount on the card) if called very shortly (typically hours) after the execution of an "authOnly" transaction. Adflex is currently working with specific acquirers on supporting the "enhanced reversals" process which will work on "authOnly" transactions greater than a few hours old. This is expected to be introduced within the next few months, once the initial PSD2 SCA and Credentials on File compliance work has been fully implemented.

Option 2 : Authenticate and tokenise the card, followed by a zero value authorisation only.

  1. Create an /ahpp/session, with a "amount" value of zero, taking care to set the "tokenLifetime" "saveCardOption" and "tokenLifetime" "ttlDays" values to the required card storage values.
  2. Invoke the https://paypage-test-cdn.adflex.co.uk/MerchantLibrary/lib.min.js widget to capture and tokenise the card.
  3. Immediately after the card is captured, call /ahpp/authorisation/token with the property "type" set to "AccountVerification" and "amount" "value" to zero.
  4. Later, at the point of dispatch, call /transactions/authorisation/token with the "amount" "value" set to the shipment value.
  5. Immediately after, call /transactions/settle to take the funds from the card.

The impact on the cardholder is that their card spend limit will not be reduced for the period prior to the dispatch of the goods and that the funds will only be taken once the goods are dispatched.

The impact on the merchant is a probability that the card has insufficient funds to pay for the shipment.

How to manage Refunds

For obvious reasons refunds are not allowed to be a card holder initiated option.
Refunds are managed in the merchant environment and are executed using a call to /v2/transactions/authorisation/token with the property "type" of "Refund".
Settlement Options
The Settlement is the process of executing the authorised payment charge from the card to the merchant.

There are two fundamental models:

Authorisation (processMode=AuthAndSettle) followed by an Adflex invoked automatic settlement at the end of day.

A separate Authorisation (processMode=AuthOnly) followed by a merchant invoked settlement call.

Regarding certainty of getting paid, if you call /ahpp/authorisation/token and get a response "statusCode" = "Authorised" and an "authCode" number then the transaction will be honoured and paid.

Here are a few examples where there may be a small risk of not getting paid:

An extended time (typically > 10 days) between authorising and settling the card.

The cardholder initiates a chargeback, where the cardholder would is reimbursed if there is suspect fraud and the proper authentication steps not done.