Generate address

POST/v1/payment-intents/:id/generate-address

Assigns a blockchain address for the customer to pay into and calculates the crypto amount at current market rates. The intent remains in requires_action status.

This endpoint is idempotent: if an address has already been generated for this intent, the existing address and crypto amount are returned without side effects.

Path parameters

Field	Type	Required	Description
id	string	required	Payment intent ID (e.g. `pi_3L9kX42`).

Request body

No request body is required.

Example

curl -X POST https://api.bchainpay.com/v1/payment-intents/pi_3L9kX42/generate-address \
  -H "Authorization: Bearer $BCHAINPAY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Response — `200 OK`

Returns the full PaymentIntentResponse with crypto fields populated. The blockchain address is available in metadata.blockchain_address.

{
  "id": "pi_3L9kX42",
  "merchant_id": "merch_abc123",
  "amount_cents": 4999,
  "received_amount_cents": 0,
  "remaining_amount_cents": 4999,
  "currency": "USD",
  "network": "ethereum",
  "token": "USDC",
  "crypto_amount": "4990000",
  "crypto_amount_decimal": "4.99",
  "token_price_cents": 100,
  "status": "requires_action",
  "reference": "order_2026_001",
  "metadata": {
    "blockchain_address": "0x9f3a...b41C"
  },
  "created_at": "2026-04-27T12:00:00Z",
  "updated_at": "2026-04-27T12:00:05Z"
}

Key fields after generation

Field	Description
`status`	Transitions to `requires_action` — the intent is now waiting for on-chain payment.
`crypto_amount`	Raw amount in the token's smallest unit (e.g. `4990000` for 4.99 USDC with 6 decimals).
`crypto_amount_decimal`	Human-readable amount (e.g. `"4.99"`). Display this to the customer.
`token_price_cents`	Snapshot of the token price at generation time, in minor fiat units.
`metadata.blockchain_address`	The on-chain address the customer should send funds to.

Errors

Status	Code	Meaning
`400`	`missing_idempotency_key`	`Idempotency-Key` header was not provided.
`401`	`unauthorized`	Invalid or missing API key.
`404`	`not_found`	Payment intent does not exist.
`409`	`invalid_state_transition`	The intent is not in a state that allows address generation (e.g. already `succeeded` or `canceled`).
`503`	`price_unavailable`	Pricing is temporarily unavailable. Retry with backoff.
`503`	`no_wallets_available`	No wallets are available in the pool for the requested network. Contact support or retry later.