--- title: "Authorize Payment" method: POST path: "/api/v1/payment-intents/{paymentIntentId}/authorize" tags: ["PaymentIntents"] --- # Authorize Payment `POST /api/v1/payment-intents/{paymentIntentId}/authorize` ## Request - Base URL: `https://merchant-api.accruesavings.com` - URL: `https://merchant-api.accruesavings.com/api/v1/payment-intents/{paymentIntentId}/authorize` - Auth: none declared. Required headers: `Client-ID`, `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Authorize a payment intent, creating a `Payment`. For wallet payment intents this also reserves wallet funds. If the payment intent was already authorized (an active payment exists), the existing payment is returned without re-authorizing. Send `data.attributes.idempotencyKey` on every authorize. Reuse that key for retries of the **same** logical authorization — including after a timeout or a lost response. A matching retry replays the original success response. A concurrent retry while the first attempt is still in flight returns `409` (`IdempotencyKeyInUse`) instead of authorizing again. Reusing the key with different attributes returns `409` (`IdempotencyKeyReused`) and is not replayed. The key is optional for backwards compatibility and is expected to become required. A timeout is not proof that authorize failed. Keep the same key and retry until you receive a success or a definitive `402` decline. Do not rotate the key and do not create a new payment intent to recover from an ambiguous failure. When a card processor is configured, processor authorization runs inline before the response is returned — for both wallet and gift payment intents. That round trip can take several seconds; use a client timeout of at least 60 seconds (90 seconds recommended). Concurrent retries of an in-flight processor authorize return `409` (`AlreadyExists`) even when no idempotency key is sent, so the card is not charged twice. On success, `included` Payment resources may include `meta.processor` with an opaque processor payload. On processor decline, the payment is marked `Failed` and the endpoint returns `402`. For a gift `lookUpId` payment intent, authorize still creates a `Payment` and, when a card processor is configured, still runs processor authorization inline. It does not debit the gift reserve or reserve wallet funds. After a successful authorize, load the Payment's `links.virtualDebitCard` via [Get Virtual Debit Card](/api#tag/Payments/operation/getVirtualDebitCard) (`/api/v1/payments/{paymentId}/card`). Card-present authorization of that card is what spends remaining gift balance. Optional `data.attributes.channel` and `data.attributes.risk.deviceSessionId` are forwarded to wallet authorization. When a wallet is attached, `data.attributes.balance` on the returned payment intent may be present. ## Path parameters - `paymentIntentId` string, uuid, required: Payment Intent ID ## Headers - `Client-ID` string, uuid, required: The unique identifier of the client making the request. This header is required to retrieve the client-specific configuration and ensure that the response is tailored to the client's settings and permissions. - `Authorization` string, uuid, required: Secure secret to access privileged endpoints. ## Request body - object - `data` AuthorizePaymentIntent, required: AuthorizePaymentIntent - `id` string, uuid, required: Unique identifier for the object. - `type` 'AuthorizePaymentIntent', required - `attributes` object, required - `amount` integer, required: Total purchase amount in cents - `idempotencyKey` string: Client-supplied key that makes this authorization retry-safe (1–255 characters). Reuse the same key for every retry of one logical authorize, including after a timeout or a lost response. A retry with the same key and the same attributes (`amount`, `reference`, `channel`, `risk.deviceSessionId`, and `meta.processor`) replays the original success response. A request that arrives while the first attempt is still in flight returns `409`. Reusing the key with different attributes also returns `409` and is not replayed. Optional for backwards compatibility; supplying it is strongly recommended and expected to become required. Rotating the key after an ambiguous failure can authorize twice. - `reference` string: Reference to the payment inside an external system (e.g. cart or order ID). - `channel` union - string: External channel identifier (e.g. app name, store outlet ID, checkout interface). - object: Structured payment channel reference. - `type` 'App' | 'Store', required: Channel type. - `id` string, required: Channel identifier in the external system. - `risk` object - `deviceSessionId` string, required: Device session ID used for risk assessment. Optional but recommended for production traffic. - `meta` object: Optional JSON:API `meta` on the authorize request. Omit when the processor does not require additional parameters. - `processor` unknown ## Response `201` OK - AuthorizePaymentResponse - `data` object, required: A transaction - `id` string, uuid, required: Unique identifier for the object. - `type` 'PaymentIntent', required - `attributes` object, required - `balance` object: Balance information for a payment intent - `available` integer, required: Available wallet balance in cents - `eligibleReward` integer, required: Eligible reward amount for this transaction in cents - `upperLimit` integer, required: Maximum checkout amount supported for this purchase, in cents - `billingAddress` object, nullable - `street` string, nullable, required - `street2` string, nullable, required - `city` string, nullable, required - `state` string, nullable, required - `postalCode` string, nullable, required - `country` string, nullable, required - `email` string, email, nullable - `error` 'LinkedAccountUnverified' | 'LinkedAccountDisconnected' | 'LinkedAccountMissing' | 'InsufficientBalance' | 'MissingFullName' | 'WrongEmail' | 'InvalidKycStatus', nullable: Specific error associated with the current invalid status. - `expiresAt` string, date-time, nullable: The datetime at which the payment intent is set to expire. After this time, the intent cannot be promoted to a payment and is considered expired. - `fullName` string, nullable - `phoneNumber` string, nullable - `amount` integer: Total purchase amount in cents. - `reference` string, nullable: Reference to the data inside an external system. - `status` 'Promotable' | 'PromotedToPayment' | 'Invalid' | 'Expired' | 'Canceled': The current status of the payment intent. Each status represents a different stage in the payment intent lifecycle, from creation to completion or cancellation. - `userId` string, nullable - `walletId` string, nullable: The ID of the wallet for which the payment intent is created. - `updatedAt` string, date-time, required - `createdAt` string, date-time, required - `relationships` object, required - `payments` object - `data` object[], required - `id` string, uuid, required - `type` 'Payment', required - `included` object[], required - `id` string, uuid, required: Unique identifier for the object. - `type` 'Payment', required - `attributes` object, required - `id` string, uuid - `status` 'Canceled' | 'Created' | 'Failed' | 'Processing' | 'Returned' | 'Sent': After authorize, the payment is typically `Created` until capture or settlement advances it. - `amount` integer, required - `channel` string, nullable: External system identifier used to identify the payment channel. E.g. App Name, Activity ID, Checkout Interface, etc. - `reference` string, nullable: Reference to the data inside an external system. - `disbursement` object[]: Array of disbursements associated with this payment, including counterparty IDs, amounts, and fees. - `counterpartyId` string, uuid, required: The ID of the counterparty to whom the funds are being disbursed. - `amount` integer, required: The total amount charged with a particular payment method, represented in the smallest currency unit (e.g., cents for USD). To obtain the value in dollars, divide by 100. - `fee` integer, required: The fee assigned to this particular disbursement based on the whole payment fee, represented in the smallest currency unit (e.g., cents for USD). To obtain the value in dollars, divide by 100. - `remit` boolean, required: Deprecated. Always returns `true`. All disbursements are remitted directly. Will be removed in a future version. - `charges` object: Charges applied to this payment. - `fee` object: Processing fee details - `amount` integer, required: Fee amount in cents - `type` string, required: Fee type identifier - `rewards` integer: Rewards amount spent from wallet balance, in cents - `deductions` object: Legacy charges breakdown. Use `charges` instead. - `rewards` integer, required: Rewards amount spent from wallet balance, in cents - `fees` integer, required: Processing fees charged, in cents - `expiresAt` string, date-time, required - `updatedAt` string, date-time, required - `createdAt` string, date-time, required - `links` object, required - `virtualDebitCard` string, required - `meta` object: Optional metadata on the Payment resource. Omitted when no processor payload is attached to the response. - `processor` unknown ## Other responses - `402`: Authorization failed for the desired amount - `403`: Client/Payment Intent mismatch - `409`: An authorization is already in progress for this payment or idempotency key, or the key was reused with different attributes. Retry `IdempotencyKeyInUse` and `AlreadyExists` with the same request. Do not retry `IdempotencyKeyReused` with the same key. --- [API](https://skmtc.dev/byaccrue/apis/accrue-merchant-api.md) - [All operations](https://skmtc.dev/byaccrue/apis/accrue-merchant-api/llms.txt) - [OpenAPI document](https://skmtc.dev/byaccrue/apis/accrue-merchant-api/revisions/3e2d97ef2e6e?raw)