Download OpenAPI specification:Download
This is the Apcopay Integration Documentation for Developers and Software Engineers who need to process payments through Synthesis.
Our APIs accept and return JSON in the HTTP body and use standard HTTP response codes. You can interact with these APIs using your preferred HTTP/REST libraries, frameworks and languages.
API BaseUrl: https://payments.apcopay.tech/merchanttools
To perform test transactions without affecting live data, you can set the IsTest
is true
in each payload request.
When integrating with our payment processing services, you have two options to choose from: our Hosted Payment Page or our Direct Connect Solution.
Follow these 6 steps to quickly get started with our payment orchestrator.
HTTP Header Example
Authorization: Basic MzoxNDU0NDlmNGUyODI0NTUyYTNl…
/api/hpptoken/create
with a payload containing the necessary purchase details including the transaction type, amount,unique reference (for idempotency), order reference and currency.
In the payload make sure to include:
NOTE: You can see the required fields by your provider in the provider quick reference hereunder.
Sample response containing redirectURL
{
"pspid": 850907,
"token": "2ed7aa0a6fa04f3b8c3ab9fa4a4136ab",
"redirectUrl": "https://payments.apcopay.tech/merchanttools/api/Redirect/Loader?token=2ed7aa0a6fa04f3b8c3ab9fa4a4136ab",
"status": "PENDING",
"isSuccess": true,
"errorMessage": null
}
https://your.redirect.site/redirectpage?Pspid=123456&OrderReference=MerchantOrder2-158&Status=PROCESSED&Signature=wkt9a2BXoctSZGTxLZd2Nl0mhc9TYAsMIduzTGyi1E8%3d
NOTE: Use the appended query string information for the redirect user journey ONLY and NOT to update the transaction status in the backoffice. For updating the transaction status within the backoffice you should implement a listener (CallBackURL in request) which parses the webhook notification payload.
INFORMATION: Webhook notifications eliminate the dependence on the client or user-agent. If the user closes their browser, has poor internet connectivity, or experiences a timeout, the redirect may fail, leading to incomplete transactions or missed events. In contrast, webhooks ensure that the event notification is delivered directly to the intended server, reducing the chances of failure due to client-side issues.
INFORMATION: See Payment Notification in the webhook section.
Follow these 4 steps to quickly get started with our payment orchestrator.
NOTE: Any merchants accepting payment cards without utilising our hosted payment page must adhere to the Payment Card Industry Security Standards (PCI DSS), as this involves the transmission of full PAN details. Typically, compliance with SAQ D PCI is required in such cases.
/api/directconnect/execute
with a payload containing the necessary purchase details, including transaction type, amount, unique reference (for idempotency), order reference, and currency.
Ensure the payload includes the following:
NOTE: You can see the required fields by your acquirer in the section hereunder.
More information about authorising a card payment can be found here.
INFORMATION: If the card is subject to 3DS Authentication, the response will have a status of "Challenge" along with a "redirectURL" where the user should be redirected to complete the authentication. Upon completion of the authentication, a webhook notification will be sent with the result, as explained step 4.
INFORMATION: See Payment Notification in the webhook section.
Payment Provider | Hosted Payment Page | Direct Connect | Supported Transaction Types | Doc Link |
---|---|---|---|---|
Asia Bank Transfer | ✓ | ✗ | Purchase, Withdrawals | Here |
BOV PayOn | ✓ | ✓ | Authorisation, Caputre, Purchase, Void, Refund, Payouts, Recurring | Here |
Cashlib | ✓ | ✗ | Purchase | Here |
CPAPM | ✓ | ✗ | Purchase | Here |
eMerchantPay | ✓ | ✓ | Authorisation, Caputre, Purchase, Refund, Payouts, Recurring | Here |
eZeeWallet | ✓ | ✗ | Purchase, Withdrawal | Here |
HSBC Webpay | ✓ | ✓ | Authorisation, Caputre, Purchase, Refund, Void, Recurring | Here |
iCard | ✓ | ✓ | Authorisation, Caputre, Purchase, Refund, Void, Payouts, Recurring | Here |
JPAY - Automated Transfers | ✓ | ✗ | Purchase, Withdrawal | Here |
Mpay Cards | ✓ | ✓ | Purchase | Here |
Mpay Payment Options | ✓ | ✗ | Purchase, Withdrawal | Here |
Neosurf | ✓ | ✗ | Purchase, Withdrawal | Here |
Multibanco via Eupago | ✓ | ✗ | Purchase | Here |
Opay | ✓ | ✗ | Purchase, Withdrawal | here |
Orange Money (Liberia) | ✓ | ✗ | Purchase, Withdrawal | Here |
Papara via Pay Primo | ✓ | ✗ | Purchase, Withdrawal | Here |
Paysafecard via Trust | ✓ | ✗ | Purchase | Here |
Pay Primo Cards | ✓ | ✓ | Purchase | Here |
Poli via GateExpress | ✓ | ✗ | Purchase | Here |
Prompt Pay | ✓ | ✗ | Purchase | Here |
Trust | ✓ | ✓ | Authorisation, Caputre, Purchase, Refund, Void, Payouts, Recurring | Here |
Wamo | ✓ | ✓ | Authorisation, Caputre, Purchase, Refund, Void, Payouts, Recurring | Here |
Version | Methods | Change Details | Release Date |
---|---|---|---|
0.2.8 | Request Payment or Payout & HPP | Updated Payloads to contain airline data | 17/12/2024 |
0.2.7 | All Methods | Updated to include OPay and enhance example | 02/12/2024 |
0.2.6 | Get Account Payout Balance | Update Payout Balance Payload | 25/07/2024 |
0.2.5 | Get Account Payout Balance | Introduced Account Payout Balance Section | 24/07/2024 |
0.2.4 | All Methods | Streamlined Models and definitions | 29/06/2024 |
0.2.3 | Request Payment or Payout | Updated full payload requirements for ApplePay GooglePay objects | 22/05/2024 |
0.2.2 | Get Payment Response | Introduced DateFrom & DateTo epoc filtering criteria | 07/05/2024 |
0.2.1 | ExtendedPaymentNotification | Introduced Extended Payment Notification Webhook API reference | 08/04/2024 |
0.2.0 | Informational | Re-Structured API Documentation Informational Sections | 08/04/2024 |
This section contains all the operations permitted around the Hosted Page Functionality
Create a Hosted Payment Page Token
Signature required | string An HMAC SHA256 signature calculated over a range of request attributes which is included in the request headers. One MUST verify this Signature in the received responses, to validate the integrity and authenticity of the data exchanged between the parties involved in the payment process. https://docs.apcopay.com/docs/basic-auth-signature-calculation |
{- "TransactionType": "PURC",
- "Amount": 150,
- "Currency": "TRY",
- "OrderReference": "MPAY BANKPM TEST",
- "IsTest": false,
- "UniqueReference": "4b8da4f0-d3b4-44ae-8019-8c66905ffad7",
- "Routing": {
- "ForceBank": "MPAY"
}, - "Client": {
- "FirstName": "Apco",
- "LastName": "Test",
- "ClientAccount": "APCOPAY TEST",
- "Email": "johndoe@mail.com",
- "City": "Valletta",
- "IPAddress": "214.21.134.79",
- "DateOfBirth": "2001-08-28"
}, - "PaymentMethodData": {
- "ClientIdentificationNumber": "25490183248"
}
}
{- "PspID": 739005,
- "Token": "f86dff7b36aa4401bbb92c88280d6db4",
- "Status": "PENDING",
- "IsSuccess": true,
- "ErrorMessage": ""
}
This section contains all the operations permitted around the Server to Server Payment Functionality. NOTE:\ Some Operations would require the merchant to be PCI DSS Certified.
The methods under the POST Operation are operations that create a transaction from scratch and do not depend on a previous operation
Signature required | string An HMAC SHA256 signature calculated over a range of request attributes which is included in the request headers. One MUST verify this Signature in the received responses, to validate the integrity and authenticity of the data exchanged between the parties involved in the payment process. https://docs.apcopay.com/docs/basic-auth-signature-calculation |
A DirectConnectRequest Object consisting of all the attributes required to fulfil a Direct Connect integration
An 'authorisation' creates a validation on a card to verify its active status and ensure that there is a sufficient balance available to cover the requested amount. Proceed to process a capture ('CAPT') to capturing the funds.
Bad Request
Unauthorized
Business Validation Exception
{- "TransactionType": "PURC",
- "Amount": 100,
- "Currency": "EUR",
- "OrderReference": "123456",
- "PaymentCredentials": {
- "PaymentSource": "Card",
- "CardNumber": "5351772561457936",
- "CvV2": "483",
- "ExpMonth": "05",
- "ExpYear": "2029",
- "CardHolderName": "JOE BORG"
}, - "Client": {
- "ClientAccount": "APCOPAY TEST",
- "FirstName": "John",
- "LastName": "Doe",
- "Email": "apcopayintegrations@apcopay.com",
- "City": "Fakecity",
- "IPAddress": "127.0.0.1"
}, - "Routing": {
- "ForceBank": "PAYPRIMOCARDS"
}, - "BrowserDetails": {
- "UserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
- "JavaEnabled": true,
- "ScreenColorDepth": "1",
- "ScreenWidth": "1080",
- "ScreenHeight": "840",
- "TimeZone": "2",
- "AcceptHeader": "application/json",
- "BrowserLanguage": "en"
}, - "CallBackURL": "https:/https://www.yourURLhere.com/Listener",
- "UniqueReference": "4b8da4f0-d3b4-44ae-8019-8c66905ffad7",
- "IsTest": true
}
{- "PspId": 738220,
- "BankResponse": "Processed",
- "BankAccept": true,
- "CardToken": "9705594a-365d-4157-84a8-5af04bbb8507",
- "IsSuccess": true,
- "ErrorMessage": "Card Limit Exceeded"
}
The methods under the PUT Operation are operations that depend on previous operations and hence
Signature required | string An HMAC SHA256 signature calculated over a range of request attributes which is included in the request headers. One MUST verify this Signature in the received responses, to validate the integrity and authenticity of the data exchanged between the parties involved in the payment process. https://docs.apcopay.com/docs/basic-auth-signature-calculation |
A DirectConnectRequest Object consisting of all the attributes required to fulfil a Direct Connect integration
A 'capture' refers to the action of recording and finalizing a previously authorized transaction, and initiating the transferring of funds from the customer's account to the merchant's account.Can only be used on an active authorisation transaction.
Bad Request
Unauthorized
Business Validation Exception
{- "TransactionType": "CAPT",
- "Amount": 13,
- "IsTest": true,
- "UniqueReference": "6514441d-8abe-4d7b-9e0c-3aa386333b34",
- "PspID": 0
}
{- "PspId": 738220,
- "BankResponse": "Processed",
- "BankAccept": true,
- "CardToken": "9705594a-365d-4157-84a8-5af04bbb8507",
- "IsSuccess": true,
- "ErrorMessage": "Card Limit Exceeded"
}
This section contains all the operations permitted around the Card Tokenisation Functionality
The Tokenise Card operation is used to tokenise a new credit card
Bad Request
Unauthorized
Business Validation Exception
{- "clientAccount": "CliACC0102",
- "cardHolderName": "Joe Bloggs",
- "cardType": "VISA",
- "cardNumber": "4444444444444444",
- "expMonth": 11,
- "expYear": 2023
}
{- "CardsData": [
- {
- "CardToken": "181767b2-bcfe-40bd-959f-cf78072c2bf8",
- "CardHolderName": "string",
- "MaskedCard": "454647******1312",
- "ExpMonth": 479000,
- "ExpYear": 8019,
- "CardLastUsed": 1695108453
}
], - "IsSuccess": true,
- "ErrorMessage": "No records found"
}
The Delete Tokenised Card operation is used to delete a Card Token.
Bad Request
Unauthorized
Business Validation Exception
{- "IsSuccess": true,
- "ErrorMessage": "No records found"
}
The Get Tokenised Cards operation is used to retrieve all the Tokenised Cards linked with a Client Account
Bad Request
Unauthorized
Business Validation Exception
{- "CardsData": [
- {
- "CardToken": "181767b2-bcfe-40bd-959f-cf78072c2bf8",
- "CardHolderName": "string",
- "MaskedCard": "454647******1312",
- "ExpMonth": 479000,
- "ExpYear": 8019,
- "CardLastUsed": 1695108453
}
], - "IsSuccess": true,
- "ErrorMessage": "No records found"
}
This endpoint is used to retrieve the transaction information
Bad Request
Unauthorized
Business Validation Exception
{- "AttemptNumber": 1,
- "SentDateTime": 1720789324,
- "UDF": {
- "DefinedField1": "ValueToDefinedField1",
- "...": "string",
- "DefinedFieldN": "ValueToDefinedFieldN"
}, - "TransactionToken": "729ca722364f47448a94bb27a3399317",
- "OrderReference": "35738128",
- "Status": "Processed",
- "AuthCode": "123456",
- "CardInput": true,
- "PspId": 767867,
- "Currency": "EUR",
- "Amount": 11.09,
- "BankMessage": "Insufficient Funds",
- "CardNumber": "654838******5152",
- "CardExpiry": "02/2025",
- "CardHolderName": "John Doe",
- "CardCountry": "Italy",
- "CardType": "VISA",
- "CardToken": "9705594a-365d-4157-84a8-5af04bbb8507",
- "Acquirer": "EMP",
- "Email": "joebloggs@mailinator.com",
- "BankErrorCode": "B2",
- "UniqueReference": "00a00569-7b7d-43fa-a5d0-4aeb673c5a25",
- "ClientAccount": "CliAcc01002",
- "Is3DS": false
}
This endpoint is used to retrieve the Payout Balance information.
Bad Request
Unauthorized
{- "Balances": {
- "Amount": 100,
- "Currency": "EUR"
}, - "AccountSpecificData": {
- "IBAN": "IT60X0542811101000000123456"
}
}
This is the webhook call sent to notify the merchant the outcome of the payment attempt
This is the transaction status JSON payload which provides details around the transaction
{- "AttemptNumber": 1,
- "SentDateTime": 1720789324,
- "UDF": {
- "DefinedField1": "ValueToDefinedField1",
- "...": "string",
- "DefinedFieldN": "ValueToDefinedFieldN"
}, - "TransactionToken": "729ca722364f47448a94bb27a3399317",
- "OrderReference": "35738128",
- "Status": "Processed",
- "AuthCode": "123456",
- "CardInput": true,
- "PspId": 767867,
- "Currency": "EUR",
- "Amount": 11.09,
- "BankMessage": "Insufficient Funds",
- "CardNumber": "654838******5152",
- "CardExpiry": "02/2025",
- "CardHolderName": "John Doe",
- "CardCountry": "Italy",
- "CardType": "VISA",
- "CardToken": "9705594a-365d-4157-84a8-5af04bbb8507",
- "Acquirer": "EMP",
- "Email": "joebloggs@mailinator.com",
- "BankErrorCode": "B2",
- "UniqueReference": "00a00569-7b7d-43fa-a5d0-4aeb673c5a25",
- "ClientAccount": "CliAcc01002",
- "Is3DS": false
}
This is the webhook call sent to notify the merchant the outcome of the payment attempt containig the UserInputs Object as an extension to the default Payment Notification. UserInputs Object is a DYNAMIC structure which is populated based on additional data which is supplied by the user during the payment process during the Apcopay HPP flow. This Object is transmitted only if the ShowUI Feature Flag in the HPP request is set to TRUE.
This is the transaction status JSON payload which provides details around the transaction.
{- "AttemptNumber": 1,
- "SentDateTime": 1695108453,
- "UDF": {
- "DefinedField1": "ValueToDefinedField1",
- "...": "string",
- "DefinedFieldN": "ValueToDefinedFieldN"
}, - "TransactionToken": "729ca722364f47448a94bb27a3399317",
- "OrderReference": "ord001-13523",
- "Status": "Processed",
- "AuthCode": "21335232385",
- "CardInput": true,
- "PspId": 736928,
- "Currency": "EUR",
- "Amount": 9.99,
- "BankMessage": "Insufficient Funds",
- "CardNumber": "654838******5152",
- "CardExpiry": "02/2025",
- "CardHolderName": "John Doe",
- "CardCountry": "CHE",
- "CardType": "VISA",
- "CardToken": "9705594a-365d-4157-84a8-5af04bbb8507",
- "Acquirer": "TRUEVO",
- "Email": "daniel.borg@test.com",
- "BankErrorCode": "B2",
- "UniqueReference": "00a00569-7b7d-43fa-a5d0-4aeb673c5a25",
- "ClientAccount": "CliAcc01002",
- "Is3DS": false,
- "UserInputs": {
- "Client": {
- "Email": "joe.bloggs@testjb.com",
- "ClientAccount": "CliAcc01002",
- "FirstName": "Joe",
- "LastName": "Bloggs",
- "Country": "MLT",
- "MobileNo": "00441234567",
- "Street": "High Street",
- "City": "MagicCity",
- "ZIPCode": "BGGC1234",
- "State": "UK",
- "DateOfBirth": "2924-12-31"
}, - "...": "string",
- "PaymentMethodData": {
- "AdditionalProviderParameter1": "IBAN:IT60X0542811101000000123456",
- "AdditionalProviderParameterN": "CISNumber:9232233"
}
}, - "ProviderOriginatingData": {
- "ProviderOriginatingData1": "ValueToAlternativePaymentMethodParameter1",
- "...": "anyOtherValue",
- "ProviderOriginatingDataN": "ValueToAlternativePaymentMethodParameterN"
}
}