Introduction


The Adflex payment API is a comprehensive set of RESTful API based web services which 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.

There are three groups of APIs: Core, PayPage, and Payment Links.

Core
A collection of low-level payment APIs not bound by any session state mechanism.


PayPage
A session-based API set designed to satisfy PCI DSS compliance. Combine the PayPage API with our JavaScript widget to capture card details outside your system, and inside our PCI compliant system.


Payment Links
An API allowing you to create links, which can be sent to a customer in order to request a payment. Messages can be configured which will be sent to the payer by Adflex, or you can implement your own solution to send URLs to your customers.

You can use these API groups together to create a PCI compliant, hybrid-payment process. e.g. Capturing and tokenising a card using the PayPage API, followed by authorisation and settlement using the Core API.



PCI DSS (Payment Card Industry Data Security Standard) Compliance


Adflex is a fully PCI DSS compliant payment processor.

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 will bring you within scope of PCI-DSS SAQ (Self Assessment Questionnaire) A-EP or PCI DSS SAQ D compliance.



Getting Started


To get started, create an Adflex sandbox account.

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, including javascript code to create the JWT authentication token.


Calling the API


The Adflex RESTful API uses a JSON format for both requests and responses. HTTP is used to transmit requests and responses to and from our servers. The following table summarises the HTTP methods used in conjunction with the resource endpoints detailed in our API documentation.

HTTP Verb CRUD Description
POST
Create
Used for creating resources.
GET
Read
Used for retrieving resources.
PUT
Update
Used for updating resources.
DELETE
Delete
Used for deleting resources.

Every request must be transmitted using HTTPS, to encrypt your customers' data.



API Authentication


In order to ensure the security of our APIs, we have implemented a robust authentication methodology.

Each API request must contain a new JWT (JSON web token), signed with a Secret Key. The merchant creates the JWT, and the Secret Key itself is not included in the request. You will be provided with this secret key (which is created by Adflex) when you sign up with a new merchant account.

You must treat the Secret Key as a secret - securely encrypted on your system and never transmitted.

The Secret Key is accompanied by an Access Key. The Access Key is submitted in the header of the API HTTP request, along with the JWT authentication token.

Keys
Key Name Description Created By Prefix Max Length (characters) Resource Lifetime API AHPP Transmission
secretKey Secret Key Adflex sk_* 4000 Supplied by Adflex during sign-up Static: ~1 year Y N Never transmitted!
accessKey Safe Pointer to Secret Key Adflex ak_* 4000 Supplied by Adflex during sign-up Static: ~1 year Y N API request header
authenticationToken API Authentication Customer Bearer * none JWT created by merchant Dynamic: per api call; max 240 mins Y N API request header
sessionID AHPP Session Adflex sn_* 4000 /ahpp/session Dynamic: per AHPP transaction; max 240 mins Y Y Merchant JS library


Creating a JWT Token


Many programming languages offer extensive support to help you implement JWT authentication in your system - a list of libraries has been compiled at https://jwt.io/.

Create the header for the JWT token - all elements are mandatory.

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

Description: alg Algorithm (HS256). typ Type.

Create the body for the JWT token - all 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 request. aud The fully qualified resource endpoint for the current request. For example: "https://api-test.adflex.co.uk/v2/transactions/authorisation". iss Issuer; value must always be "Adflex". iat Issued time; please use NumericDate format as per RFC 7519.

You must encode the secret key into a byte array using UTF-8, before using it to sign the token.

Once you have created the JWT token, submit it in the "Authorization" header of the request as "{JWTtoken}".



The Authentication Flow


The Authentication Flow


Processing a Payment


When a customer makes a payment using a Credit or Debit card, a complex sequence of operations is fired off. Just a few seconds after requesting the payment, you'll receive a response indicating whether or not the transaction has been Authorised, but during that short period an extensive series of security checks, communications and analysis of the trustworthiness of the transaction have all taken place. This whole process happens quietly behind the scenes.

