Card authorization request
Real-time decision request for a card authorization. Grid sends it to the endpoint you enrolled through PUT /platform/card-authorization-endpoint. It never goes to the webhookEndpoint in your platform config. 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 the endpoint’s responseTimeoutMs (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 endpoint’s timeoutBehavior. 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 on your webhookEndpoint. 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:
- Get the Grid public key provided to you during integration
- Decode the base64 signature from the header
- Create a SHA-256 hash of the request body
- 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.
Authorizations
Secp256r1 (P-256) asymmetric signature of the webhook payload, which can be used to verify that the webhook was sent by Grid. To verify the signature:
- Get the Grid public key provided to you during integration
- Decode the base64 signature from the header
- Create a SHA-256 hash of the request body
- Verify the signature using the public key and the hash
If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.
Body
Unique identifier for this webhook delivery (can be used for idempotency)
"Webhook:019542f5-b3e7-1d02-0000-000000000007"
Status-specific event type in OBJECT.EVENT dot-notation (e.g., OUTGOING_PAYMENT.COMPLETED)
CARD_AUTHORIZATION.REQUEST ISO 8601 timestamp of when the webhook was sent
"2025-08-15T14:32:00Z"
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.
Response
Your decision on the authorization.
The body your authorization endpoint returns with HTTP 200.
Your platform's decision on a card authorization.
APPROVE, DECLINE "APPROVE"
Why you declined. Used only when decision is DECLINE. When you omit it, Grid sends the card network a generic decline.
SUSPECTED_FRAUD, UNAUTHORIZED_MERCHANT, VELOCITY_EXCEEDED, INSUFFICIENT_FUNDS, CARD_PAUSED "SUSPECTED_FRAUD"