Table of Contents

Introduction

APEXX makes technical integrations to all the payment suppliers you need and presents them as a single, comprehensive JSON API. All API calls are performed using standard HTTPS GET and POST requests. You can explore our full developer documentation here.



Basic Principles

The following steps are necessary for a payment to be processed through the APEXX Gateway and apply to both conventional card payments and alternative payment methods:

  1. Initiate the payment request
  2. Capture the payment method details
  3. Authenticate the transaction
  4. Authorise and/or capture the payment
  5. Process the card issuer’s response



Connecting to APEXX

Authentication

Your Implementation Manager will provide you with an API key, which is used to identify your application to the APEXX server. This key needs to be included in the header of every HTTPS call to the APEXX API. You will receive separate keys for the Sandbox and Live environments.


HTTPS Connection Security

To keep cardholder data secure and adhere to industry best practices, APEXX require at least TLS 1.2 for all HTTPS connections.


Currency Precision

The APEXX platform supports all ISO 4217 currencies. Currency precision can thus range from zero to three decimals. For example, USD amounts have two digits to the right of the decimal, and Japanese yen (JPY) have none. To support this dynamic currency precision and to prevent rounding errors, no decimal points are used in the amount field of the API requests. The APEXX platform will determine the decimal position based on the value transmitted in the currency field.

For example, an amount of £14.08 GBP will be stored and presented as 1408. In contrast, a transaction amount of ¥1,000 JPY is stored as 1000.


Environments

Apexx provides two different environments for your integration:


EnvironmentEndpointDescription
Sandboxhttps://sandmgw.apexxfintech.com/This is a test environment providing you with access to the full API feature set. Transactions will have no financial impact. The sandbox environment is intended for functional testing only. Please do not use it for load/scripted testing.
Productionhttps://production.apexxfintech.com/This is the live environment which APEXX will configure to meet your specific requirements. Transactions will have financial impact.



Testing

Test Card Numbers

Your Implementation Consultant will provide you with a set of test card numbers that are valid for your specific integration.


Test Cases

You can find a collection of test cases for direct payment scenarios here, and for hosted payment page scenarios here.

Adjust the following parameters in the payment request message to suit your business needs:


ParameterValueResult
create_tokenfalseNo token will be returned for the card number supplied
create_tokentrueA token will be returned for the card number supplied
capture_nowfalseTransaction will be authorised only
capture_nowtrueTransaction will be authorised and captured in the same request
three_ds_requiredfalseCustomer will not be redirected to 3DS verification page
three_ds_requiredtrueCustomer will be redirected to 3DS verification page
merchant_referenceplease 121Force a “declined” response


Sample request collection

Your Implementation Manager will provide you with a collection of sample requests for the Sandbox environment. This will be preconfigured to work with your APEXX test account.



Merchant Setup in APEXX

Organisations

An organisation represents the full scope of all transactions and related data. Merchant organisations can be set up in APEXX as individual entities or as a hierarchically structured group. Child organisations typically represent the subsidiaries or sub-merchants within the group. Whereas data is shared between the parents and children within an organisation, it cannot be shared with organisations not in the hierarchy.


Accounts

The different cashflows received by a merchant are aggregated on accounts. An account is linked to a specific currency, (sub)organisation and payment processor. The account setup could be structured by e.g. region, payment method or revenue type; depending on the different cash flows the merchant wishes to track.


General Architecture


What impact does the organisation and account structure have?

When deciding the structure of their organisation as it should be set up in APEXX, merchants should consider the following areas:


Reporting

The reporting scope for transactions can be set to the child organisation, or one of the parent organisations

When reporting by account, the scope of the report will be limited to the organisation the account is associated with


User Access Control

User access is granted at organisation level. Users' visibility can be restricted to a single child organisation, or extended to a parent and all of its child organisations. 


Hosted Payment Page Customisation

APEXX supports limited HPP customisation at organisation level. At present, an organisation can be associated with a single customisation template. Merchants wishing to maintain multiple brands with different design requirements can dynamically send CSS styling data in the transaction_css_template field in the hosted payment page request, or consider using Client Side Encryption (CSE) instead of the Hosted Payment Page. 


API Authentication

