Build an authorization integration

Overview

Use the Onerway Direct API to implement authorization and capture flows where you reserve funds on a customer's card first, then decide whether to capture or void the authorization later. This is ideal for delayed fulfillment scenarios such as hotel bookings, car rentals, or ship-on-order workflows.

Because you directly handle cardholder data (CHD), this integration requires PCI DSS compliance.

Constraints

How authorization works

1. Authorize — Send an AUTH request. Onerway places a hold on the customer's card without transferring funds.
2. 3DS (if required) — If the sync response returns status=R, redirect the customer to redirectUrl. The final result arrives via webhook.
3. Capture or void — Capture to transfer funds, or void to release the hold.

Integration steps

1. Create an authorization

Send a payment request with txnType set to AUTH. All other parameters are the same as a standard Direct Card PaymentPayments API.

Key differences from a standard payment

Response handling

2. Capture the authorization

Send a CAPTURE request to transfer the reserved funds. Reference the original authorization via originTransactionId.

Request parameters

Example

{
  "merchantNo": "800209",
  "merchantTxnId": "capture_1721288823000",
  "originTransactionId": "1815983598810308608",
  "txnType": "CAPTURE",
  "sign": "your_calculated_signature"
}

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1813842908840075264",
    "orderAmount": "200.00",
    "orderCurrency": "USD",
    "status": "P"
  }
}

The sync response returns status=P (pending). The final result arrives via webhook notification.

3. Void an authorization (optional)

If you no longer need to capture the funds, send a VOID request to release the hold immediately. Common scenarios:

• Customer cancels the order before capture
• Item is out of stock after authorization
• Authorization was created in error

Request parameters

Example

{
  "merchantNo": "800209",
  "merchantTxnId": "void_1721288823000",
  "originTransactionId": "1815983598810308608",
  "txnType": "VOID",
  "sign": "your_calculated_signature"
}

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1921498535157956608",
    "orderAmount": "200.00",
    "orderCurrency": "USD",
    "status": "P"
  }
}

The sync response returns status=P (pending). The final result arrives via webhook notification.

Error handling

Best practices

• Store transactionId from the AUTH webhook — you need it for both capture and void
• Track expiration — set up alerts for uncaptured authorizations approaching the validity window
• Webhook as source of truth — never rely on sync responses for final business decisions
• Idempotent processing — track transaction status to prevent duplicate capture or void attempts
• Timely action — capture promptly after fulfillment; void promptly on cancellation

Next steps

• API Reference — AuthorizationPayments API — Full request/response field reference
• API Reference — CapturePayments API — Capture endpoint details
• API Reference — ReversalPayments API — Void endpoint details
• Build a subscriptions integration — Recurring billing with Direct API