The Authorization Request

This page is the wire contract for External authorization: what Reap sends on every transaction, what you return, and how long you have to respond.

The request

Reap sends a CARD_AUTHORIZATION_REQUEST as a signed HTTPS POST to your registered endpoint. It carries the same { id, type, data } envelope and X-Reap-Webhook-* headers as every other Reap webhook, so you can verify the signature - over the raw request bytes - and route it through the same code path. The one difference is that Reap consumes your HTTP response as the decision. The body is the envelope: type is always CARD_AUTHORIZATION_REQUEST and data carries the authorization payload.

{
  "id": "9b2c1f7e-1a4d-4c8e-9b2a-2f7e1a4d4c8e",
  "type": "CARD_AUTHORIZATION_REQUEST",
  "data": {
    "transactionId": "8a1d0e6f-2b3c-4d5e-8f1a-3c4d5e6f7a8b",
    "eventId": "9b2c1f7e-1a4d-4c8e-9b2a-2f7e1a4d4c8e",
    "accountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "cardId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "channel": "ECOMMERCE",
    "digitalWallet": null,
    "currency": "USD",
    "amount": 42.50,
    "originalCurrency": "EUR",
    "originalAmount": 39.10,
    "fees": {
      "atm": 0,
      "fx": 0.01
    },
    "merchant": {
      "cardAcceptorId": "000123456789012",
      "name": "ACME Store",
      "city": "Berlin",
      "postCode": "10115",
      "state": null,
      "country": "DE",
      "mccCode": "5732",
      "mccCategory": "Electronics Stores"
    },
    "occurredAt": "2024-01-15T10:30:00Z"
  }
}

The data fields:

Field	Description
`transactionId`	Identifier of the transaction this authorization belongs to. On the first authorization it is the id the transaction is created with. On an incremental authorization it is the id of the existing pending transaction. Matches `id` on the subsequent transaction webhooks.
`eventId`	Identifier for this authorization event, equal to the envelope `id`. Whichever way you decide, the same id appears in the resulting transaction’s `events` and as `triggerEventId` on the transaction webhooks that follow - as the authorization event if you approve, as the decline event if you decline. Use it to correlate this request with the specific event.
`accountId`	The account the card belongs to.
`cardId`	The card used for this transaction.
`channel`	`POS`, `ECOMMERCE`, `ATM`, or `VISA_DIRECT`. `VISA_DIRECT` is a Visa Direct funding transfer that debits the card, such as topping up a wallet.
`digitalWallet`	`APPLE_PAY`, `GOOGLE_PAY`, `MERCHANT_TOKEN`, or `null` for a physical card.
`currency`, `amount`	The amount to authorize in the card’s billing currency (fixed per card program, for example `USD` or `HKD`). A zero `amount` is a balance-check authorization.
`originalCurrency`, `originalAmount`	The same amount in the merchant’s local presentment currency.
`fees`	Cardholder fee breakdown in the billing currency: `atm` (ATM markup) and `fx` (FX markup). Always present; zeros when no fee applies.
`merchant`	Merchant `cardAcceptorId`, `name`, `city`, `postCode`, `state`, `country` (ISO 3166-1 alpha-2), `mccCode` (ISO 18245), and `mccCategory`. `cardAcceptorId` is the merchant ID assigned by the merchant’s acquirer, the same value the transaction webhooks carry. It is unique only within one acquirer and can be `null`.
`occurredAt`	ISO 8601 timestamp of when the authorization was initiated.

The payload is a subset of the card transaction resource and reuses its field names, types, and enums. The generated CARD_AUTHORIZATION_REQUEST webhook reference is the authoritative schema - build your integration against it. For the shared formats of channel, digitalWallet, and merchant, see the card transaction resource.

Your response

Respond with 200 and a JSON body carrying your decision. The body is a discriminated object keyed on decision. To approve:

{ "decision": "APPROVE" }

To decline, include a reason:

{ "decision": "DECLINE", "reason": "INSUFFICIENT_BALANCE" }

Decline reason	Use when
`INSUFFICIENT_BALANCE`	The cardholder does not have enough balance on your side for this transaction.
`TRANSACTION_NOT_ALLOWED`	You are rejecting the transaction on your own controls (risk, a blocked merchant or category, a disabled card on your side, and so on).

These are the only reasons you return. Card and account state declines are decided by Reap before you are called, so they are not yours to return. The decision object is intentionally small so it can gain options later, such as partial approval, without breaking your integration.

Responding in time

You must return a decision within 1.6 seconds. The card network does not wait, and there is no retry on the live transaction. Reap fails closed. If your endpoint times out, is unreachable, returns a non-2xx status, or returns a body Reap cannot parse, Reap declines the transaction. It does the same when your project has no active authorization webhook, or the webhook URL resolves to an address Reap does not call. The declined transaction’s declineReason.code is AUTHORIZATION_ENDPOINT_TIMEOUT for a timeout and AUTHORIZATION_ENDPOINT_ERROR for anything else, so you can tell your endpoint’s failures apart from other declines. Its declineReason.message stays generic for the cardholder.

Because authorization fails closed, your endpoint is on the critical path of every transaction. Treat it as a high-availability, low-latency service. Downtime or slow responses decline real cardholder transactions. See Handling requests for how to build for this.

Zero-amount checks

Some merchants send a zero-amount authorization to confirm a card is valid without charging it, common for subscription sign-ups and saved-card setups. Reap forwards these to you like any other authorization, and you approve or decline them. A zero-amount authorization places no hold whichever way you decide; your decision only signals to the merchant whether the card is usable.

Getting Started

Program Configuration

Compliance

Accounts

Cards

Transactions

Spend Policies

Virtual Assets

Statements

Agentic Payments

Rewards

The Authorization Request

The request

Your response

Responding in time

Zero-amount checks

​The request

​Your response

​Responding in time

​Zero-amount checks

The request

Your response

Responding in time

Zero-amount checks