Every organisation has an API key, which can be used to authenticate API requests for the organisation itself, but also any child organisations in the hierarchy. Merchants therefore have the choice of using 

  • only the API key associated with the ultimate parent, or
  • the API keys associated with the intermediate parents, or 
  • the individual API keys associated with the child organisations 


Client Side Encryption (CSE) and HMAC Signature Key Generation

Public keys for both CSE and HMAC signature generation are managed at organisation level. Currently, a single key per organisation is supported. 



Capturing Card Details

The APEXX payment gateway supports two types of integration for payment processing:


Direct Integration

In a direct integration, raw card data including card number, CVV and expiry date are submitted along with details of the order. Processing a payment using this method requires a higher level of Payments Card Industry (PCI) compliance to be maintained by the merchant (typically, SAQ-D self assessment). However, it also allows you to maintain a high level of control over the design of the payment details collection page, as well as the payment process itself.


Direct Payment Flow


Direct Integration - Sample Payment Request

createCardTransaction

{"account": "435fe3946b104e7783756fff3b80e4f0",
"amount": 15000,
"capture_now": false,
"card" : {
    "card_number" : "5186150000002228",
    "cvv" : "123",
    "expiry_month" : "02",
    "expiry_year" : "23",
    "token" : "" 
},
"customer_ip": "192.168.1.135",
"dynamic_descriptor" : "Demo Merchant 1",
"merchant_reference" : "ORDER 0001",
"recurring_type": "first",
"user_agent": "Mozilla/5.0 (Windows; U; Windows NT 6.1; en-GB;rv:1.9.2.13) Gecko/20101203 Firefox/3.6.13 (.NET CLR 3.5.30729)",

"three_ds":{
"three_ds_required": false
    }
}

Because direct payment requests contain sensitive card data, they can be further protected by encryption. Further information about how to encrypt the Create Card Transaction Request message can be found here in our API documentation.


Hosted Payment Page

Where the merchant wishes to avoid the exposure of raw card data to their website and there is no requirement to store cardholder data, card details can be captured on APEXX’ own secure payment page. Upon receipt of the payment request, APEXX returns a unique URL which can be used in either a full page or an iframe redirect. Once the payment attempt has been processed, the customer is redirected to the page specified in the return_url parameter in the payment request, and the result of the transaction can be displayed.

Using the hosted payment page allows merchants to avoid onerous PCI compliance requirements as well as the technical challenges associated with maintaining their own payment page and storing card data.


Hosted Payment Page Flow


Hosted Payment Page Customisation

Certain attributes of the APEXX payment page can be customised to give it a look and feel that is consistent with your website. This includes the font and background colours. A full list of customisable elements can be viewed in our API reference. Your Implementation Manager will ask you about your preferred styling options during the configuration process.


Example 1: Payment Form


Example 1: Payment Form with Link to Terms and Conditions

iFrame Redirect

An iFrame allows you to embed the fields from the APEXX payment page on your own webpage. This results in a more consistent user experience, as the customer remains on a page hosted on the merchant’s domain. Optionally, you can also include an order summary in the iFrame.



Hosted Payment Page Security

Merchants can optionally implement HMAC signature verification to ensure the authenticity and data integrity of the HPP-redirect return URL sent in the hostedPaymentPage response from APEXX.



Hosted Payment Page - Sample Payment Request

hostedPaymentPage

{
"account": "435fe3946b104e7783756fff3b80e4f0",
"amount": 15000,
"capture_now": true,
"dynamic_descriptor" : "Demo Merchant 1",
"merchant_reference" : "ORDER0001",
"return_url" : "https://qaigate.apexxfintech.com/mgw/return",
"webhook_transaction_update" : "https://dev.apexxfintech.com/",
"transaction_type" : "first",
"locale":"en_GB",
    "billing_address":{
        "first_name": "Joe", 
        "last_name": "Bloggs", 
        "email": "joe.bloggs@customerco.com", 
        "address": "16", 
        "city": "London", 
        "state": "London", 
        "postal_code": "155", 
        "country": "GB", 
        "phone":77123456
        }
}


Tokenisation

