Pre-Authorisations - API Integration Guide

What this product does

Pre-authorisations separate reserving funds from completing a card payment. Your integration creates the payment, tracks its status, and requests capture within the permitted window. If you no longer intend to charge the customer, you can cancel the full pre-authorisation through the refund API before it expires.

For endpoint definitions, authentication, and payment parameters, see the Payments API reference.

Before you start

• Confirm support and any account activation requirements with EveryPay.
• Obtain API credentials for the environment you will use.
• Decide when your business will capture the payment.
• Confirm that the final charge will equal the authorised amount.

Core concepts

A pre-authorisation and its capture belong to the same payment.

Your system is responsible for:

• Linking the payment to the relevant order or booking.
• Keeping authorisation separate from successful payment in your business records.
• Requesting capture before the deadline.
• Reconciling the result before marking the order as paid.

End-to-end flow

1. Create the pre-authorisation

Send POST /payments with capture=0 and the required payment details.

Request

curl https://sandbox-api.everypay.gr/payments \
  -u YOUR_SANDBOX_SECRET_KEY: \
  -d token=YOUR_CARD_TOKEN \
  -d amount=15000 \
  -d capture=0 \
  -d description="Order #1234"

Response — relevant fields

{
  "token": "pmt_lkPJrywRlDAp5oKrqOeRHEt0",
  "currency": "EUR",
  "status": "Pre Authorized",
  "is_captured": false,
  "amount": 15000
}

Confirm Pre Authorized and store the returned payment token against your order or booking. Use this token for capture and payment retrieval.

2. Capture the payment

Request capture when you are ready to charge the customer.

The capture completes the charge for the full authorised amount.

Request

curl https://sandbox-api.everypay.gr/payments/pmt_lkPJrywRlDAp5oKrqOeRHEt0/capture \
  -u YOUR_SANDBOX_SECRET_KEY: \
  -X PUT

Response — relevant fields

{
  "token": "pmt_lkPJrywRlDAp5oKrqOeRHEt0",
  "currency": "EUR",
  "status": "Captured",
  "is_captured": true,
  "amount": 15000,
  "captured_amount": 15000
}

Confirm Captured before marking the order as paid.

Alternatively, cancel the pre-authorisation

If you no longer intend to complete the charge, send POST /refunds with the original payment token.

The payment must still be Pre Authorized and must not have expired. EveryPay automatically processes the refund request as an authorisation cancellation.

Request

This example cancels the €150 pre-authorisation created above.

curl https://sandbox-api.everypay.gr/refunds \
  -u YOUR_SANDBOX_SECRET_KEY: \
  -d payment=pmt_lkPJrywRlDAp5oKrqOeRHEt0 \
  -d amount=15000

You can omit amount to cancel the full remaining amount.

Response — relevant fields

{
  "token": "ref_example",
  "status": "Captured",
  "amount": 15000,
  "captured_amount": 0,
  "is_captured": true,
  "payment": "pmt_lkPJrywRlDAp5oKrqOeRHEt0"
}

EveryPay records the cancellation as a refund. The refund’s Captured status indicates completed processing; it does not mean that the original payment was captured. Its captured_amount remains 0.

Confirm the payment status

Retrieve the original payment using the payment token.

curl https://sandbox-api.everypay.gr/payments/pmt_lkPJrywRlDAp5oKrqOeRHEt0 \
  -u YOUR_SANDBOX_SECRET_KEY:

Response — relevant fields

{
  "token": "pmt_lkPJrywRlDAp5oKrqOeRHEt0",
  "status": "Canceled",
  "is_captured": false,
  "amount": 15000,
  "captured_amount": 0,
  "refund_amount": 15000
}

Confirm Canceled before marking the authorisation as canceled in your system. The cancellation appears in the payment’s refund history and contributes to refund_amount, even though no captured funds were returned.

Cancellation requests release of the reserved funds. It does not deduct the authorised amount from your merchant balance. The issuing bank determines when those funds become available to the customer.

If you have configured the refundCreated webhook, EveryPay uses that event for the cancellation and sends the updated payment payload. Check the payment’s Canceled status to distinguish cancellation from a refunded charge.

3. Check and reconcile the result

Retrieve the payment when you need to check its current state.

curl https://sandbox-api.everypay.gr/payments/pmt_lkPJrywRlDAp5oKrqOeRHEt0 \
  -u YOUR_SANDBOX_SECRET_KEY:

Use the payment token to reconcile the result with your order or booking.

Customer-facing experience

Before authorisation, explain:

• The amount you will reserve.
• When you expect to complete the charge.
• That an uncaptured hold is released automatically, with timing determined by the issuing bank.

For example:

We’ll reserve €150 on your card and charge it when your order is ready for dispatch. If the payment is not completed, your bank will release the hold automatically. Release timing varies by bank.

State, lifecycle, and timing

Capture within seven days. The customer’s funds may remain on hold after that deadline while the issuing bank processes their release.

If an authorisation expires and payment is still required, obtain a new authorisation.

What happens if you do not capture?

If you no longer need the authorisation, cancel it before expiry through the Refund API.

If you neither capture nor cancel it, EveryPay automatically marks the pre-authorisation as Expired when its expiry process runs.

Failure modes and recovery

Handling common scenarios

Error handling

Best practices

• Capture promptly once you can fulfil the order or provide the service.
• Keep the payment token linked to your order or booking.
• Distinguish a successful authorisation from a completed charge.
• Explain the reserved amount and expected capture timing to the customer.
• Test authorisation, capture, payment retrieval, and failure handling in the sandbox.

Where to go next

• Review the Payments API reference for the complete request and response definitions.
• Test authorisation, full capture, payment retrieval, and failure handling in the sandbox.
• Confirm extended-authorisation eligibility with EveryPay if your business requires a longer window.