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:

Initiate the payment request
Capture the payment method details
Authenticate the transaction
Authorise and/or capture the payment
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:

Environment	Endpoint	Description
Sandbox	https://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.
Production	https://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:

Parameter	Value	Result
create_token	false	No token will be returned for the card number supplied
create_token	true	A token will be returned for the card number supplied
capture_now	false	Transaction will be authorised only
capture_now	true	Transaction will be authorised and captured in the same request
three_ds_required	false	Customer will not be redirected to 3DS verification page
three_ds_required	true	Customer will be redirected to 3DS verification page
merchant_reference	please 121	Force 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:

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.
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

The status of a transaction is returned in API responses from APEXX, as well as in webhooks. See the list of APEXX Transaction Statuses for further details.

Card Payment	Cancel	Capture	Refund
AUTHORISED	CANCELLED	CAPTURED	REFUNDED
CAPTURED	FAILED	FAILED	FAILED
FAILED		DECLINED	DECLINED
DECLINED
3DS_REQUIRED
CHARGEBACK*
CHARGEBACK_REVERSAL*
SETTLED*

* only where reconciliation data has been integrated

Reason Codes

Accepted Transactions

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

Declined Transactions

A status of DECLINED will coincide with one of the ISO 8583 reason codes listed in the APEXX Reason Codes table
APEXX translates the reason code received from the acquiring bank and will send an ISO 8583 response in the API response.
Reason codes for DECLINED transactions will always be returned with a 200 HTTP status code. A HTTP code of 200 indicates that a payment request has received an approve or decline response from the issuer

Failed Transactions

A status of FAILED may occur if APEXX cannot validate the API request received from the merchant, or from a processing error
See APEXX Card Validation Errors and APEXX Card Processing Errors
Note that the "CUP Validation" and "CUP Processing" error tables are for use with domestic China Union Pay processing in China only
Card validation errors may be returned with a 400, 401 , or 500 HTTP status code
Card processing errors are always returned with a 412 HTTP status code. A HTTP code of 412 indicates that the transaction failed and did not receive an approve or decline response from the issuer

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.

Status	Description
CANCELLED	The transaction has been cancelled and do not allow any further processing.
FAILED	The 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 Scheme	3DS Version
Visa	Verified by Visa
MasterCard	MasterCard® SecureCode
JCB	J-Secure
AMEX	SafeKeySM

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 3DS	Account does not require 3DS
Transaction requires 3DS	3DS verification. Transaction fails if card is not enrolled.	3DS verification. Transaction does not fail if card is not enrolled.
Transaction does not require 3DS	3DS 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:

Name	Card Scheme
CVV2	Visa
CVC2	MasterCard
CID	American Express, Discover
CVN2	China 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

Status	Description
REFUNDED	The transaction has been successfully refunded and do not allow any further processing.
FAILED	The transaction has been rejected by us, or an error has occurred during transaction processing, most likely because the transaction request is malformed or inconsistent.
DECLINED	The 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

Status	Description
AUTHORISED	The transaction has been authorised by the acquirer, and can now be processed. AUTHORISED transaction status can either be captured or cancelled.
CAPTURED	The transaction has been queued for processing. This request can be cancelled.
FAILED	The transaction has been rejected by us, or an error has occurred during transaction processing, most likely because the transaction request is malformed or inconsistent.
DECLINED	The transaction request has been declined by the issuer.
CANCELLED	The 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 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

Introduction
Basic Principles
Connecting to APEXX
Testing
Merchant Setup in APEXX
Capturing Card Details

APEXX API Reference Print

Table of Contents

Introduction

Basic Principles

Connecting to APEXX

Authentication

HTTPS Connection Security

Currency Precision

Environments

Testing

Test Card Numbers

Test Cases

Sample request collection

Merchant Setup in APEXX

Organisations

Accounts

What impact does the organisation and account structure have?

Capturing Card Details

Direct Integration

Direct Integration - Sample Payment Request

Hosted Payment Page

Hosted Payment Page Customisation

iFrame Redirect

Hosted Payment Page Security

Hosted Payment Page - Sample Payment Request

Tokenisation

Taking Payments

Authorisation and Capture

Payment Status Codes

Reason Codes

Cancel Authorisation

Unused Authorisations

Cancel Captured Transaction

Cancel Statuses

3DS options

APEXX 3DS Inspector

Post Authorisation Checks

Address Verification (AVS)

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

Recurring Transactions (Subscriptions)

Paying Out Funds

Refunds

Refund Statuses

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

Original Credit Transaction - Sample Payout Request

OCT Statuses

Surcharging

Surcharge Inspector

Webhooks

Webhooks

Setting Up Webhooks

Post-Invoice Payment Methods

Afterpay

PayPal

Related Articles