Tokenisation is the practice of encrypting a card number and returning a token to the merchant. The token can be used to process the initial transaction as well as subsequent recurring or stored-card payments. The partially masked card number and expiry date are returned alongside the token. This enables the merchant and the customer to identify the supplied card without viewing its full number. Tokenisation allows merchants to process these payments without further interaction from the customer or consumer. As only a token is stored instead of full card data, the merchant may benefit from less stringent PCI compliance requirements (SAQ-A or SAQ-A-E).

Tokens can be used in a variety of scenarios:

  1. You can request a token from APEXX in the initial payment request. The token can then be stored instead of the raw card data. This applies to both the direct and hosted payment page method.

  2. You can send a request to convert card data into a token independently of a payment request. The token can then be stored until it is needed.

Because tokenisation requests contain sensitive card data, they can be further protected by encryption. Further information about how to encrypt the Create Token Request message can be found here in our API documentation.

The token has no expiration date and can be used multiple times. Merchants belonging to the same parent organisation will be able to access tokens created within that organisation.


Direct Recurring Payments with Tokenisation




Taking Payments

Authorisation and Capture

Taking a payment involves two steps: authorisation and capture.

The purpose of the authorisation is to verify that the card details entered are valid and that the cardholder’s bank permits the transaction. If, for example, the issuing bank determines that the customer does not have sufficient funds in their account, or it identifies the transaction as potentially fraudulent due to unusual spending patterns or merchant locations, it will decline the authorisation request.

A successful authorisation places a temporary hold on the requested amount. The funds remain in the shopper’s account, but are reserved and cannot be used for other purchases. An authorisation typically lasts for 5 days if it is not captured or cancelled.

The capture signals the completion of a transaction. At this point, the funds are deducted from the shopper’s account and will be held by the acquiring bank until the merchant requests settlement.

Requests for capture can be submitted either in full or for partial amounts up to and including the full amount of the authorisation.

Authorisation requests and responses are exchanged between the merchant and cardholder’s bank in real time, whereas capture requests are collected by the merchant and transmitted to the acquiring bank in daily batches.

The authorisation is initiated by sending a createCardTransaction or hostedPaymentPage request. The capture_now parameter in the payment request determines whether the transaction is to be captured automatically (capture_now = “true”), or whether the transaction should initially only be authorised (capture_now = “false”). If only an authorisation is taken, an additional API call will be necessary to capture the funds.

The reason_code and status values in the authorisation response indicate whether the transaction has been successful and its current status.


Payment Status Codes

StatusDescription
AUTHORISEDThe transaction has been authorised by the acquirer and can now be processed. A transaction in AUTHORISED status can either be captured or cancelled.
CAPTUREDThe transaction has been queued for processing. This request can be cancelled.
SETTLEDThe transaction has been successfully processed. The transaction can now be refunded.
REFUNDEDThe transaction has been successfully refunded and will not allow any further processing unless only a partial refund was requested.
FAILEDEither the transaction has been rejected by APEXX, or an error has occurred during transaction processing, most likely because the transaction request is malformed or inconsistent.
DECLINEDThe transaction request has been declined by the issuer.
CANCELLEDThe transaction authorisation has been cancelled and will not allow any further processing.


  • A reason_code of “0” indicates a successful transaction. The status of the transaction will be either AUTHORISED, CAPTURED, or REFUNDED

  • A status of DECLINED will coincide with one of the following ISO 8583 reason codes. Where an issuing bank is using its own list of reason codes, APEXX will map the code internally and send the ISO code in the API response instead.


Reason Codes

