Initiate a collection
Initiates a collection request using a specified collection method (card, bank transfer, and mobile money).
If the collection method is card, a payment link will be generated for the customer to complete the payment. For mobile money and bank transfer methods, payment instructions will be provided.
Headers
Required for POST requests. Reuse only for an identical retry.
Request Body
Amount to collect
Three-letter uppercase ISO 4217 currency code
Alpha-2 country code
Unique customer identifier
A unique identifier assigned by the client to reference the customer when storing payment details
Client unique reference
Custom JSON data that will be returned in webhook notifications for this transaction
One of the following variants:
Possible values: external
Possible values: card, apple_pay, google_pay, pix, mobile_money, bank_transfer
One of the following variants:
Type of internal destination
Possible values: internal_account, internal_crypto_wallet
Provide an account ID if destination_type is internal_account, or a wallet ID if destination_type is internal_crypto_wallet
Possible values: external_crypto_wallet
Wallet address for the external crypto wallet
Blockchain network for the crypto wallet
Possible values: polygon, stellar, ethereum, solana, avalanche
Request Examples
{
"amount": "50",
"currency": "USD",
"country": "NG",
"customer_id": "04dfb2e5-1274-4214-b5fd-3415fde7dc17",
"client_customer_id": "checkers_user",
"client_reference": "9d8184a1-4a19-b74d-4797-9896aed01332",
"source": {
"source_type": "external",
"methods": [
"card"
]
},
"destination": {
"id": "bccb74d8-9715-478d-bcac-9d8184a19530",
"destination_type": "internal_crypto_wallet"
},
"metadata": {
"something": "i can share"
}
}
{
"source": {
"source_type": "external",
"methods": [
"card"
]
},
"destination": {
"destination_type": "external_crypto_wallet",
"wallet_address": "0x445906a6766927c5da8b2fca0e0db5d7b5565ef8",
"network": "polygon"
},
"amount": "2",
"currency": "USD",
"country": "NG",
"customer_id": "3eb41f1e-0b09-41d0-a1cc-3a60f57a3c5f",
"client_customer_id": "3eb41f1e-0b09-41d0-a1cc-3a60f57a3c59",
"client_reference": "657678888S",
"metadata": {
"order_id": "12345",
"source_platform": "mobile_app"
}
}
Responses
| Status | Description |
|---|---|
200 |
Collection initialized successfully |
400 |
Bad request — invalid or missing parameters |
200 response
One of the following variants:
Hosted payment link for card checkout
Possible values: created, initialized, pending, provider_initiated, provider_success, provider_failed, transfer_queued, transfer_initiated, transfer_success, transfer_failed, abandoned, completed, expired, refunded, cancelled
HTML instructions for completing the payment
Possible values: created, initialized, pending, provider_initiated, provider_success, provider_failed, transfer_queued, transfer_initiated, transfer_success, transfer_failed, abandoned, completed, expired, refunded, cancelled
{
"data": {
"amount": "50",
"client_reference": "trasdfausdaa",
"country": "KE",
"currency": "USD",
"onramp_status": "initialized",
"payment_link": "https://pay-staging.gravv.xyz?transaction_id=07b655cc-3dbd-4f6c-a16c-4657946d2e08",
"raw_payment_link": "https://provider.example/checkout/polygon/purchase...",
"transaction_id": "07b655cc-3dbd-4f6c-a16c-4657946d2e08",
"status": "created"
},
"error": null
}
{
"instruction": "<p>Dear Sam Katana,</p> ... <p>Customer Service</p>",
"client_reference": "04dfb2e5-1274-4214-b5fd-3415fde7dc17",
"transaction_id": "e07aa829-cda4-4c51-bd43-09a2f1e6604d",
"status": "created",
"onramp_status": "initialized",
"amount": "50",
"currency": "ETB",
"country": "ET"
}
{
"instruction": "<p>You have a Pending Payment...</p>",
"client_reference": "04dfb2e5-1274-4214-b5fd-3415fde7dc17",
"transaction_id": "e07aa829-cda4-4c51-bd43-09a2f1e6604d",
"status": "created",
"onramp_status": "initialized",
"amount": "50",
"currency": "ETB",
"country": "ET"
}
400 response
Authorization
- ApiKeyAuth