> ## Documentation Index > Fetch the complete documentation index at: https://docs.reap.global/llms.txt > Use this file to discover all available pages before exploring further. # The Authorization Request > The CARD_AUTHORIZATION_REQUEST contract - what Reap sends, what you return, and your time budget. This page is the wire contract for [External authorization](/transactions/external-authorization/overview): 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](/webhooks/signature-verification) - 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. ```json theme={null} { "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](/transactions/lifecycle) 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](#zero-amount-checks). | | `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`](/api-reference/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](/api-reference/card-transactions/get-card-transaction). ## Your response Respond with `200` and a JSON body carrying your decision. The body is a discriminated object keyed on `decision`. To approve: ```json theme={null} { "decision": "APPROVE" } ``` To decline, include a `reason`: ```json theme={null} { "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`](/transactions/decline-reasons#catch-all)), 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](/transactions/external-authorization/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.