CodeMessage
0Successful approval/completion or that VIP PIN verification is valid
1Refer to card issuer
2Refer to card issuer, special condition
3Invalid merchant or service provider
4Pickup
5Do not honor
6General error
7Pickup card, special condition (other than lost/stolen card)
8Honour with identification
9Request in progress
10Partial approval
11VIP approval
12Invalid transaction
13Invalid amount (currency conversion field overflow) or amount exceeds maximum for card program
14Invalid account number (no such number)
15No such issuer
16Insufficient funds
17Customer cancellation
19Re-enter transaction
20Invalid response
21No action taken (unable to back out prior transaction)
22Suspected Malfunction
25Unable to locate record in file, or account number is missing from the inquiry
28File is temporarily unavailable
30Format error
343DS Authentication failed
353DS Issuer is unable to respond
363DS Error
41Merchant should retain card (card reported lost)
43Merchant should retain card (card reported stolen)
51Insufficient funds
52No checking account
53No savings account
54Expired card
55Incorrect PIN
57Transaction not permitted to cardholder
58Transaction not allowed at terminal
59Suspected fraud
61Activity amount limit exceeded
62Restricted card (for example, in country exclusion table)
63Security violation
65Activity count limit exceeded
68Response received too late
75Allowable number of PIN-entry tries exceeded
76Unable to locate previous message (no match on retrieval reference number)
77Previous message located for a repeat or reversal, but repeat or reversal data are inconsistent with original message
78’Blocked, first used’—The transaction is from a new cardholder, and the card has not been properly unblocked.
80Visa transactions: credit issuer unavailable. Private label and check acceptance: Invalid date
81PIN cryptographic error found (error found by VIC security module during PIN decryption)
82Negative CAM, dCVV, iCVV, or CVV results
83Unable to verify PIN
85No reason to decline a request for account number verification, address verification, CVV2 verification; or a credit voucher or merchandise return
86Card Expiry Date invalid
87AVS check failed
91Issuer unavailable or switch inoperative (STIP not applicable or available for this transaction)
92Destination cannot be found for routing
93Transaction cannot be completed, violation of law
94Duplicate transmission
95Reconcile error
96System malfunction, System malfunction or certain field error conditions
B1Surcharge amount not permitted on Visa cards (U.S. acquirers only)
N0Force STIP
N3Cash service not available
N4Cashback request exceeds issuer limit
N7Decline for CVV2 failure
P2Invalid biller information
P5PIN change/unblock request declined
P6Unsafe PIN
Q1Card authentication failed
R0Stop payment order
R1Revocation of authorization order
R3Revocation of all authorizations order
XAForward to issuer
XDForward to issuer
Z3Unable to go online
  • A status of FAILED will be matched by one of the following error codes:

Error Codes

CodeMessage
APC_001Transaction in progress
APC_002Error processing transaction
APC_003Account configuration invalid
APC_004IP not allowed
APC_005Function not supported by acquirer
APC_006Order details do not match request
APC_007Malformed request
APC_008Merchant account suspended
APC_009Currency not supported
APC_010Malformed request
APC_011Gateway error - please contact support
APC_012Unable to connect to Acquirer
APC_015Encryption error
APC_016Duplicate request
APC_017Acquirer settlement error
APC_018AVS/CVC not supported by Acquirer
APC_019Payment method not supported
APC_020Unable to authorise transaction
APC_021Request expired
APC_022Test card not supported
APC_023Issuing country not supported
APC_024Action invalid or missing
APC_025Amount invalid or missing
APC_026Card number invalid or missing
APC_027Expiry date invalid or in the past
APC_028Card issue number invalid or missing
APC_029CVV invalid or missing
APC_030Billing name invalid or missing
APC_031Billing address invalid or missing
APC_032Billing postcode invalid or missing
APC_033Email invalid or missing
APC_034Phone number invalid or missing
APC_035Country code invalid or missing
APC_036Merchant reference invalid or missing
APC_037Remote address invalid or missing
APC_038Redirect URL invalid or missing
APC_039Callback URL invalid or missing
APC_040Merchant data invalid or missing
APC_041Origin invalid or missing
APC_042Duplicate delay invalid or missing
APC_043Item details invalid or missing
APC_044Tax details invalid or missing
APC_045Discount value invalid or missing
APC_0463DS details invalid or missing
APC_0473DS pares invalid or missing
APC_048Capture now missing or invalid
APC_049Order date invalid or missing
APC_050Card start date invalid or missing
APC_051Confirmation Number invalid
APC_052CSRF token invalid or missing
APC_053Token invalid or missing
APC_054Data invalid or missing
APC_055Captcha invalid or missing
APC_056Error processing request
APC_057Attempts exceeded
APC_0583DS Authentication failed
APC_0593DS Issuer is unable to respond
APC_0603DS Error
APC_061Try again later
APC_062Invalid DATETIME format
APC_063Authorisation code missing or invalid

Cancel Authorisation

It is common practice for transactions to be captured only once an order has been fulfilled. If the order cannot be fulfilled (for example, due to a stockout) then it is cheaper for the merchant to cancel the authorisation than to process a refund.

