Authorization and capture

Overview

Authorization and capture is a two-step process available for card payments only; every other payment method captures at the time of payment. Use it when you need to verify that funds are available before charging the customer, such as for pre-orders or hotel reservations.

Two-step process

1. Authorization: Reservepay verifies that the customer has sufficient funds and places a hold on the amount. The funds are not yet transferred to your account.
2. Capture: You confirm the transaction and the funds are officially transferred from the customer to your account.

How to use authorization and capture

To use this two-step process, you must set the capture parameter to false when initiating a payment flow.

Step 1: Authorize a payment

When calling the initiate-payment-flow endpoint, set capture: false.

await fetch('https://api.reservepay.com/merchants/initiate-payment-flow', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Api-Version': '2025-04-01',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: '10000',
    currency: 'THB',
    payment_session_id: 'sess_1234567890',
    capture: false, // Set to false for authorization only
    return_url: 'https://example.com/return'
  })
})

Once the customer completes the payment flow, the payment status will transition to AUTHORIZED.

Step 2: Capture the payment

To complete the transaction and transfer the funds, call the capture-payment endpoint with the payment_id.

await fetch('https://api.reservepay.com/merchants/capture-payment', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Api-Version': '2025-04-01',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payment_id: 'pay_1234567890'
  })
})

Releasing an authorization

If you decide not to proceed with the transaction, you should release the hold on the customer's funds by reversing the authorization. Use the reverse-payment endpoint for this purpose.

Important considerations

• Capture window: You have 7 days from the payment's created_at to capture or reverse it. This is the same on test and live accounts. The card issuer can release its hold sooner, so a late capture can still fail. Check capturable and reversible on find-payment for the current answer.
• expires_at is not the capture deadline: expires_at is when an unfinished payment expires if the customer doesn't complete it. Once a payment is AUTHORIZED, expires_at no longer matters, and the 7-day capture window applies.
• Full capture only: Capture the full authorized amount. You can't increase or extend an authorization, so a longer hold needs a new payment from the customer.
• When the window closes: The payment stays AUTHORIZED, but capturable and reversible become false and no webhook is sent. capture-payment then returns NOT_CAPTURABLE and reverse-payment returns NOT_REVERSIBLE. Reverse any payment you won't capture while you still can, so the customer's funds are released quickly.

For payment statuses, see Payment lifecycle.