---
title: "Create a Payment Intent"
method: POST
path: "/api/v1/payment-intents"
tags: ["PaymentIntents"]
---

# Create a Payment Intent

`POST /api/v1/payment-intents`

## Request

- Base URL: `https://merchant-api.accruesavings.com`
- URL: `https://merchant-api.accruesavings.com/api/v1/payment-intents`
- Auth: none declared. Required headers: `Client-ID`, `Authorization`
- TypeScript: <https://skmtc.dev/byaccrue/apis/accrue-merchant-api/docs/api/v1/payment-intents/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a payment intent using `amount` and exactly one of `walletId` or `lookUpId`.

  When `walletId` is provided, the wallet is validated for the request merchant.

  When `lookUpId` is provided, the scanned string is resolved as a wallet barcode first; if no wallet barcode matches, it is resolved as a gift identifier. Never send a gift `data.id` as `walletId`. A wallet barcode `lookUpId` follows the wallet scan-and-pay flow.

  Gift look-ups skip KYC. `balance.available` is the remaining spendable amount (gift remaining, or wallet available).

  For a **gift** `lookUpId`, point-of-sale should first fetch remaining via [Get Gift by lookUpId](/api#tag/Gifts/operation/getGiftByLookUpId) (`/api/v1/gifts/{lookUpId}`), then POST this endpoint with the **same** scanned string as `lookUpId`. Authorize returns a Payment whose `links.virtualDebitCard` is the gift virtual debit card. Gift remaining is spent later by card-present authorization of that card; authorize does not debit the gift reserve.

## 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` CreatePaymentIntent, required: CreatePaymentIntent
    - `id` string, uuid, required: Unique identifier for the object.
    - `type` 'CreatePaymentIntent', required
    - `attributes` union, required
      - object
        - `amount` integer, required: Amount to be charged in cents
        - `walletId` string, uuid, required: Wallet identifier to validate. Optional alternative to `lookUpId`. Provide exactly one of `walletId` or `lookUpId`.
        - `lookUpId` string: Scanned lookup identifier. Optional alternative to `walletId`. May be a wallet barcode or a gift identifier; wallet barcode resolution wins. For gift spend, send this same string — never send the gift `data.id` as `walletId`. See [Get Gift by lookUpId](/api#tag/Gifts/operation/getGiftByLookUpId).
      - object
        - `amount` integer, required: Amount to be charged in cents
        - `walletId` string, uuid: Wallet identifier to validate. Optional alternative to `lookUpId`. Provide exactly one of `walletId` or `lookUpId`.
        - `lookUpId` string, required: Scanned lookup identifier. Optional alternative to `walletId`. May be a wallet barcode or a gift identifier; wallet barcode resolution wins. For gift spend, send this same string — never send the gift `data.id` as `walletId`. See [Get Gift by lookUpId](/api#tag/Gifts/operation/getGiftByLookUpId).

## Response `201`

Created

- CreatePaymentIntentResponse
  - `data` object, required
    - `id` string, uuid, required: Unique identifier for the object.
    - `type` 'PaymentIntent', required
    - `attributes` object, required
      - `balance` PaymentIntentBalanceInformation, required: Balance for this payment intent. `available` is the remaining spendable amount in cents (gift remaining for a gift lookUpId, or wallet available for a wallet).
        - `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

## Other responses

- `400`: Invalid amount or wallet identifier validation failed
- `403`: Wallet access denied
- `404`: Wallet identifier not found

---

[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)