Capturing only part of a transaction amount will still result in the release of the full authorisation amount. Therefore, cancellation requests are only sent when there is nothing to capture and will automatically apply to the full transaction amount.


Unused Authorisations

Please note that APEXX will automatically cancel authorisations that have not been captured or cancelled by the merchant after 7 days.


Cancel Captured Transaction

In a situation where the authorisation and capture requests were sent separately it is possible to cancel the transaction after capture using the cancelCapturedTransaction request. This references the capture_id returned in the captureCardTransaction response.

Cancellation of a capture removes the transaction from the daily settlement batch and voids the underlying authorisation. It is therefore only possible if the captured transaction has not yet been submitted for settlement, i.e. on the same business day.

Once the capture has been cancelled, the authorisation cannot be re-captured. A new authorisation must be made. 


Cancel Statuses

Cancel statuses are returned in the cancellation response.


StatusDescription
CANCELLEDThe transaction has been cancelled and do not allow any further processing.
FAILEDThe transaction has been rejected by us, or an error has occurred during transaction processing, most likely because the transaction request is malformed or inconsistent.

3DS options

3D Secure is the payment authentication standard for e-commerce card transactions adopted by Visa, MasterCard, JCB, and AMEX.


Card Scheme3DS Version
VisaVerified by Visa
MasterCardMasterCard® SecureCode
JCBJ-Secure
AMEXSafeKeySM

The purpose of 3D Secure is to protect the merchant in cases where a customer denies knowledge of or involvement in a specific transaction. Using 3D Secure shifts the liability to provide evidence of fraudulent use of card data from the merchant to the cardholder and the issuing bank.


3D Secure can be implemented in both hosted and direct integrations. 3DS checks are performed after the card details have been collected, prior to sending the authorisation request. The shopper is prompted to enter all or part of a password to prove that they are the true owner of the card. Once the password has been verified, the transaction is sent to the issuing bank for authorisation.


Where a merchant and cardholder set up a recurring payment plan (e.g. a subscription schedule), only the first transaction will need to be 3DS verified. Recurring transactions are flagged using the recurring_type field in the createCardTransaction request.


In APEXX, the merchant’s 3DS preference (i.e. whether to check if the card is 3DS enabled and redirect the customer to the verification page) can be set at account level as well as at transaction level.

  • Setting a 3DS requirement at account level will force the customer to use a 3DS verifiable card. The transaction will only proceed to the authorisation step if the 3DS enrolment check identifies that the card is enrolled in the scheme.
  • Setting a 3DS requirement at transaction level will allow the customer to bypass the 3DS verification if the card is not enrolled. The transaction will proceed directly to the authorisation step if the 3DS enrolment check identifies that the card is enrolled in the scheme.



Account requires 3DSAccount does not require 3DS
Transaction requires 3DS3DS verification. Transaction fails if card is not enrolled.3DS verification. Transaction does not fail if card is not enrolled.
Transaction does not require 3DS3DS verification. Transaction fails if card is not enrolled.No 3DS verification

3DS message flow in merchant environment with direct payments


3DS message flow in hosted payment page merchant environment


APEXX 3DS Inspector

Since 14 September 2019, new European Union rules came into force that impose stricter authentication requirements on payments taking place between a payer and a payee both located in the EEA. Whereas the timing of enforcement by the respective local authorities will vary between EEA member states, merchants are expected to have embarked on the SCA implementation process at this point. The regulations apply to transactions in which both the issuer and acquirer are located in an EEA member state.


Transactions where either the issuer or acquirer is located outside the EEA are considered “one leg out” and do not fall within the scope of SCA rules. As the SCA process is only available to EEA card holders and even more cumbersome for the shopper than the traditional 3DS procedure, there is a certain risk that they will abandon the purchase before completing payment. If the risk of cancelled purchases outweighs the risk of fraud and charged-back transactions, the merchant may therefore decide to bypass the 3DS authentication in cases where it is not mandatory.


APEXX provides merchants with the option to verify the country the payer’s card was issued in. The merchant can then use this data to help decide if their application should request an enrolment check or not.


The APEXX 3DS Inspector is based on the following API call:


Bin Check Sample Request:

{
    "organisation": "44f5587916604e7bbd340670cf80fba8",
    "bin": "454222647623"
}

