Authorise a payment 🛎️🧶

Direct Payment API

Use an authorisation to reserve funds on a card now and settle them later.

An authorisation places a hold on the cardholder's funds without debiting them. You settle the hold with a separate Capture once the final amount is known, or release it with Cancel if it is no longer needed. This makes it a two-step flow, unlike a sale.

Use this flow when the final amount may differ from the amount reserved, or when the charge is confirmed after the order is placed — for example hotel or car-rental deposits.

The authorisation request uses the same structure and endpoint as Accept a payment, with intent set to authorise. Capture and Cancel are mutually exclusive, and a hold can only be cancelled if it has not already been captured. To return funds from a capture that has already settled, use Refund a payment.

How it works 🧶

1. Authenticate — attach your Bearer token and Integrator ID (X-Integrator-ID) to the request headers.
2. Place card details inside sender.custom_data: PAN, expiry month, expiry year, and holder name. CVC is submitted separately at root custom_data.authentication.cvc.
3. Set intent: authorise, channel: ecommerce, and routing.payment_flow: credit_card, then send the request.
4. 🧶 A successful authorisation returns status: success (accepted and queued for the network) for the payment and an id — save it as your payment_id. Check custom_data.transaction_iso_properties.processor_response_code for the actual approval outcome; 00 means approved.
5. When the final amount is known, capture or cancel the hold using that payment_id — see below.

Let's try to reserve funds 🛎️🧶

note

Keep in mind that:

• intent: authorise reserves funds without debiting them — settlement happens on capture.
• Capture and Cancel are mutually exclusive — see below.

Here's the smallest valid request for an authorisation to reserve funds — set intent: authorise and provide the card details directly.

Comments below follow popular API clients' JSON syntax for readability — strip them before sending via curl, fetch, or another HTTP client.

Request body

{
  "amount": 2000,           // Your amount in minor units
  "currency": "EUR",        // Your currency
  "sender": {
    "type": "credit_card",  // Represent the sender in this operation
    "custom_data": {
      "pan": "5341260000000056",
      "expiry_month": "12",
      "expiry_year": "2033",
      "holder_name": "John Snow"
    }
  },
  "receiver": {
    "configuration_id": "<CONFIGURATION_ID>" //PSP/acquirer configuration identifier. 
  },
  "routing": {
    "payment_flow": "credit_card"
  },
  "intent": "authorise",    // This intent is used for an authorisation to reserve funds
  "channel": "ecommerce",  // Sale channel (e.g. `ecommerce`, `moto`)
  "custom_data": {
    "authentication": {
      "cvc": "123"
    }
  }
}

Check the HTTP response — the desired status is 201, meaning the request was accepted. Save these fields, to later trace the payment:

Field	Purpose
id	Payment ID — used for GET, reverse, and webhooks
initial_operation_id	Transfer ID
network_transaction_reference	Scheme network reference

Capture 🛎️

Capture — settles a pre-authorisation (an authorise hold) for the amount you actually want to charge. Turns a reserved hold into a real, debited transaction. Only valid on a payment that hasn't already been captured or cancelled.

Settle a pre-authorisation by sending a POST from the backoffice to the capture endpoint with the original payment ID in the URL.

Handle the synchronous response directly — but note that further updates for this operation may still arrive asynchronously afterward.

curl -X POST https://sandbox-api.paystrax.com/payments/<id>/capture \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "X-Integrator-ID: <integrator_id>" \
  -d '{}'

To capture the full authorised amount, send an empty request body. To capture a partial amount, include {"amount": <AMOUNT>} — the value must not exceed the amount originally authorised.

Check the HTTP response — the desired status is 201. Save the following fields, to later trace the payment:

Field	Purpose
id	This will be the new transfer_id. Do not overwrite your stored payment_id.
parent_operation_id	References the original authorisation_id

Cancel 🛎️

Cancel — releases a pre-authorisation instead of settling it. Voids the hold entirely, no money moves. Only valid before capture — once captured, there's nothing left to cancel.

Void a pre-authorisation and release the reserved funds by sending a POST from the backoffice to the cancel endpoint with the original payment ID in the URL.

Handle the synchronous response directly — but note that further updates for this operation may still arrive asynchronously afterward.

curl -X POST https://sandbox-api.paystrax.com/payments/<id>/cancel \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "X-Integrator-ID: <integrator_id>" \
  -d '{}'

To cancel in full, send an empty request body. To release a partial amount, include {"amount": <AMOUNT>}.

A pre-authorisation can only be cancelled if it has not already been captured. Check the HTTP response — the desired status is 201. Save the following fields, to later trace the payment:

Field	Purpose
id	This will be the new cancel_id
parent_operation_id	References the original authorisation_id

For the full list of which IDs each operation returns and which to store, see Response ID Fields. For more in depth details about payment flow check Payment status transitions.

🧶 Try for yourself

Try it

Call this flow directly in the API Reference.

• POST Create Direct payment ( intent: authorise )
• POST Capture a Payment
• POST Cancel a Payment