---
title: "Processing payments via Card Payments API"
slug: "authorise-a-payment"
updated: 2025-02-20T14:49:37Z
published: 2025-02-20T14:49:37Z
canonical: "docs.apcopay.com/authorise-a-payment"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apcopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authorise a Payment

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.

:::(Info) (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](/v1/docs/create-a-hosted-payment-page-session).

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](/v1/docs/request-payouts) section for more information.
:::

:::(Warning) (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.
:::

:::(Info) (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 **<span style="color: black; background-color: lightgrey">Auth</span>** 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](/v1/docs/capture-a-payment).

A **<span style="color: black; background-color: lightgrey">Purc</span>** 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](/v1/docs/transaction-types).
:::

Select if you wish to process an authorisation or purchase:
- [using full card details](/v1/docs/authorise-a-payment#using-full-card-details)
- [using a card token](/v1/docs/authorise-a-payment#using-a-card-token)


### Using full card details ### 

:::(Warning) (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](/v1/docs/accept-a-payment-on-a-hosted-payment). This will shift the PCI responsibilities to us.
:::

Follow the below details to set up your request.

**Endpoint**

<div style="display: flex; justify-content: space-between; align-items: center; border: 1px solid #e0e0e0; padding: 10px; background-color: #f5f5f5;">
    <strong style="background-color: #1F5CA6; color: #fff; padding: 5px; border-radius: 3px;">POST</strong>
    <strong style="margin-left: 10px; flex: 1;">/api/directconnect/execute</strong>
    <a href="https://apcopay.redoc.ly/#operation/PaymentOperationAUTHPURC" target="_blank" style="margin-left: 10px;">Try it here</a>
    <br>
    <br>
</div>
<br>


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

**Request example**

````JSON
{
  "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"
  }
}
````
</br>

 **Response example**
 
 ````JSON
 {
"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:

 ````JSON
 {
"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](/v1/docs/callback-notifications-1).

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

<div style="display: flex; justify-content: space-between; align-items: center; border: 1px solid #e0e0e0; padding: 10px; background-color: #f5f5f5;">
    <strong style="background-color: #1F5CA6; color: #fff; padding: 5px; border-radius: 3px;">GET</strong>
    <strong style="margin-left: 10px; flex: 1;">api/transactions/retrieve</strong>
    <a href="https://apcopay.redoc.ly/#operation/GetPaymentResponse" target="_blank" style="margin-left: 10px;">Try it here</a>
    <br>
    <br>
</div>

## 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**

<div style="display: flex; justify-content: space-between; align-items: center; border: 1px solid #e0e0e0; padding: 10px; background-color: #f5f5f5;">
    <strong style="background-color: #1F5CA6; color: #fff; padding: 5px; border-radius: 3px;">POST</strong>
    <strong style="margin-left: 10px; flex: 1;">/api/directconnect/execute</strong>
    <a href="https://apcopay.redoc.ly/#operation/PaymentOperationAUTHPURC" target="_blank" style="margin-left: 10px;">Try it here</a>
    <br>
    <br>
</div>
<br>

**Request example**

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

````JSON
{
  "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**
 
 ````JSON
 {
"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.

 ````JSON
 {
"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](/v1/docs/callback-notifications-1) 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.

<div style="display: flex; justify-content: space-between; align-items: center; border: 1px solid #e0e0e0; padding: 10px; background-color: #f5f5f5;">
    <strong style="background-color: #1F5CA6; color: #fff; padding: 5px; border-radius: 3px;">GET</strong>
    <strong style="margin-left: 10px; flex: 1;">api/transactions/retrieve</strong>
    <a href="https://apcopay.redoc.ly/#operation/GetPaymentResponse" target="_blank" style="margin-left: 10px;">Try it here</a>
    <br>
    <br>
</div>

### 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](/v1/docs/test-card-numbers).