Bin Check Sample Response:

{
    "scheme": "MASTERCARD",
    "type": "DEBIT",
    "brand": "PREPAID BUSINESS",
    "bank": {
    "name": "R. RAPHAEL & SONS PLC"
    },
    "country": {
    "name": "UNITED KINGDOM",
    "alpha2": "GB",
    "alpha3": "GBR",
    "numeric": 826
    }       
}

Post Authorisation Checks

Some data such as the result of an AVS (Address Verification Service) or CVV/CVC (Card Verification Value) check is only returned in the authorisation response from the issuing bank. These post-authorisation checks are used in fraud screening by payment gateway. A transaction that was authorised by the issuing bank may still be blocked by the gateway as a result of a single critical check being failed, or due to a high risk score calculated from a number of contributing factors.


Address Verification (AVS)

In an AVS check, the numerical address data supplied during the transaction is cross-referenced against the issuing bank’s cardholder records, and any discrepancies are flagged. AVS checks the numerical values in the first line of the address and in the postcode.

For example,

  • Address Line 1: 450 High Road - AVS checks if the numbers ‘4’, ‘5’ and ‘0’ are submitted in the Address Line 1 field of the authorisation request

  • Postcode: N17 5RT - AVS checks if the numbers ‘1’, ‘7’, and ‘5’ are submitted in the Postcode field of the authorisation request

The result of the AVS check is returned in the avs_result field of the createCardTransaction response. Please note that AVS result codes vary slightly between card schemes and processors. They give an indication of whether a full or partial match was detected, or if the check failed for some other reason.

It is the merchant’s responsibility to decide how to act on the AVS result; i.e. to allow the transaction to continue processing or to send a cancel/void request for the authorisation.

AVS is fully supported in the USA, Canada and United Kingdom, but may not give consistent results in many other billing countries.

APEXX will send the billing address details in the createCardTransaction and hostedPaymentPage requests. Some address fields may be mandatory for certain acquirers. Please speak to your Implementation Manager about the specific requirements for your integration.


CVV/CVC (Card Verification Value/Card Verification Code)

The name for card verification codes varies by card scheme:


NameCard Scheme
CVV2Visa
CVC2MasterCard
CIDAmerican Express, Discover
CVN2China Union Pay

The CVV/CVC is a three-digit code printed on or just to the right of the signature panel on the back of a Visa or MasterCard. For American Express cards, the CID consists of four digits and is printed on the front of the card just above the embossed card number. Unlike the card number and expiry date, the CVV is not stored on the card’s magnetic stripe or chip and therefore cannot be captured by point-of-sale terminals and similar equipment. Its purpose is to secure online and MOTO transactions, similar to the way a PIN secures a face-to-face transaction. PCI-DSS Requirement 3.2 considers the CVV sensitive authentication data and prohibits its storage. The APEXX API allows the CVV to be passed through in the createCardTransaction request, but it is not stored in the database. The CVV is only required for initial transactions, not for recurring payments.


During a CVV check, the card verification code supplied during the transaction is cross-referenced against the issuing bank’s records. Please note that CVV result codes vary between card schemes and processors. They give an indication of whether the CVV supplied was identified as a match, or if the check failed for some other reason.


It is the merchant’s responsibility to decide how to act on the CVV check result; i.e. to allow the transaction to continue processing or to send a cancel/void request for the authorisation.


Recurring Transactions (Subscriptions)

Recurring (subscription) e-commerce payments are merchant-initiated and are therefore submitted without a CVV and without undergoing 3DS authentication. This is generally done after an initial transaction has been successfully processed and passed the required post-authorisation checks. 


Recurring transactions are flagged using the recurring_type parameter  in the createCardTransaction request.


Hosted payment page requests are always considered initial transactions, as the merchant cannot know which card the customer will use for the payment. 


In order to manage recurring payments in a merchant setup using the hosted payment page, the merchant must request a token in the hostedPaymentPage request and store it. To process the recurring payment, the merchant sends a createCardTransaction request and inserts the token in the card data block. 



Paying Out Funds

Funds can flow from the merchant to the customer in the form of refunds or Original Credit Transfers (OCTs).


Refunds

