---
title: "Create a payment intent"
method: POST
path: "/v1/sdk/payment-intents"
tags: ["Payment Intents"]
---

# Create a payment intent

`POST /v1/sdk/payment-intents`

Creates a new payment intent for a customer to purchase a plan, top up credits (`purpose: "credit_topup"`), or bill usage (`purpose: "usage_billing"`) with an explicit `amount`/`currency`. Requires an idempotency key to prevent duplicate charges. Returns client secret and publishable key needed for frontend integration.

## Headers

- `idempotency-key` string, required

## Request body

- CreatePaymentIntentDto
  - `amount` integer
  - `autoRecharge` object
    - `currency` string
    - `enabled` boolean
    - `maxMonthlySpendMajor` number
    - `thresholdAmountMajor` number
    - `topupAmountMajor` number
    - `triggerType` 'balance'
  - `currency` string
  - `customerRef` string, required
  - `description` string
  - `planRef` string
  - `pricingTier` string
  - `productRef` string
  - `purpose` 'product' | 'credit_topup' | 'usage_billing'

## Response `201`

Payment intent created successfully

- SdkPaymentIntentResponse
  - `accountId` string — Connected Stripe account ID (only present on create)
  - `amount` number, required — Amount in USD minor units (ledger/normalised). The charge-currency amount is `originalAmount` paired with `currency`.
  - `clientSecret` string, required — Client secret used to confirm the payment on the client
  - `createdAt` string — Creation timestamp
  - `currency` string, required — ISO 4217 presentment (charge) currency code — pairs with `originalAmount`
  - `customerRef` string — Customer reference
  - `exchangeRate` number — Exchange rate applied to convert to USD
  - `expiresAt` string — Expiry timestamp of the payment intent
  - `originalAmount` number — Charge-currency amount in minor units (the currency the customer is billed in)
  - `planRef` string — Plan reference
  - `processorPaymentId` string, required — Payment processor payment intent ID
  - `publishableKey` string, required — Stripe publishable key for the environment
  - `status` 'pending' | 'requires_payment_method' | 'requires_confirmation' | 'requires_action' | 'processing' | 'succeeded' | 'failed' | 'cancelled', required — Payment intent status
  - `transactionId` string — Ledger transaction ID

## Other responses

- `400` — Missing required fields or invalid data

## Changes

- **2026-08-13** `e356f6586bf2` — 8 warning
  - added the new `cancelled` enum value to the `status` response property for the response status `201`
  - added the new `failed` enum value to the `status` response property for the response status `201`
  - added the new `pending` enum value to the `status` response property for the response status `201`
  - added the new `processing` enum value to the `status` response property for the response status `201`
  - …4 more
- **2026-07-30** `8578b7536a9f` — 1 info
  - the request property `autoRecharge` became optional
- **2026-07-17** `bbc2ff2bc849` — 4 warning, 1 info
  - the `customerRef` request property's maxLength was set to `20`
  - the `planRef` request property's maxLength was set to `20`
  - the `productRef` request property's maxLength was set to `20`
  - removed the request property `autoRecharge/maxRecharges`
  - …1 more
- **2026-07-04** `a30b6aef464d` — 2 breaking, 14 info
  - added the new required request property `autoRecharge`
  - the response's body type changed from no type to `object` for status `201`
  - added the optional property `accountId` to the response with the `201` status
  - added the optional property `createdAt` to the response with the `201` status
  - …12 more
- **2026-04-26** `60c2cd1caf83` — 2 breaking
  - the response's body type changed from `object` to no type for status `201`
  - the response's body type changed from `object` to no type for status `400`

[Full history](https://skmtc.dev/solvapay/apis/solvapay-rest-api/changes/v1/sdk/payment-intents/post.md)

---

[API](https://skmtc.dev/solvapay/apis/solvapay-rest-api.md) · [All operations](https://skmtc.dev/solvapay/apis/solvapay-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/solvapay/apis/solvapay-rest-api/revisions/a946cecd290d?raw)