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": {
    "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,
    "merchant": {
      "name": "ACME Store",
      "city": "Berlin",
      "country": "DE",
      "mccCode": "5732",
      "mccCategory": "Electronics Stores"
    },
    "occurredAt": "2024-01-15T10:30:00Z"
  }
}

The data fields:

Field	Description
`eventId`	Identifier for this authorization event, equal to the envelope `id`. On approval the same id appears in the transaction’s `events` and as `triggerEventId` on the transaction webhooks that follow. Use it to correlate this request with the lifecycle.
`accountId`	The account the card belongs to.
`cardId`	The card used for this transaction.
`channel`	`POS`, `ECOMMERCE`, `ATM`, or `VISA_DIRECT`.
`digitalWallet`	`APPLE_PAY`, `GOOGLE_PAY`, `MERCHANT_TOKEN`, or `null` for a physical card.
`currency`, `amount`	The amount to authorize in the card currency (always `USD`). A zero `amount` is a balance-check authorization.
`originalCurrency`, `originalAmount`	The same amount in the merchant’s local presentment currency.
`merchant`	Merchant `name`, `city`, `country` (ISO 3166-1 alpha-2), `mccCode` (ISO 18245), and `mccCategory`.
`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. The cardholder sees a generic decline (INTERNAL_ERROR), so keep your endpoint highly available and monitor it. Reap records the underlying cause on its side for support.

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.

​The request

​Your response

​Responding in time

​Zero-amount checks

The request

Your response

Responding in time

Zero-amount checks