Create a payment intent

POST/v1/payment-intents

Creates a new payment intent in the created status. The intent records how much the customer owes and optionally pins a network and token. To generate a blockchain address for the customer to pay into, call Generate Address as a second step.

Request body

Field	Type	Required	Description
amount_cents	integer	required	Amount to charge in the smallest unit of `currency` (e.g. USD cents). Must be greater than 0.
currency	string	required	ISO-4217 fiat currency code, 3–4 characters (e.g. `USD`).
settlement_currency	string	optional	Crypto token to settle in. If omitted the merchant default is used.
network	string	optional	Blockchain network. One of `ethereum`, `solana`, `tron`, `bnbchain`.
token	string	optional	Token symbol. One of `ETH`, `USDT`, `USDC`, `DAI`, `SOL`, `TRX`, `BNB`, `BUSD`. Must be valid for the chosen `network` (see table below).
reference	string	optional	Your internal reference (e.g. order ID). Max 255 characters. Echoed back in the response and on webhooks.
metadata	object	optional	Arbitrary key/value pairs attached to the intent.

Supported tokens by network

Network	Tokens
`ethereum`	`ETH`, `USDT`, `USDC`, `DAI`
`solana`	`SOL`, `USDT`, `USDC`
`tron`	`TRX`, `USDT`, `USDC`
`bnbchain`	`BNB`, `USDT`, `USDC`, `BUSD`

Example

curl -X POST https://api.bchainpay.com/v1/payment-intents \
-H "Authorization: Bearer $BCHAINPAY_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
  "amount_cents": 4999,
  "currency": "USD",
  "network": "ethereum",
  "token": "USDC",
  "reference": "order_2026_001"
}'

Response — `201 Created`

{
  "id": "pi_3L9kX42",
  "merchant_id": "merch_abc123",
  "amount_cents": 4999,
  "received_amount_cents": 0,
  "remaining_amount_cents": 4999,
  "currency": "USD",
  "network": "ethereum",
  "token": "USDC",
  "status": "requires_action",
  "reference": "order_2026_001",
  "metadata": {},
  "created_at": "2026-04-27T12:00:00Z",
  "updated_at": "2026-04-27T12:00:00Z"
}

Field	Type	Required	Description
id	string	required	Unique payment intent identifier.
merchant_id	string	required	Your merchant account ID.
amount_cents	integer	required	Requested amount in minor currency units.
received_amount_cents	integer	required	Total confirmed on-chain amount, in minor currency units. Starts at `0`.
remaining_amount_cents	integer	required	Amount still owed: `amount_cents - received_amount_cents`.
currency	string	required	Fiat currency code.
settlement_currency	string	optional	Settlement token, if specified.
network	string	optional	Blockchain network, if specified.
token	string	optional	Token symbol, if specified.
crypto_amount	string	optional	Raw crypto amount (smallest unit). Populated after Generate Address.
crypto_amount_decimal	string	optional	Human-readable crypto amount (e.g. `"4.99"`).
token_price_cents	integer	optional	Token price snapshot at generation time, in minor currency units.
status	string	required	Current status: `requires_action`, `processing`, `completed`, `failed`, `cancelled`, `expired`.
reference	string	optional	Your reference string, echoed back.
metadata	object	optional	Arbitrary metadata. After address generation, includes `blockchain_address`.
created_at	string	required	ISO 8601 timestamp.
updated_at	string	required	ISO 8601 timestamp of the last update.

Errors

Status	Code	Meaning
`400`	`invalid_request`	Missing or invalid field — check `error.details`.
`400`	`missing_idempotency_key`	`Idempotency-Key` header was not provided.
`401`	`unauthorized`	Invalid or missing API key.
`409`	`conflict`	Idempotency key reused with a different body.
`422`	`invalid_currency`	The provided currency is not supported.