Create payment intent
Creates a card payment intent. It lasts 24 hours and allows at most 5 charge attempts.
Without card_token, the response has a payment_link for the payer. With card_token, Gravv charges the saved card at once. The response is then HTTP 200 whatever the outcome, so check data.status.
Headers
Required for POST requests. Reuse it only to retry the same request. Gravv stores a 400 with the key for 24 hours, so use a new key after you fix a rejected body.
Optional ID of the payer's device. On a payment intent, Gravv stores it and reuses it for later saved-card charges.
Request Body
Your Gravv customer. The customer record must have a phone number and a date of birth.
Your reference for the customer. Saved cards are looked up by this value, so use the same one every time.
USD amount in major units, as a string with at most 2 decimal places.
Alpha-2 country code, stored on the intent. Card availability still uses the customer's address country.
Your reference. It must be unique across your collections and payment intents.
A saved card token from GET /v1/collections/cards. When you send it, Gravv charges the card at once.
When true, asks the checkout to save the card
Where to send the payer after checkout. Gravv adds payment_intent_id and client_reference to it.
Stablecoin to settle in. If you leave it out, USD settles as USDC.
Settlement network. If you send it, it must match the destination.
Possible values: polygon, ethereum, base, stellar, solana, avalanche
Your own data, returned in webhooks for this collection. At most 50 keys. The keys provider_response, internal_transaction_id and system_metadata are reserved. For bank_transfer, put the payer's bank account number in bank_account_number.
The payer's bank account number, for bank_transfer
One of the following variants:
Type of internal destination
Possible values: internal_account, internal_crypto_wallet
An account ID for internal_account, or a wallet ID for internal_crypto_wallet
Possible values: external_crypto_wallet
Address of the external wallet. Gravv checks only its length, so check that the address is on network. Funds sent to a wrong address are lost.
Settlement network
Possible values: polygon, ethereum, base, stellar, solana, avalanche
Possible values: external
Possible values: card
Request Examples
{
"customer_id": "f827e428-c497-4b21-8855-99d978909c28",
"client_customer_id": "merchant-user-123",
"amount": "3.50",
"currency": "USD",
"client_reference": "order-abc-123",
"save_card": true,
"destination": {
"destination_type": "internal_crypto_wallet",
"id": "b628ff35-429b-48f7-bcf0-6a49df106fc6"
},
"source": {
"source_type": "external",
"methods": [
"card"
]
},
"metadata": {
"order_id": "ord_123"
}
}
{
"customer_id": "f827e428-c497-4b21-8855-99d978909c28",
"client_customer_id": "merchant-user-123",
"amount": "9.99",
"currency": "USD",
"client_reference": "sub-2026-10",
"card_token": "tokn_80aebb6ea2594a74bc",
"destination": {
"destination_type": "internal_crypto_wallet",
"id": "b628ff35-429b-48f7-bcf0-6a49df106fc6"
},
"source": {
"source_type": "external",
"methods": [
"card"
]
}
}
Responses
| Status | Description |
|---|---|
200 |
The payment intent |
400 |
The request failed. Every collections error is a 400, including not-found. Read error. |
200 response
Payment intent ID. Send it as payment_intent_id to charge a card.
created when you send no card token. With a card token, it is processing when the charge went through, requires_action for 3D Secure, or charge_failed with the reason in message.
Possible values: created, processing, requires_action, charge_failed
24 hours after created_at
Checkout link, returned when you send no card token. It carries a secret for this payment, so send it only to the payer.
Sent only when Gravv could not build a payment link
Sent only when Gravv could not build a payment link
Collection ID, when a card token charge went through
Outcome of a card token charge
Possible values: redirect_to_url
The 3D Secure page to send the payer to
{
"data": {
"intent_id": "pi_429f578b-675a-4b68-abe3-856cd976257f",
"client_reference": "order-abc-123",
"status": "created",
"amount": "3.50",
"currency": "USD",
"created_at": "2026-10-12T10:00:00Z",
"expires_at": "2026-10-13T10:00:00Z",
"metadata": {
"order_id": "ord_123"
},
"payment_link": "https://checkout.example.com/pi_429f578b-675a-4b68-abe3-856cd976257f?session=eyJqd3QiOiIuLi4ifQ=="
},
"error": null
}
{
"data": {
"intent_id": "pi_0c6f2d7a-1b0e-4f3e-9a3d-4b5c6d7e8f90",
"client_reference": "sub-2026-10",
"status": "processing",
"transaction_id": "90950347-d40b-4ab9-aa77-f1882750477c",
"message": "Card charged successfully",
"amount": "9.99",
"currency": "USD",
"created_at": "2026-10-12T10:00:00Z",
"expires_at": "2026-10-13T10:00:00Z"
},
"error": null
}
{
"data": {
"intent_id": "pi_0c6f2d7a-1b0e-4f3e-9a3d-4b5c6d7e8f90",
"client_reference": "sub-2026-10",
"status": "charge_failed",
"message": "The card has insufficient funds: payment declined",
"amount": "9.99",
"currency": "USD",
"created_at": "2026-10-12T10:00:00Z",
"expires_at": "2026-10-13T10:00:00Z"
},
"error": null
}
400 response
Authorization
- ApiKeyAuth