Authorise a Payment

20 Feb 2025
4 Minutes to read

Print
Share
Dark
Light

Authorise a Payment

Updated on 20 Feb 2025
4 Minutes to read

Print
Share
Dark
Light

Article summary

Did you find this summary helpful?

Thank you for your feedback

Authorising a card payment is the crucial first step in validating a financial transaction. This process ensures the legitimacy of the cardholder’s request to make a purchase and confirms that sufficient funds are available.

Supported Payment Methods

This endpoint is designed for processing card payments. If you intend to process a payment via an Alternative Payment Method (APM), we recommend utilising our Hosted Payment Page.

The exception here applies to payouts. Payout requests for both cards and APMs are typically handled through the direct connect method. As these transactions involve receiving funds rather than making a payment, they do not require customer authentication, and redirection is generally unnecessary. View the Request Payouts section for more information.

Authorisation expiry

An authorisation has a predefined expiration period, which is determined by the card issuer. The duration can typically remain active up to 30 days. Following this period, the funds are released back on the card.

Transaction Type

There are two primary transaction types for processing card payments:

'Auth' for authorisation
or
'Purc' for purchase. (combines an authorisation and capture)

An Auth initiates a validation on a card to verify its active status and ensure that there is a sufficient balance available to cover the requested amount. You can find details on capturing the requested amount here.

A Purc combines both the authorisation and capture processes. This validates the card, checks for sufficient funds, and the payment is finalised through a single call.

You can find more information on transaction types here.

Select if you wish to process an authorisation or purchase:

Using full card details

PCI Compliance

If you achieve SAQ D PCI certification, you can utilize the following endpoint to request an authorisation.

For those without this level of PCI certification, we recommend us our hosted payment page. This will shift the PCI responsibilities to us.

Follow the below details to set up your request.

Endpoint

POST /api/directconnect/execute Try it here

You can request a transaction of either type AUTH or PURC

Request example

{
  "TransactionType": "PURC",
  "Amount": 1,
  "Currency": "EUR",
  "OrderReference": "9635",
  "UniqueReference": "4b8da4f0-d3b4-44ae-8019-8c66905ffad7",
  "IsTest": false,
  "RedirectionURL": "https://yourURLhere.com/Redirect/",
  "CallBackURL": "https://yourURLhere.com/Listener",
  "PaymentCredentials": {
    "PaymentSource": "Card",
    "CardType": "VISA",
    "CardNumber": 5530869844855045,
    "CvV2": 854,
    "ExpMonth": "11",
    "ExpYear": 2028,
    "CardHolderName": "frictionless Processed"
  },
  "Routing": {
    "ForcePayment": "CARDS"
  },
  "UDF": {
    "MerchantField1": "Value 1"
  },
  "Client": {
    "email": "joe.bloggsaa@testjb.com",
    "firstName": "Joe",
    "lastName": "Bloggs",
    "city": "MagicCity",
    "IPAddress": "127.0.0.1"
  },
  "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"
  }
}

Response example

{
"pspid": 738246,
"bankResponse": "Processed",
"bankAccept": "YES",
"cardToken": "9705594a-365d-4157-84a8-5af04bbb8507",
"redirectUrl": null,
"isSuccess": true,
"errorMessage": null
}

Response example where 3DS is required
When 3D Secure (3DS) authentication is necessary, the user must be redirected to the provided URL to complete the authentication process.

Below is a sample JSON response:

{
"pspid": 738246,
"bankResponse": "Pending",
"bankAccept": "YES",
"cardToken": "9705594a-365d-4157-84a8-5af04bbb8507",
"redirectUrl": https//3DSecure.com/2324123,
"isSuccess": true,
"errorMessage": null
}

The result of the payment can be attained in two ways.

Payment Status Notification Method

The outcome of the payment will be sent to the callbackURL provided in the original request. More information can be found here.

Polling Option
To retrieve the payment status manually, you can poll the status after a certain time using the Get Payment Response API available at the below endpoint.

GET api/transactions/retrieve Try it here

Using a Card Token

Instead of using the full PAN details, you can make the transaction request with the card token. The card token is generated and provided in the payment notification after the first successful payment.

Endpoint

POST /api/directconnect/execute Try it here

Request example

You can request either a transaction of type AUTH or a PURC.

{
  "TransactionType": "AUTH",
  "Currency": "EUR",
  "Amount": 12,
  "OrderReference": "MerchantOrder1",
  "UniqueReference": "4b8da4f0-d3b4-44ae-8019-8c66905ffad7",
  "Card": {
    "CardToken": "9705594a-365d-4157-84a8-5af04bbb8507",
    "CvV2": 123,
  },
 "RedirectionURL": "https://yourURLhere.com/Redirect/",
 "CallBackURL": "https://yourURLhere.com/Listener",
 "FailRedirectionURL": "https://yourURLhere.com/FailRedirect/",
 "Language": "it",
 "IPAddress": "127.0.0.1",
 "Client": {
    "email": "string",
    "clientAccount": "string",
    "firstName": "string",
    "lastName": "string",
    "country": "string",
    "mobileNo": "string",
    "street": "string",
    "city": "string",
    "ZIPCode": "string",
    "state": "string",
    "dateOfBirth": "2019-08-24"
  },
  "UDF": {
    "key": "UserDefinedKey1",
    "value": "UserDefined value"
  },
  "Routing": {
    "ForceBank": "PTEST"
  },
  "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"
  },
  "ThreeDSecureAuthentication": {
    "eci": "07",
    "xid": "aGVsbG8xMjM0NQ==",
    "dsTransactionId": "be395b1a6ab345cfb6688e6737413ba3",
    "acsTransID": "be395b1a6ab345cfb6688e6737413ba3",
    "challengeIndicator": "01",
    "transStatus": "Y",
    "threeDSecureFlow": "CHALLENGE",
    "cavv": "d29ybGQ1NDMyMQ==",
    "threeDVersion": "2.2.0"
  },
  "IsTest": false
}

Response example

{
"pspid": 738246,
"bankResponse": "Processed",
"bankAccept": "YES",
"cardToken": "9705594a-365d-4157-84a8-5af04bbb8507",
"redirectUrl": null,
"isSuccess": true,
"errorMessage": null
}

Response example where 3DS is required
The user is to be redirected the URL provided to complete the authentication.

{
"pspid": 738246,
"bankResponse": "Pending",
"bankAccept": "YES",
"cardToken": "9705594a-365d-4157-84a8-5af04bbb8507",
"redirectUrl": https//3DSecure.com/2324123,
"isSuccess": true,
"errorMessage": null
}

Payment Status

The payment outcome can be obtained through our Payment Notification or by using the Polling Option as a fallback.

Payment Notification Method

The payment result will be sent to the callbackURL specified in the original request. For detailed information, refer to our callback notification guide.

Polling Option (Fallback)
If the payment notification is unavailable or delayed, you can manually retrieve the payment status by polling the Get Payment Response API after a suitable interval. The endpoint for this API is provided below.

GET api/transactions/retrieve Try it here

Testing your integration

There is only one API Base URL:

API BaseUrl: https://payments.apcopay.tech/merchanttools

To perform a test transaction, set the IsTest parameter to true in the payload. For more detailed instructions on how to test, please refer to this page.

Was this article helpful?

What's Next

Capture a Payment

Table of contents

Using a Card Token