Initiate a collection
Starts a collection from a payer. Card methods return a payment_link for the payer. bank_transfer returns payment instructions and bank details. The funds settle in stablecoin to the destination.
Card amounts are charged in USD. Bank transfer works in BJ, BW, BF, CM, CI, CG, GA, ML, MW, NG, RW, ZA, TZ, TG, UG and ZM, chosen by the customer's address country. For saved cards and repeat charges, use payment intents.
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. Its address country decides which methods are available; there is no country field.
Your own reference for the customer
Amount in major units, as a string with at most 2 decimal places. For card methods it is a USD amount, whatever currency you send.
Three-letter ISO 4217 code in upper case. For bank_transfer, use the local currency of the customer's country.
Stablecoin to settle in, such as USDC or USDT. If you leave it out, USD settles as USDC, and a local currency settles as its tokenized asset where there is one.
Settlement network. If you send it, it must match the destination network.
Possible values: polygon, ethereum, base, stellar, solana, avalanche
Your reference. It must be unique across your collections and payment intents. Gravv generates one if you leave it out.
When true, Gravv does not send the payer's name and email to the card checkout
When true, asks the card checkout to save the card
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
Possible values: external
Payment methods to offer. Send one group only: card, apple_pay and google_pay together, or bank_transfer alone. pix and mobile_money are not available in any country, so the API rejects a request with them. Availability depends on the customer's address country.
Possible values: card, apple_pay, google_pay, pix, bank_transfer, mobile_money
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
Request Examples
{
"amount": "50.00",
"currency": "USD",
"customer_id": "04dfb2e5-1274-4214-b5fd-3415fde7dc17",
"client_customer_id": "checkers_user",
"client_reference": "order-1001",
"source": {
"source_type": "external",
"methods": [
"card"
]
},
"destination": {
"destination_type": "internal_crypto_wallet",
"id": "bccb74d8-9715-478d-bcac-9d8184a19530"
}
}
{
"amount": "15000.00",
"currency": "NGN",
"asset": "USDC",
"customer_id": "04dfb2e5-1274-4214-b5fd-3415fde7dc17",
"client_customer_id": "checkers_user",
"client_reference": "order-1002",
"source": {
"source_type": "external",
"methods": [
"bank_transfer"
]
},
"destination": {
"destination_type": "external_crypto_wallet",
"wallet_address": "0x445906a6766927c5da8b2fca0e0db5d7b5565ef8",
"network": "polygon"
},
"metadata": {
"bank_account_number": "0123456789"
}
}
Responses
| Status | Description |
|---|---|
200 |
The collection was created |
400 |
The request failed. The error names the field, such as source.methods: payment method 'pix' is not available for country 'BR'. The API rejects a customer without a phone number or a date of birth. |
200 response
The new collection. Card methods return payment_link. bank_transfer returns instruction, bank_info, account, converted_amount and rate.
Collection ID. Use it with GET /v1/collections/{id}.
Always created when the collection is created
Possible values: created
Always initialized here. Read the step from GET /v1/collections/{id}.
Possible values: initialized
Possible values: initialized
When onramp_status switches to the new labels. Sent until then.
Card checkout link. Send the payer here.
HTML payment instructions to show the payer
The account the payer sends funds to
The payer account used
Your reference, or the one Gravv generated
The customer's country code
Settlement asset
Settlement network
Amount in the settlement asset. 0.00 for card methods.
Rate used. 0.00 for card methods.
{
"data": {
"transaction_id": "07b655cc-3dbd-4f6c-a16c-4657946d2e08",
"payment_link": "https://checkout.example.com/payment/07b655cc-3dbd-4f6c-a16c-4657946d2e08",
"client_reference": "order-1001",
"status": "created",
"onramp_status": "initialized",
"new_onramp_status": "initialized",
"status_transition_deadline": "2026-10-31T23:59:59Z",
"country": "NG",
"currency": "USD",
"amount": "50.00",
"asset": "USDC",
"network": "polygon",
"converted_amount": "0.00",
"rate": "0.00"
},
"error": null
}
{
"data": {
"transaction_id": "e07aa829-cda4-4c51-bd43-09a2f1e6604d",
"instruction": "<p>You have a pending payment.</p>",
"bank_info": {
"account_number": "9876543210",
"bank_name": "Example Bank",
"account_name": "Example Collections"
},
"account": "0123456789",
"client_reference": "order-1002",
"status": "created",
"onramp_status": "initialized",
"new_onramp_status": "initialized",
"status_transition_deadline": "2026-10-31T23:59:59Z",
"country": "NG",
"currency": "NGN",
"amount": "15000.00",
"asset": "USDC",
"network": "polygon",
"converted_amount": "9.62",
"rate": "1560.00"
},
"error": null
}
400 response
{
"data": null,
"error": "amount: amount has too many decimal places"
}
Authorization
- ApiKeyAuth