Refunds are sent as an update to an original purchase transaction using the refundCardTransaction request type. You can specify an amount that represents a full or partial refund, but you cannot issue a refund that exceeds the original transaction amount. If you need to process e.g. a goodwill payment, you will need to use the createdCreditTransaction request type.


Refund requests can only be accepted after the original payment transaction has been submitted to the acquirer for settlement (this normally happens nightly, but timings vary between acquirers). This is because the bank cannot pay the cardholder back for a transaction that has not even left their account yet. Refund attempts that were made before settlement has taken place will incur a DECLINED response.


If you need to reverse a payment on the same day it was made then you need to use the cancelCapturedTransaction request instead. This will remove the transaction from the settlement batch and void the preauthorisation at the same time.


Refund Statuses

Refund statuses are returned in the refund response.

  • A reason_code of “0” indicates a successful transaction. The status of the transaction will be either REFUNDED or FAILED.
  • A status of FAILED will be matched by one of the error codes listed above


StatusDescription
REFUNDEDThe transaction has been successfully refunded and do not allow any further processing.
FAILEDThe transaction has been rejected by us, or an error has occurred during transaction processing, most likely because the transaction request is malformed or inconsistent.
DECLINEDThe transaction request has been declined by the processor.

Original Credit Transactions (OCT) / Payment Transactions (PT)

Card payouts are referred to as Original Credit Transactions by Visa and as Payment Transactions by Mastercard. Most commonly, they are used by merchants in the gambling sector to pay out winnings. It is possible to use a tokenised card number in the request. 


Original Credit Transaction - Sample Payout Request

createCreditTransaction

{   
"original_transaction_id": "",
"account": "99a02186917d4143ba3014331239a9be",
"organisation": "",
"currency": "52",
"amount": 100,
"dynamic_descriptor": "Apexx Demo Merchant",
"merchant_reference": "Apexx Demo Merchant Payout 0001",
"card": {
        "card_number": "4176661000001015",
        "cvv": "677",
        "expiry_month": "03",
        "expiry_year": "24",
        "token": ""
        },
"customer": {
        "customer_id": "",
        "last_name": "Customer",
        "date_of_birth": "",
        "postal_code": "15",
        "account_number": ""
        },
"customer_ip": "192.168.1.135",
"user_agent": "Mozilla/5.0 (Windows; U; Windows NT 6.1; en-GB;rv:1.9.2.13) Gecko/20101203 Firefox/3.6.13 (.NET CLR 3.5.30729)",
"webhook_transaction_update": "",
"billing_address": {
    "first_name": "Test",
    "last_name": "Customer",
    "email": "test.customer@mydomain.com",
    "address": "123",
    "city": "London",
    "state": "",
    "postal_code": "23",
    "country": "GB",
    "phone": 7359501048
    },
    "shopper_interaction": "ecommerce"
}

The payout request can be cancelled using the cancelCreditTransaction request type, provided it has not yet been progressed to settlement.


OCT Statuses

OCT statuses are returned in the OCT response.

  • A reason_code of “0” indicates a successful transaction. The status of the transaction will be either AUTHORISED, CAPTURED, DECLINED or FAILED.
  • A status of DECLINED will be matched by one of the reason codes listed above
  • A status of FAILED will be matched by one of the error codes listed above


StatusDescription
AUTHORISEDThe transaction has been authorised by the acquirer, and can now be processed. AUTHORISED transaction status can either be captured or cancelled.
CAPTUREDThe transaction has been queued for processing. This request can be cancelled.
FAILEDThe transaction has been rejected by us, or an error has occurred during transaction processing, most likely because the transaction request is malformed or inconsistent.
DECLINEDThe transaction request has been declined by the issuer.
CANCELLEDThe transaction authorisation has been cancelled and will not allow any further processing.

Surcharging


Surcharge Inspector

Surcharges can be legally applied to corporate card transactions, or to transactions in which the payment card used was issued outside the EEA (i.e. an EU member state, Iceland, Norway or Liechtenstein). The APEXX Surcharge Inspector allows merchants to accurately determine a card’s country of issue as well as the account type associated with it. This data is then used by APEXX to verify if the card is eligible for surcharging. Where surcharging is permitted on the card, APEXX calculates the surcharge to be applied to a transaction, up to the maximum amount permitted by card scheme rules and regulations.

