BYbyaccrue
PaymentIntents

Authorize Payment

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/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.

post/api/v1/payment-intents/{paymentIntentId}/authorize

Request

Path parameters

paymentIntentIdstring uuid required

Payment Intent ID

Example:123e4567-e89b-12d3-a456-426614174000

Headers

Client-IDstring 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.

Example:123e4567-e89b-12d3-a456-426614174000
Authorizationstring uuid required

Secure secret to access privileged endpoints.

Example:Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef

Request body

Example request

{
  "data": {
    "attributes": {
      "idempotencyKey": "order-12345-authorize",
      "reference": "order-12345",
      "channel": "ORG-1"
    },
    "meta": {
      "processor": {
        "type": "card-terminal",
        "posId": "POS-001"
      }
    }
  }
}

Response

OK

Example response

{
  "data": {
    "attributes": {
      "balance": {
        "available": 1500,
        "eligibleReward": 500,
        "upperLimit": 103600
      },
      "amount": 3600,
      "reference": "MERCHANT-GENERATED-TOKEN",
      "status": "PromotedToPayment",
      "walletId": "123e4567-e89b-12d3-a456-426614174000"
    }
  },
  "included": [
    {
      "attributes": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "status": "Created",
        "amount": 9999,
        "channel": "ORG-1",
        "reference": "MERCHANT-GENERATED-TOKEN",
        "disbursement": [
          {
            "counterpartyId": "9f755746-13cb-4d0b-81f2-3b4f1b44f6d8",
            "amount": 800,
            "fee": 10,
            "remit": true
          },
          {
            "counterpartyId": "4cf95060-dd01-42ac-9020-8ca42004920d",
            "amount": 200,
            "fee": 5,
            "remit": true
          }
        ],
        "charges": {
          "fee": {
            "amount": 150,
            "type": "pay_by_wallet"
          },
          "rewards": 1000
        },
        "deductions": {
          "rewards": 1000,
          "fees": 150
        }
      },
      "links": {
        "virtualDebitCard": "https://secure-api.accruesavings.com/api/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08/card"
      }
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.