Apcopay Synthesis (0.2.8)

Download OpenAPI specification:Download

This is the Apcopay Integration Documentation for Developers and Software Engineers who need to process payments through Synthesis.

Getting Started

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.

  • Hosted Payment Page: This option redirects customers to a secure payment page hosted by us. It’s easy to set up, requires minimal development effort, and ensures that sensitive payment data is handled securely by our systems.
  • Direct Connect: This option allows for direct transaction processing from your server, offering more flexibility and control. However, it may require you to comply with PCI DSS (Payment Card Industry Data Security Standard) requirements to ensure the security of payment data.

Follow these 6 steps to quickly get started with our payment orchestrator.

1. Sign Up

    Get in touch with our business development team so that you can be provided with an overview of our solutions and get the best guidance for the right configuration that is best fit for your platform and business.

2. Setup API Credentials

  • Generate a Base64-encoded string: Concatenate your ClientID and ClientSecret with a colon (e.g., "ClientID:ClientSecret") and convert the resulting string to Base64 encoding. This encoded string will serve as your credentials for Basic Authorization.
  • Include the Authorization header: In each API request, add an "Authorization" header to the request headers. The value of this header should be "Basic" followed by a space and the Base64-encoded credentials generated in the previous step.

HTTP Header Example

Authorization: Basic MzoxNDU0NDlmNGUyODI0NTUyYTNl…

3. Create a Hosted Payment Page Token
To create a HPP token, make a POST request to /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:
  • RedirectionURL - A redirectURL to which the user should be redirected after completing the payment process.
  • CallBackURL - A CallbackURL where webhook notifications are sent, providing updates on the transaction status."
  • Signature - HMAC SHA256 signature that is calculated over a range of request attributes which is included in the request headers. Click here for more information.

NOTE: You can see the required fields by your provider in the provider quick reference hereunder.


More information about creating a HPP token can be found here.

4. Redirect Client for Payment
Once the above method is invoked you should parse the payload, check that the `isSuccess` is `true` and redirect the client to the redirectURL supplied in the payload

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
}    

5. Redirecting the Client back to Your Site
Once the payment journey is complete the Payment Platform will redirect the user to the RedirectionURL supplied in the original Hosted Payment Page Token request also appending the PspID, OrderReference, Status and Signature in the url query string.

  • The same signature algorithm needs to be used as highlighted in section 2 however in this context it is computed on the PspID, OrderReference and Status attributes.
  • The signature needs to be always calculated and verified for request tempering before proceeding with any additional business logic.

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


6. Parsing the Transaction Webhook Notification
Once the payment journey is complete, our platform will send a webhook notification containing the payment outcome at the supplied CallBackURL in the HPP Token Request. Similiar to step 4, a secure hash is supplied however in this context it set in a Signature attribute within the HTTP Header.
  • The signature needs to be always calculated and verified for request tempering before proceeding with any additional business logic.
  • The same signature algorithm needs to be used as highlighted in section 2 over the webhook JSON payload.

INFORMATION: See Payment Notification in the webhook section.


Follow these 4 steps to quickly get started with our payment orchestrator.

1. Sign Up

  • Get in touch with our business development team so that you can be provided with an overview of our solutions and get the best guidance for the right configuration that is best fit for your platform and business.

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


2. Setup API Credentials

  • Generate a Base64-encoded string: Concatenate your ClientID and ClientSecret with a colon (e.g., "ClientID:ClientSecret") and convert the resulting string to Base64 encoding. This encoded string will serve as your credentials for Basic Authorization.
  • Include the Authorization header: In each API request, add an Authorization header to the request headers. The value of this header should be "Basic" followed by a space and the Base64-encoded credentials generated in the previous step.
HTTP Header Example Authorization: Basic MzoxNDU0NDlmNGUyODI0NTUyYTNl…

3. Authorising a Card
To authorize a card, make a POST request to /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:

  • RedirectionURL: The URL to which the user will be redirected after completing the payment process.
  • CallBackURL: The URL where webhook notifications will be sent, providing updates on the transaction status.
  • Signature: An HMAC SHA256 signature calculated over a range of request attributes and included in the request headers. For more details, click here.
  • Browser Details: The BrowserDetails object capturing browser fingerprinting attributes required for 3DS Authentication.
  • Payment Information: The card or token details required to authorize and process the payment. This could include a physical payment card, virtual token, or digital payment method stored on a mobile device.

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.