Rates are calculated for the merchant based on the assumptions that are made for the payment. The assumptions include: e-commerce transaction, regionality, 3D Secure verification in use and AVS check in use.

The APEXX Surcharge Inspector is a standalone product and billed separately. Please contact your APEXX sales representative for further details.

The APEXX Surcharge Inspector supports two types of API calls:

  • Bin check - returns details about the card type, scheme and issuing bank based on the first six digits of the card number
  • Surcharge request - to request verification and application of a surcharge to a specific transaction


Bin Check Sample Request:

{
    "organisation": "44f5587916604e7bbd340670cf80fba8",
    "bin": "222647"
}

Bin Check Sample Response:

{
    "scheme": "MASTERCARD",
    "type": "DEBIT",
    "brand": "PREPAID BUSINESS",
    "bank": {
    "name": "R. RAPHAEL & SONS PLC"
    },
    "country": {
    "name": "UNITED KINGDOM",
    "alpha2": "GB",
    "alpha3": "GBR",
    "numeric": 826
    }       
}

Surcharge Sample Request:

{
    "organisation_id": "6c18a82fe5a2439b922522570c9abc37",
    "transaction_currency": "GBP",
    "transaction_amount": 1000,
    "trans_orig_loc_country": "GB",
    "transaction_merchant_reference": "RS122820181418",
    "surcharge_merchant_reference": "SC122820181418",
    "settlement_currency": "INR",
    "capture_now": true,
    "acquirer_country_code": "GB",
    "card": {
        "card_number": "2226471234564562",
        "token": ""
    },
    "channel": "ecommerce"
}

Note: APEXX will always round down the final amount in the surcharge fee response based on the decimals supported for the currency.

To ensure the security of transferred data we support only encrypted data transfer for the surcharge request.


Webhooks

Webhooks

Webhooks notify you of any event occurring on the transactions that you process via APEXX. You can select whether you want to be notified for the transactions update and where you want us to send them to. This allows you to stay up to date on the transactions even after a customer is no longer on your site.


Setting Up Webhooks

The webhook endpoint can either be configured against a specific account or be sent in the webhook_transaction_update field of the createCardTransaction (for direct integrations) or hostedPaymentPage request. Webhook URLs included in a transaction request will override any URL set on the account.

The presence of a webhook URL will prompt APEXX to send out transaction updates whenever the status of a transaction changes. The merchant will need to provide an application that processes the incoming webhook events and returns a response message to APEXX. If APEXX does not receive a message indicating that the event update was successfully received, it will attempt to resend the update at a later point in time.



Alternative Payment Methods (APMs)


Post-Invoice Payment Methods

Post-invoice payment methods allow recipients to pay for goods after they have been delivered. Shoppers avoid the risk of non-delivery of items, and generally only need to pay for the goods they keep. Late payment or installment options may additionally be available to them. This makes post-invoice payments an attractive option for purchases where there is a high rate of item returns, such as clothing. The merchant still gets paid at the time of purchase, with the payment operator funding the difference and taking on the risk of non-payment. Technically, post-invoice payment methods are a form of debt factoring as the merchant sells a receivable to the payment operator and the process is transparent to the end customer.

Merchants must balance the cost of offering this service against the potentially higher conversion rates they can achieve by making open-invoice payment options available. Consumer payment preferences vary widely from country to country, with after-delivery payment types enjoying particularly high adoption rates in Germany, Austria and the Benelux countries.


Afterpay

In the initial payment request, approval is obtained for the payment by a specific customer and shopping basket. Afterpay apply fraud checks and credit scoring, and verify the address supplied by the customer.

The details of the transactions are submitted directly to APEXX by the merchant application. There is no hosted payment page (indirect option) available.

The payment request contains a number of fields specific to Afterpay such as product, pricing and tax details, billing and delivery address information, and (optionally) risk scoring data.

Afterpay will evaluate the request and return an Accepted/Rejected response with a reason code to APEXX. APEXX will forward this response to the merchant application for display to the shopper.


PayPal

To process a PayPal payment, APEXX creates an order using PayPal's Order API. The buyer can then settle the amount using their PayPal balance, or another permitted payment method. 


TABLE OF CONTENTS