In the majority of cases, a transaction will be approved quickly and the payment will be made rapidly into the merchant's account. However, various factors may complicate a transaction. For example, a customer can dispute a transaction - leading to a "Chargeback", if they are successful. When an unusual situation such as this occurs, a broader understanding of what is happening can help. We are here to guide you through this process as efficiently and as painlessly as possible.

Depending on the type of environment you are processing payments in, the exact steps taken may differ slightly. Here are some of the environments in which you can process payments using Adflex:

  • Cardholder not present
  • Mail order
  • Telephone order
  • eCommerce
  • Application-initiated eCommerce

In payment processing, the full process to complete a card payment usually takes about three working days, during which it passes through distinct stages, such as Authorisation, Clearing and Settlement.

Authentication
This is the first phase of a transaction. In this step, the "Issuer" of the card will attempt to confirm that an authorised user of the card has initiated the transaction. If the payment is being made in an eCommerce environment, EMV 3D Secure is used to authenticate the transaction.


Authorisation
If the card issuer is satisfied that the transaction should take place, the transaction amount is 'ring-fenced' on the payee's account. At this point, there is no transfer of funds between the cardholder and the merchant, but the spending limit on the card will be reduced by the transaction amount.


Settlement
This is the final phase, in which authorised funds are transferred from the cardholder to the merchant.



Authentication


If the transaction is being made as part of an eCommerce transaction, you must first authenticate the transaction using EMV 3D Secure, which is a mandatory additional layer of fraud security implemented by the card schemes, before you request an authorisation.

3D Secure adds an additional step to the online checkout process. The cardholder is redirected to a page hosted by the card issuer, where they are challenged on their identity.

In order to implement this in your own solution, you must send a request to the /threedsecure/authenticate endpoint using the Adflex API. The response will contain the URL for the 3DS page, at which the payer can validate the transaction.

Please note that if you are using our Hosted Pay Page solution, we will conduct this step for you when we capture the payer's card details.

Capture Mode
When you authorise a payment, you must populate the transactionDetails.captureMode with the environment in which you are performing the transaction (e.g. Cardholder not present, eCommerce, etc.).

Note: This is not to be confused with the 'capture' process as used in payments taking place in the USA, which relates to part of the settlement process.



Authorisation


The first step you need to take in order to execute a card payment, is to request an authorisation.

This can be done by calling/ahpp/authorisation/token if you are using card details you have securely tokenised via our AHPP (Adflex Hosted Pay Page) solution, or /transactions/authorisation if you are directly submitting card details to our Core API.

