--- title: "Card authorization request" method: POST path: "card-authorization-request" tags: ["Webhooks"] --- # Card authorization request `POST card-authorization-request` (webhook) Real-time decision request for a card authorization. Grid sends it to the `webhookEndpoint` in your platform config while `cardConfigs.realTimeAuthorization` is set. Your response decides whether the authorization proceeds. This endpoint should be implemented by clients of the Grid API that want to make their own authorization decisions. ### When Grid sends it Grid runs its own checks first: card status, card and platform spend limits, merchant category rules, and network support. Grid sends this request only for authorizations those checks approve, so a declined authorization never reaches your endpoint. Balance inquiries are never sent. It covers only cards whose authorization decisions Grid makes. ### Responding Return HTTP `200` with a `CardAuthorizationDecision` body within 1.5 seconds. `decision: APPROVE` lets the authorization proceed. `decision: DECLINE` declines it, and Grid passes your `declineReason` to the card network. If your endpoint returns any other status or an invalid body, or does not respond in time, Grid applies the `timeoutBehavior` in `cardConfigs.realTimeAuthorization`. Grid does not retry this request. ### After you approve Grid reserves the authorized amount from the funding source after you approve. If the funding source cannot cover it, Grid still declines with `INSUFFICIENT_FUNDS`. The final outcome arrives as a `CARD_TRANSACTION.AUTHORIZED` or `CARD_TRANSACTION.DECLINED` webhook. A decline you return arrives there with `cardDeclinedReason: PLATFORM_DECLINED` and your `declineReason` in `platformDeclineReason`. ### Duplicates Grid can send the same authorization more than once if the card network retries it. Each delivery has a new `id`, but `data.transactionId` and `data.issuerTransactionToken` stay the same. Return the same decision for each. ### Authentication The request includes a signature in the `X-Grid-Signature` header that allows you to verify that the request was sent by Grid. To verify the signature: 1. Get the Grid public key provided to you during integration 2. Decode the base64 signature from the header 3. Create a SHA-256 hash of the request body 4. Verify the signature using the public key and the hash If the signature verification succeeds, the request is authentic. If not, reject it. Also reject a request whose `timestamp` is more than a few minutes old. ## Payload - CardAuthorizationRequestWebhook - `id` string, required: Unique identifier for this webhook delivery (can be used for idempotency) - `type` 'CARD_AUTHORIZATION.REQUEST', required: Type of webhook event in OBJECT.EVENT dot-notation. The part before the dot identifies the resource, the part after identifies the event. This lets consumers route purely on type without inspecting data.status. `CARD_AUTHORIZATION.REQUEST` is a synchronous decision request that Grid sends only while `cardConfigs.realTimeAuthorization` is set. - `timestamp` string, date-time, required: ISO 8601 timestamp of when the webhook was sent - `data` CardAuthorizationRequest, required: A card authorization that Grid's own checks approved, awaiting your platform's decision. `transactionId` is the id of the `CardTransaction` that later `CARD_TRANSACTION.*` webhooks carry, and it stays the same if Grid sends this request more than once. - `transactionId` string, required: The id of the card transaction this authorization opens or adds to. Return the same decision for the same `transactionId` and `issuerTransactionToken`. - `cardId` string, required: The id of the `Card` being used. - `platformCardId` string: Your platform's id for the card, when you set one at issuance. - `customerId` string, required: System ID of the cardholder. - `platformCustomerId` string, required: Platform-specific ID of the cardholder. - `issuerTransactionToken` string, required: Opaque identifier for the transaction on the underlying issuer. It matches `issuerTransactionToken` on the resulting `CardTransaction`. - `transactionType` 'AUTHORIZATION' | 'FINANCIAL_AUTHORIZATION', required: The kind of card authorization being decided. | Value | Meaning | |-------|---------| | `AUTHORIZATION` | A standard authorization. A clearing settles it later. | | `FINANCIAL_AUTHORIZATION` | A single-message authorization, such as an ATM withdrawal or some debit purchases, that settles without a separate clearing. | - `requestedAmount` CurrencyAmount, required - `amount` integer, required: Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC) - `currency` Currency, required - `code` string: Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) - `name` string: Full name of the currency - `symbol` string: Symbol of the currency - `decimals` integer: Number of decimal places for the currency - `approvedAmount` CurrencyAmount, required - `amount` integer, required: Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC) - `currency` Currency, required - `code` string: Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) - `name` string: Full name of the currency - `symbol` string: Symbol of the currency - `decimals` integer: Number of decimal places for the currency - `merchantAmount` CurrencyAmount - `amount` integer, required: Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC) - `currency` Currency, required - `code` string: Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) - `name` string: Full name of the currency - `symbol` string: Symbol of the currency - `decimals` integer: Number of decimal places for the currency - `merchant` CardMerchant, required - `descriptor` string, required: Merchant descriptor string captured from the card network at authorization time. On the sandbox simulate endpoints, where this is supplied rather than reported, it must be 1–25 characters — the width of the card network's acceptor-name field. - `mcc` string: Merchant Category Code (ISO 18245) — four-digit numeric string. - `city` string: Merchant city as reported by the card network, when present. - `state` string: Merchant state or region as reported by the card network, when present. - `country` string: Two-letter ISO 3166-1 alpha-2 country code of the merchant. - `accountId` string, required: The internal account that will fund the authorization. ## Acknowledgement `200` Your decision on the authorization. - CardAuthorizationDecision: The body your `webhookEndpoint` returns with HTTP `200` for a `CARD_AUTHORIZATION.REQUEST`. - `decision` 'APPROVE' | 'DECLINE', required: Your platform's decision on a card authorization. - `declineReason` 'SUSPECTED_FRAUD' | 'UNAUTHORIZED_MERCHANT' | 'VELOCITY_EXCEEDED' | 'INSUFFICIENT_FUNDS' | 'CARD_PAUSED': Why your platform declined a card authorization. Grid passes it to the card network, so choose the most specific reason. | Reason | Use when | |--------|----------| | `SUSPECTED_FRAUD` | The authorization breaks your fraud rules. Use it only when no other reason fits. | | `UNAUTHORIZED_MERCHANT` | The merchant, merchant category, country, or transaction type is not allowed for this card. | | `VELOCITY_EXCEEDED` | The authorization exceeds a velocity limit you set. The merchant may retry later. | | `INSUFFICIENT_FUNDS` | The cardholder lacks funds by your own accounting. The merchant may retry later. | | `CARD_PAUSED` | You track a paused state for the card that Grid's card `status` does not reflect. | --- [API](https://skmtc.dev/lightsparkdev/apis/grid-api.md) - [All operations](https://skmtc.dev/lightsparkdev/apis/grid-api/llms.txt) - [OpenAPI document](https://skmtc.dev/lightsparkdev/apis/grid-api/revisions/7a1db46ec552?raw)