4. Parsing the Transaction Webhook Notification
  • Once the acquirer has responded with the bank result, our platform will send a webhook notification containing the payment outcome at the supplied CallBackURL in the Authorisation Request.
  • A secure hash is supplied however in this context it set in a Signature attribute within the HTTP Header.

    • The signature needs to be always calculated and verified for request tempering before proceeding with any additional business logic.
    • The same signature algorithm needs to be used as highlighted in section 2 over the webhook JSON payload.

    INFORMATION: See Payment Notification in the webhook section.

    For Integration Best Practices and implementation guides kindly follow the guidelines available at the following link.

    Provider Quick Reference

    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

    Change Log

    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

    Hosted Payment Page

    This section contains all operations permitted around the Hosted Page Functionality

    Create a Hosted Payment Page Token

    Create a Hosted Payment Page Token

    SecurityClientCredentials
    Request
    header Parameters
    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

    Request Body schema: application/json
    required
    TransactionType
    required
    string (HostedPaymentPageRequestTransactionType)

    Supported Transaction Types

    Enum: "AUTH" "PURC"
    Currency
    required
    string

    Specifies the currency code for the transaction. 3-letter alpha (A-to Z) currency code ISO 4217

    Amount
    required
    number

    Indicates the transaction amount to be processed.

    OrderReference
    required
    string

    Merchant Unique Transaction Reference.This may be used for reconcilliation. It is recommended that the identifier is unique to the transaction.

    UniqueReference
    required
    string <uuid>

    Unique identifier generated for each and every attempt when performing a transaction

    RedirectionURL
    required
    string

    Specifies the URL where the user should be redirected after the transaction.

    CallBackURL
    required
    string

    Specifies the URL where callback notifications or responses should be sent.

    FailRedirectionURL
    required
    string

    Indicates the URL where the user should be redirected in case the transaction fails.

    Language
    string
    Default: "en"

    Sets the ISO 639-1 language code for the Hosted Payment Page

    IsTest
    boolean

    Specifies if the transaction will be routed to the sandbox environment. Not passing this parameter will default to the live environment

    object (HostedPaymentPageRequestRouting)

    This Captures the HostedPaymentPage Routing Object

    object (AntifraudObject)

    This model captures the HPP AntiFraud parameters

    required
    object (ClientObject)

    A model capturing the client information

    object (HostedPaymentPageRequestUDF)

    User-Defined Data. Any additional information you want to be passed back to you after payment completion.

    object (ConfigurationObject)

    This model captures the HPP UI/UX custimisation parameters

    object (HPPPaymentMethodDataObject)

    This model is intended to capture additional attributes required by the specific Bank and/or Alternate Payment Method APM

    object (AirlineDetailsObject)

    This object encapsulates flight-related, passenger, and reservation details for airline related payment transactions. The entire JSON object needs to be implemented however supplying the minimum required values as per Acquirer specific guidelines. NOTE: Empty string values should be supplied for non required values

    Responses
    200
    400
    401
    default
    post/api/hpptoken/create
    Request samples
    application/json
    {
    • "TransactionType": "PURC",
    • "Amount": 150,
    • "Currency": "EUR",
    • "OrderReference": "OrderRef0011235",
    • "FailRedirectionURL": "https://yourURLhere.com/FailRedirect/",
    • "IsTest": true,
    • "UniqueReference": "4b8da4f0-d3b4-44ae-8019-8c66905ffad7",
    • "Client": {
      }
    }
    Response samples
    application/json
    {}

    Payment Operations

    This section contains all operations permitted around the Server to Server Payment Functionality. NOTE:\ Some Operations would require the merchant to be PCI DSS Certified.

    Request Payment or Payout

    The methods under the POST Operation are operations that create a transaction from scratch and do not depend on a previous operation

    SecurityClientCredentials
    Request
    header Parameters
    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

    Request Body schema: application/json

    A DirectConnectRequest Object consisting of all the attributes required to fulfil a Direct Connect integration

    One of:

    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.

    TransactionType
    required
    any
    Default: "AUTH"

    Specifies the Transaction Type for this operation. In the contect of a Payment Authorisation it is an "AUTH"

    Enum: "AUTH" "PURC" "ORIGINALCREDIT"
    Currency
    required
    string

    Specifies the currency code for the transaction. 3-letter alpha (A-to Z) currency code ISO 4217

    Amount
    required
    number

    Indicates the transaction amount to be processed.

    OrderReference
    required
    string

    Merchant Unique Transaction Reference.This may be used for reconcilliation. It is recommended that the identifier is unique to the transaction.

    UniqueReference
    required
    string <uuid>

    A unique identifier must be provided in this parameter to identify the request and prevent duplicate processing. It is recommended that you utilize a GUID or similar mechanism.

    Language
    string
    Default: "en"

    Sets the ISO 639-1 language code for the Hosted Payment Page

    RedirectionURL
    required
    string

    Specifies the URL where the user should be redirected after the transaction.

    CallBackURL
    required
    string

    Specifies the URL where callback notifications or responses should be sent.

    FailRedirectionURL
    string

    Indicates the URL where the user should be redirected in case the transaction fails. If not set the redirectionUrl is used instead.

    IsTest
    boolean

    Specifies if the transaction will be routed to the sandbox environment. Not passing this parameter will default to the live environment

    object (DirectConnectRequestRouting)

    Routing Object intended to Capture all routing related configuration

    object (AntifraudObject)

    This model captures the HPP AntiFraud parameters

    required
    object (ClientObject)

    A model capturing the client information

    object (HostedPaymentPageRequestUDF)

    User-Defined Data. Any additional information you want to be passed back to you after payment completion.

    object (HPPPaymentMethodDataObject)

    This model is intended to capture additional attributes required by the specific Bank and/or Alternate Payment Method APM

    required
    object (DirectConnectRequestBrowserDetails)

    BrowserDetails Object capturing Browser Finger Printing attributes required for ThreeDSecureAuthentication

    object (DirectConnectRequestThreeDSecureAuthentication)

    ThreeDSecureAuthentication Object capturing ThreeDSecure Authentication attributes. This is supported from select Acquirers.

    required
    any

    This refers to any form of information or token used to authorize and process payments, whether it's a physical credit card, a virtual token representing a credit card, or a digital payment method stored on a mobile device

    PspId
    integer

    The previously processed transaction reference (PspID) to be used as reference for Repeat Purchase or Repeat Authorization Transactions on MIT Scenarios

    object (AirlineDetailsObject)

    This object encapsulates flight-related, passenger, and reservation details for airline related payment transactions. The entire JSON object needs to be implemented however supplying the minimum required values as per Acquirer specific guidelines. NOTE: Empty string values should be supplied for non required values

    Responses
    200
    400

    Bad Request

    401

    Unauthorized

    default

    Business Validation Exception

    post/api/directconnect/execute
    Request samples
    application/json
    {
    • "TransactionType": "AUTH",
    • "Currency": "EUR",
    • "Amount": 12.23,
    • "OrderReference": "MerchantOrder1",
    • "UniqueReference": "6514441d-8abe-4d7b-9e0c-3aa386333b34",
    • "Language": "it",
    • "IsTest": true,
    • "Routing": {
      },
    • "AntiFraud": {
      },
    • "Client": {
      },
    • "UDF": {
      },
    • "PaymentMethodData": {
      },
    • "BrowserDetails": {
      },
    • "ThreeDSecureAuthentication": {
      },
    • "PaymentCredentials": {
      },
    • "PspId": 0,
    • "AirlineDetails": {
      }
    }
    Response samples
    application/json
    {
    • "PspId": 738220,
    • "BankResponse": "Processed",
    • "BankAccept": true,
    • "CardToken": "9705594a-365d-4157-84a8-5af04bbb8507",
    • "IsSuccess": true,
    • "ErrorMessage": ""
    }

    Update Previous Payment Operation

    The methods under the PUT Operation are operations that depend on previous operations and hence

    SecurityClientCredentials
    Request
    header Parameters
    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

    Request Body schema: application/json
    required

    A DirectConnectRequest Object consisting of all the attributes required to fulfil a Direct Connect integration

    One of:

    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.

    TransactionType
    required
    any

    Specifies the Transaction Type for this operation. In the contect of a Payment Capture it is a "CAPT"

    Enum: "CAPT" "GENERALVOID" "PARTIALREFUND"
    Amount
    required
    number

    Indicates the transaction amount to be processed.

    CallBackURL
    required
    string

    Specifies the URL where callback notifications or responses should be sent.

    IsTest
    required
    boolean
    Default: false

    Specifies if the transaction will be routed to the sandbox environment. Not passing this parameter will default to the live environment

    UniqueReference
    required
    string <uuid>

    A unique identifier must be provided in this parameter to identify the request and prevent duplicate processing. It is recommended that you utilize a GUID or similar mechanism.

    PspID
    required
    integer

    This field should contains the Gateway Unique Transaction ID

    Responses
    200
    400

    Bad Request

    401

    Unauthorized

    default

    Business Validation Exception

    put/api/directconnect/execute
    Request samples
    application/json
    {}
    Response samples
    application/json
    {
    • "PspId": 738220,
    • "BankResponse": "Processed",
    • "BankAccept": true,
    • "CardToken": "9705594a-365d-4157-84a8-5af04bbb8507",
    • "IsSuccess": true,
    • "ErrorMessage": ""
    }

    Tokenisation

    This section contains all operations permitted around the Card Tokenisation Functionality

    Tokenise a Card

    The Tokenise Card operation is used to tokenise a new credit card

    SecurityClientCredentials
    Request
    path Parameters
    cardToken
    string

    A GUID Based token representing a tokenized card

    Request Body schema: application/json
    required
    ClientAccount
    string

    The field represents the client's account or user identifier. It typically refers to the unique identifier associated with a customer or client within your system. It helps in identifying and associating the payment request with the specific client account.

    CardHolderName
    required
    string

    Indicates the Card Holder Name & Surname

    CardNumber
    required
    integer <int64>

    Specifies the Card Primary Account Number (Card Number) which typically is between 14 to 19 digit

    ExpMonth
    required
    integer <int32>

    Specifies the Month part of the Card Expiry

    ExpYear
    required
    integer

    Specifies the Year part of the Card Expiry

    Responses
    200
    400

    Bad Request

    401

    Unauthorized

    default

    Business Validation Exception

    post/api/cards/tokenise
    Request samples
    application/json
    {
    • "clientAccount": "CliACC0102",
    • "cardHolderName": "Joe Bloggs",
    • "cardType": "VISA",
    • "cardNumber": "4444444444444444",
    • "expMonth": 11,
    • "expYear": 2023
    }
    Response samples
    application/json
    {
    • "CardsData": [
      ],
    • "IsSuccess": true,
    • "ErrorMessage": "No records found"
    }

    Delete a Tokenised Card

    The Delete Tokenised Card operation is used to delete a Card Token.

    SecurityClientCredentials
    Request
    path Parameters
    cardToken
    required
    string <uuid>

    A GUID Based token representing a tokenized card

    query Parameters
    clientAccount
    string

    The field represents the client's account or user identifier. It typically refers to the unique identifier associated with a customer or client within your system. It helps in identifying and associating the payment request with the specific client account.

    Responses
    200
    400

    Bad Request

    401

    Unauthorized

    default

    Business Validation Exception

    delete/api/cards/tokenise
    Request samples
    Response samples
    application/json
    {
    • "IsSuccess": true,
    • "ErrorMessage": "No records found"
    }

    Get Tokenised Cards Information

    The Get Tokenised Cards operation is used to retrieve all the Tokenised Cards linked with a Client Account

    SecurityClientCredentials
    Request
    path Parameters
    cardToken
    string <uuid>

    A GUID Based token representing a tokenized card

    query Parameters
    clientAccount
    string

    The field represents the client's account or user identifier. It typically refers to the unique identifier associated with a customer or client within your system. It helps in identifying and associating the payment request with the specific client account.

    dateRegisteredAfter
    integer <int64>

    This field represents the Epoch Timestamp to filter Cards that have been registered from the specified date

    Responses
    200
    400

    Bad Request

    401

    Unauthorized

    default

    Business Validation Exception

    get/api/cards/tokens/{cardToken}
    Request samples
    Response samples
    application/json
    {
    • "CardsData": [
      ],
    • "IsSuccess": true,
    • "ErrorMessage": "No records found"
    }

    Transaction Data

    This section contains all operations to retrieve Payment related information.

    Get Payment Response

    This endpoint is used to retrieve the transaction information

    SecurityClientCredentials
    Request
    query Parameters
    OrderReference
    string

    Merchant Unique Transaction Reference.This may be used for reconcilliation. It is recommended that the identifier is unique to the transaction. Either OrderReference or Pspid need to be supplied.

    PspId
    integer <int32>

    This field should contain the Gateway Unique Transaction ID. Either OrderReference or Pspid need to be supplied.

    Example: PspId=935454
    Responses
    200
    400

    Bad Request

    401

    Unauthorized

    default

    Business Validation Exception

    get/api/transactions/retrieve
    Request samples
    Response samples
    application/json
    {
    • "data": [
      ],
    • "IsSuccess": true,
    • "ErrorMessage": ""
    }

    Balances

    This section contains all operations to retrieve Balance related information.

    Get Account Payout Balance

    This endpoint is used to retrieve the Payout Balance information.

    SecurityClientCredentials
    Request
    query Parameters
    Currency
    required
    string

    Specifies the currency code for the transaction. 3-letter alpha (A-to Z) currency code ISO 4217

    Example: Currency=EUR
    PaymentMethodProvider
    required
    string

    Specifies the specific Bank and/or Alternate Payment Method APM provider

    Example: PaymentMethodProvider=Truepay
    IsTest
    boolean
    Default: false

    Specifies if the request will be routed to the sandbox environment. Not passing this parameter will default to the live environment

    Example: IsTest=true
    AccountIdentifier
    string

    Specifies the SWIFT, BIC, IBAN or Account Number supplied by the Provider. This is typically required where there is more then one account configured (e.g. due to different currencies)

    Example: AccountIdentifier=LU120010001234567891
    Responses
    200
    400

    Bad Request

    401

    Unauthorized

    get/api/banktransfers/getaccountpayoutbalance
    Request samples
    Response samples
    application/json
    {
    • "Balances": {
      },
    • "AccountSpecificData": {
      }
    }

    Provider Configuration

    This section contains all operations to retrieve Provider related information.

    Get Payment Methods

    This method provides a means to retrieve a list of allowable payment methods linked to a specific provider.

    SecurityClientCredentials
    Request
    query Parameters
    Currency
    required
    string

    Specifies the currency code for the transaction. 3-letter alpha (A-to Z) currency code ISO 4217

    Country
    required
    string

    Country in Alpha-3 code of the customer or client

    PaymentProvider
    required
    string

    The Provider that is offering the Payment Method

    IsTest
    required
    boolean

    Specifies allowable payment methods for test requests linked with the specific provider

    Responses
    200
    400
    401
    get/api/providerconfig/getpaymentmethods
    Request samples
    Response samples
    application/json
    {
    • "PaymentMethods": [
      ]
    }

    WebHooks

    Payment NotificationWebhook

    This is the webhook call sent to notify the merchant the outcome of the payment attempt

    Request
    header Parameters
    signature
    required
    string

    This value is intended to be used by the receiving logic to confirm that the payload has not been tempered with in transit. The following link explains the signature calculation process which needs to be implemented by the receiving logic and matched with the specific signature contained in the header Signature Calculation and Verification

    Request Body schema: application/json
    required

    This is the transaction status JSON payload which provides details around the transaction

    AttemptNumber
    integer <int32>

    Specifies the callback attempts to send the payment notification linked to the specific pspid

    SentDateTime
    integer <int64>

    This field represents the Epoch Timestamp of when the specific transaction has been received

    object (UserDefineDataObject)

    User-Defined Data. Any additional information you want to be passed back to you after payment completion.

    TransactionToken
    string

    The Hosted Payment Page token used for the Payment Process

    OrderReference
    string

    Merchant Unique Transaction Reference.

    Status
    any

    A value capturing the payment status.

    Enum: "Processed" "Declined" "Pending"
    AuthCode
    string

    Indicates the Bank authorisation code

    CardInput
    boolean

    Indicates whether a card has been inputted or not

    PspId
    integer <int32>

    This field contains the Gateway Unique Transaction ID

    Currency
    string

    Specifies the currency code for the transaction. 3-letter alpha (A-to Z) currency code ISO 4217

    Amount
    number

    Indicates the transaction amount that has been processed.

    BankMessage
    string

    Indicates the Bank Response of the specific transaction attempt

    CardNumber
    string

    Specifies the Masked Card Primary Account Number (Card Number) which typically is between 14 to 19 digit

    CardExpiry
    string

    Specifies the Month/Year part of the Card Expiry

    CardHolderName
    string

    Indicates the Card Holder Name & Surname

    CardCountry
    string

    Country in Alpha-3 code of the card issuing bank

    CardType
    string

    Specifies the type of Card Scheme Provider

    CardToken
    string

    Captures a card representation in the form of token

    Acquirer
    string

    Indicates the Acquiring Bank of the transaction

    Email
    string

    Email address of the customer or client.

    BankErrorCode
    string

    This attribute captures the Bank Error Code when the transaction is declined by Bank. It is set null if the Transaction has been Processed.

    UniqueReference
    string <uuid>

    Unique identifier generated for each and every attempt when performing a transaction

    ClientAccount
    string

    The field represents the client's account or user identifier. It typically refers to the unique identifier associated with a customer or client within your system. It helps in identifying and associating the payment request with the specific client account.

    Is3DS
    boolean

    Indicates whether a 3ds authentication has been performed or not

    Responses
    200
    Request samples
    application/json
    {
    • "AttemptNumber": 1,
    • "SentDateTime": 1720789324,
    • "UDF": {
      },
    • "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": "ITA",
    • "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
    }

    Extended Payment NotificationWebhook

    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.

    Request
    header Parameters
    signature
    required
    string

    This value is intended to be used by the receiving logic to confirm that the payload has not been tempered with in transit. The following link explains the signature calculation process which needs to be implemented by the receiving logic and matched with the specific signature contained in the header Signature Calculation and Verification

    Request Body schema: application/json
    required

    This is the transaction status JSON payload which provides details around the transaction.

    AttemptNumber
    integer <int32>

    Specifies the callback attempts to send the payment notification linked to the specific pspid

    SentDateTime
    integer <int64>

    This field represents the Epoch Timestamp of when the specific transaction has been received

    object (UserDefineDataObject)

    User-Defined Data. Any additional information you want to be passed back to you after payment completion.

    TransactionToken
    string

    The Hosted Payment Page token used for the Payment Process

    OrderReference
    string

    Merchant Unique Transaction Reference.

    Status
    any

    A value capturing the payment status

    Enum: "Processed" "Declined" "Pending"
    AuthCode
    string

    Indicates the Bank authorisation code

    CardInput
    boolean

    Indicates whether a card has been inputted or not

    PspId
    integer <int32>

    This field contains the Gateway Unique Transaction ID

    Currency
    string

    Specifies the currency code for the transaction. 3-letter alpha (A-to Z) currency code ISO 4217

    Amount
    number

    Indicates the transaction amount that has been processed.

    BankMessage
    string

    Indicates the Bank Response of the specific transaction attempt

    CardNumber
    string

    Specifies the Masked Card Primary Account Number (Card Number) which typically is between 14 to 19 digit

    CardExpiry
    string

    Specifies the Month/Year part of the Card Expiry

    CardHolderName
    string

    Indicates the Card Holder Name & Surname

    CardCountry
    string

    Country in Alpha-2 code of the card issuing bank

    CardType
    string

    Specifies the type of Card Scheme Provider

    CardToken
    string

    Captures a card representation in the form of token

    Acquirer
    string

    Indicates the Acquiring Bank of the transaction

    Email
    string

    Email address of the customer or client.

    BankErrorCode
    string

    This attribute captures the Bank Error Code when the transaction is declined by Bank. It is set null if the Transaction has been Processed.

    UniqueReference
    string <uuid>

    Unique identifier generated for each and every attempt when performing a transaction

    ClientAccount
    string

    The field represents the client's account or user identifier. It typically refers to the unique identifier associated with a customer or client within your system. It helps in identifying and associating the payment request with the specific client account.

    Is3DS
    boolean

    Indicates whether a 3ds authentication has been performed or not

    object (UserInputsObject)

    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. If ALL mandatory fields required by the specific Provider are filled, then this object is NOT populated. If SOME mandatory fields required by the specific Provider are filled, then ONLY the fields filled by the User are populated within this object. The final hierarchy and contents of the object is dependent on the specific Provider requirements. Notwithstanding, mandatory attributes required in the main request object such as Client.Email will follow the same structure or the main request. Kindly check the Provider specific documentation.

    object (ProviderOriginatingDataObject)

    ProviderOriginatingDataObject is a key value pair structure that is populated if the specific provider provides additional transaction information that can be shared with the merchant.

    Responses
    200
    Request samples
    application/json
    {
    • "AttemptNumber": 1,
    • "SentDateTime": 1695108453,
    • "UDF": {
      },
    • "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": {
      },
    • "ProviderOriginatingData": {
      }
    }