When we receive your request, Adflex's bespoke systems will process the data you have submitted and initiate communication between the Acquiring Bank (the merchant's bank account), the Issuing Bank (the cardholder's bank account), and the Card Scheme. Based on the responses we receive and the configuration within your account, you will then receive a response indicating whether the payment has been authorised or declined.

If you request an authorisation for a transaction using the Adflex API and receive a response containing a responseObject.statusCode of "Authorised", and an responseObject.transactionDetails.authCode number, the transaction will be honoured and paid.

Here are two circumstances in which there may be a risk of not getting paid:

  • An extended time (typically > 10 days) between authorising and settling the card.
  • When a cardholder initiates a chargeback - if successful, the cardholder will be reimbursed if there is suspect fraud or if the proper authentication steps have not been completed.


Authorisation Outcomes


When you submit a request for a payment to be authorised, you will usually receive a response containing a statusCode of "Authorised".

If this is the case, the transaction was successful, and the settlement process will then be able to take place, depositing the payment amount into your merchant bank account.

However, depending on a several factors, you may receive a different response. Here are some of the statuses you may receive when attempting to authorise a payment:

Authorised

The merchant has received approval from the card issuer, and the requested funds have now been ringfenced but not yet deducted (settled) from the cardholder's account. Following an authorised transaction, you can confirm to the user that the payment has been successful.


Declined

The card issuer has refused the authorisation request. Following a decline, a second attempt to authorise the transaction is unlikely to be approved. Instead of returning the user to the payment screen in order to try again, we suggest that you direct them to either use a different card or contact their card issuer for further information on why the transaction has been declined.


Error

If you receive an error status, please refer to the subCode and statusMessage properties of the response object, as they will be able to provide you with further information on why an error has occurred.


Referral

A referral is also known as a soft decline, in which the issuing bank requires further information from the cardholder to authorise the payment. Typically, a referral is treated similarly to a decline by payment applications. Referral statuses are now mostly obsolete as 3D Secure has largely replaced the process.



Reversals


The reversal process is designed to reverse (remove) the reserved (ring-fenced) 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. We expect this to be introduced within the next few months, once we have fully implemented the current PSD2 SCA and Credentials on File compliance work.

You can request a reversal of a transaction by calling the /transactions/reversal endpoint in the Adflex API.



Settlement


'Settlement' is the process of transferring an authorised payment's funds from the cardholder's account into the merchant's bank account.

In order to settle a transaction which you have previously authorised, please call the /transactions/settle endpoint in the Adflex API.

The Adflex API can be used to implement two types of settlement models.

Authorise and Settle
An Authorisation followed by an Adflex invoked automatic settlement at the end of the day.

To operate this model, you must call the /ahpp/authorisation/token or /transactions/authorisation endpoint using the Adflex API, taking care to set the transactionDetails.processMode property to "AuthAndSettle".


Authorise Only
An Authorisation without automatic settlement.

To operate this model, you must first call the /ahpp/authorisation/token or /transactions/authorisation endpoint using the Adflex API, taking care to set the transactionDetails.processMode property to "AuthOnly". If the card issuer is satisfied that the transaction should take place, the transaction amount is 'ring-fenced' on the payee's account.

When you wish to settle the transaction, the you must call the /transactions/settle endpoint. If the settle endpoint is never called, the authorisation for the transaction will naturally expire after a period of time; typically between five and ten working days, depending on the card issuing bank.



Refunds


Refunds are managed by the merchant. By making an API request to the /v2/transactions/authorisation/token endpoint with the property transactionDetails.type set to "Refund", you can execute a refund.

A cardholder is unable to initiate a refund for a transaction made from their account.



'Delayed Shipment and Charge' Model


There are two ways in which you can operate a delayed shipment and charge model (using the Adflex Hosted PayPage).

Option 1
Reserve, without deducting, the funds from the card (ring-fence the charge value at the point of order):


  1. Create an Adflex Hosted PayPage Session, by making a request to the /ahpp/session endpoint exposed by the Adflex API, 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 within your customer-facing website to capture and tokenise the card details.
  3. Immediately after the card is captured, call the /ahpp/authorisation/token API endpoint, with the property transactionDetails.processMode set to "authOnly".
  4. Later, at the moment of dispatch, call the /transactions/settle API endpoint to request the transfer (or 'settlement') of the ring-fenced funds from the payee's card into your account. Please note that you should ideally request the settlement within 4-10 days of the original "authOnly" transaction.

The advantage for the merchant, is that there is a high probability of receiving the ring-fenced funds on dispatch and settlement.

The disadvantage for the cardholder is that their card spend limit will be reduced for the period prior to the dispatch of the goods, but the funds will only be taken from their account once you have dispatched the goods. This is commonly referred to as a "shadow" on the cardholder's card.

If, for any reason, the merchant is unable to dispatch the goods (e.g. if the order cancelled or the required stock is unavailable), the card-holder's spending limit will continue to be reduced until the original Authorisation naturally expires. This is not a limitation of Adflex's systems, but a consequence of how card payments are handled within the UK.

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


  1. Create an Adflex Hosted PayPage Session, by sending a request to the /ahpp/session endpoint exposed by the Adflex API, with an amount.value of "0", 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 within your customer-facing website to capture and tokenise the card details.
  3. Immediately after the card is captured, call the /ahpp/authorisation/token API endpoint, with the property transactionDetails.type set to "AccountVerification", and amount.value set to "0".
  4. Later, at the point of dispatch, call the /transactions/authorisation/token API endpoint using the previously tokenised card, with the amount.value set to the required transaction value.
  5. Immediately afterwards, call the/transactions/settle API endpoint to request the transfer (or 'settlement') of the funds from the payee's card into your account.

The disadvantage for the merchant is a possibility that the card has insufficient funds to pay for the shipment.

The advantage for the cardholder is that their card spend limit will not be reduced for the period prior to the dispatch of the goods, and the funds will only be taken once the goods have been dispatched.



Card Security Options


AVS is a Cardholder not Present (CNP) fraud detection process, based on passing the address information captured during the checkout process directly to the cardholder's issuing bank for verification. Once checked the issuer then returns a code, indicating their level of certainty regarding the address's validity. This code is then passed through our rules-based checking system and will contribute towards a 'transaction acceptance score'. Please note that AVS does not work as reliably for transactions made with corporate cards, where the card's registered address often differs to that of the cardholder.

CSC (also referred to as CVC or CVV) is a three to four-digit security code that should be known only to the cardholder. We will request this code during the checkout process, and submit it to the cardholders issuing bank for verification. The response is then passed through our rules-based checking system and will contribute towards a 'transaction acceptance score'. A failed CSC transaction should never be accepted!

When is an AVS/CSC check performed?
Adflex performs AVS/CSC checks when you request an authorisation. AVS/CSC rules are agreed at the time of signing up with Adflex and are configured at the merchant account level. If the outcome is to reject the transaction, Adflex will attempt to execute a reversal to cancel the transaction.

We will apply these rules across all transactions processed within the merchant account, unless you choose to manually override them for a specific transaction.

EMV 3D Secure (also referred to as 3D Secure or 3DS) is a mandatory cardholder authentication service implemented by the card schemes, in order to reduce fraud in eCommerce environments. The advantage of 3D Secure is that as a merchant, once you have carried out a successful authentication of the cardholder for a specific transaction using 3D Secure, you are no longer liable for this transaction should a fraud claim arise. The number of chargeback cases raised against you should therefore reduce significantly.



Payment Links


It's never been easier to convert unsecured telephone payments into secure online transactions. Send a payment link to your customer via email or text message and get paid anytime, anywhere. Payment Links takes your customer to a secure hosted payment page where they can pay for orders and outstanding invoices by debit, credit or purchasing card.

Transactions will use 3D Secure to authenticate the cardholder, resulting in lower merchant service charges and reduced fraud. All links are customisable with your company's branding and logo, and available in multiple languages. For recurring payments, we can also securely keep the Card on File (CoF) using tokenisation.

There are two ways to create a payment request link.

API
Make a call to the /paymentlinks endpoint using the Adflex API, to generate a payment link from your Website or back office ERP.


My Adflex
Request a payment link via the My Adflex portal. This feature will allow you to create and send a payment link without writing a single line of code

There are two ways to send a payment link.

Non-Delegated
Adflex sends the payment link directly to your customer from the Adflex domain. Submit a POST request to the /paymentlinks endpoint using the Adflex API, setting the sendLinkMode property to "NonDelegated".


Delegated
You send the link directly to the customer using your domain. Submit a POST request to the /paymentlinks endpoint, setting the sendLinkMode property to "Delegated".

You can also use Payment Links to securely tokenise a customer's card for future use. To use this feature, configure the payPageConfiguration.tokenLifetime object in the request to enable the "Save Card" checkbox on the pay page, specifying the token TTL (time to live) in days. You will then be able to reuse the card details for future transactions, using the returned token as a proxy for the card details.



Security Best Practice


When handling payments within your system, you must take care to build a solution with security implications at the forefront of concerns. There are several publicly available resources which can provide technical advice and details on common security mistakes and exploits.

We recommend following the guidelines published by OWASP to protect both your company and your customers from fraud and loss of data.

  • The OWASP Top Ten is a list of OWASP's top ten most critical security risks to web applications. We strongly recommend that you take steps to mitigate these potential vulnerabilities when building your solution.
  • OWASP's Cheat Sheet Series is a set of simple good practice guides for application developers. This is a useful resource for building secure applications, offering guidance for specific aspects of your solution or technology of choice.
  • The OWASP Web Security Testing Guide provides helpful advice on testing web applications to ensure a high level of security.

Please ensure you avoid the following design errors when building your payment solution.

Failing to use HTTPS

Always use HTTPS to secure your website. All of Adflex's APIs use HTTPS for both requests and responses, to prevent sensitive communications from being intercepted by third parties.


Transmitting or failing to keep your API secret key encrypted

Your security credentials for the API must be kept secure and encrypted on your system. At no point should you ever transmit these to a third party, or serve them to a browser via your website.

When you access the API, use the security key to create a JWT token which is submitted as a header to authenticate the request.

When using Adflex's Hosted Pay Page, it is necessary to call our API from the customer's browser. In this case, authentication takes place via session IDs and tokens which are passed to the browser, so it is not necessary to send your security credentials to the browser.


Passing sensitive information to the browser

Never send sensitive data (especially relating to personal or card details) to the customer's browser. Process sensitive data on your server rather than in the browser. Once you have transmitted information to a customer's browser, it is out of your control, and you are reliant on the customer's environment for security.



MID (Merchant ID) Selector Rulebase


The MID (Merchant ID) Selector Rulebase is a feature available to your Adflex Gateway Account. It enables a MID to be selected based on one or a combination of the following conditions;

  • BIN Range
  • Card Scheme
  • Value Range
  • Enhanced Datatype
  • Country Code
  • Currency Code
  • Card Number Regex Pattern

MID Selector Rules are configured by Adflex based on the Merchants use cases when the account is initially set up.

Individual MID Selector Rules can be chained (logical ORed / ANDed) together into a single Rule set.

Each Rule set is tested in turn, based on its priority number (lowest is run first) If the Rule outcome is matched, then the transaction is bound to the rules assigned mapped MID.

If none of the Rule sets are matched, then the transaction will be bound to the default MID.

The MID Selector Rulebase is applicable to the following API resources;

  • paypage .js widget (ahpp)
  • /transactions/authorisation


Transaction Rulebase


The Transaction Rulebase is a feature built into your Adflex Gateway Account. It enables a transaction to be accepted or rejected based on the MID and the 3DS, CVC and AVS responses.

Each rule set is grouped by

  • Transaction Value Lower
  • Transaction Value Upper

And tests against the following rules;

  • Allow Non-3DS Cards
  • Allow non 3DS Merchants
  • Allow 3DS Failures
  • Allow 3DS MPI/Server Failures
  • Allow Non-Matched CVC
  • Allow Non-Matched Address
  • Allow Partial Matched Address
  • Allow Non-Matched Postcode
  • Allow Partial Matched Postcode

For example;
If a transaction AVS Postcode=NotMatched and Allow Non-Matched Postcode is not ticked, then the transaction will be forced to status Declined.

Another example;
If a transaction AVS Postcode=NotMatched and Allow Non-Matched Postcode is not ticked, then the transaction will be forced to status Declined.

In the Adflex Paypage solution, these rules can be overridden on a transaction by transaction basis using the following /ahpp/session properties;

  • "tdsCheck"
  • "cvcCheck"
  • "avsCheck"

Refer to the /ahpp/session documentation for the available options

Note that the 3DS, CVC and AVS response values are returned in the API irrespective of the rule actions. Except for when using the Paypage to creating a token only. In this case, you will need to set the /ahpp/session request property “accountVerification”: true and to call /ahpp/accountverification/ at the end of the step to retrieve the values.



Postman


To get you up and running quickly, we recommend that you use a free tool called Postman. With Postman you can execute API calls, using a collection of predefined method templates created by Adflex.

Once you have downloaded and installed Postman, please import the following two files, via the User Interface, to configure your Adflex API test environment.

  • The Postman Environment file provided when you register for an Adflex Sandbox account, containing your secret, access keys and adflex account code.
  • 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.