Bank transfer

Collect a payment by bank transfer. The customer pays in their local currency with a reference, and you receive a stablecoin.

This page shows how to collect a payment by bank transfer. The customer pays from their own bank account. The API returns a payment instruction, including a reference number that the customer uses when they pay.

Customers pay in their local currency, and Gravv stores the funds as a stablecoin in your receiving account.

To create a bank transfer collection, send an Initiate a collection request call with bank_transfer in source.methods. You can collect funds to an internal account, an internal crypto wallet or an external crypto wallet. For an internal destination, send the account or wallet ID. For an external crypto wallet, send the wallet address and network.

The request has no country field. Gravv uses the country of the customer's address, which must be one of the bank transfer countries. In the request:

• Set currency to that country's local currency.
• Send amount as a string with at most 2 decimal places.
• Set asset to the stablecoin you want to receive.
• Put the payer's bank account number in metadata.bank_account_number.

The customer record must have a phone number and a date of birth.

curl --request POST \
     --url https://api.gravv.xyz/v1/collections \
     --header 'Api-Key: <API_KEY>' \
     --header 'Idempotency-Key: 3d4e5f6a-7b8c-4d9e-8f0a-1b2c3d4e5f01' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": "15000.00",
  "currency": "NGN",
  "asset": "USDC",
  "customer_id": "04dfb2e5-1274-4214-b5fd-3415fde7dc17",
  "client_customer_id": "checkers_user",
  "client_reference": "9d8184a1-4a19-b74d-4797-9896aed01332",
  "source": {
    "source_type": "external",
    "methods": [
      "bank_transfer"
    ]
  },
  "destination": {
    "id": "bccb74d8-9715-478d-bcac-9d8184a19530",
    "destination_type": "internal_account"
    },
  "metadata": {
    "bank_account_number": "0123456789"
  }
}
'

The response has an instruction field with HTML-formatted payment details to show the customer, and the bank details in bank_info:

{
  "data": {
    "instruction": "<p>You have a pending payment.</p><p>Transfer <strong>NGN 15,000.00</strong> to the account below.</p>",
    "bank_info": {
      "account_name": "<account name>",
      "account_number": "<account number>",
      "bank_name": "<bank name>"
    },
    "account": "0123456789",
    "client_reference": "9d8184a1-4a19-b74d-4797-9896aed01332",
    "transaction_id": "e07aa829-cda4-4c51-bd43-09a2f1e6604d",
    "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": "<amount in USDC>",
    "rate": "<rate>"
  },
  "error": null
}

Collect to external crypto wallet

To collect funds directly to an external crypto wallet, set destination_type to external_crypto_wallet and provide the wallet address and network:

curl --request POST \
     --url https://api.gravv.xyz/v1/collections \
     --header 'Api-Key: <API_KEY>' \
     --header 'Idempotency-Key: 3d4e5f6a-7b8c-4d9e-8f0a-1b2c3d4e5f02' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": "15000.00",
  "currency": "NGN",
  "asset": "USDC",
  "customer_id": "04dfb2e5-1274-4214-b5fd-3415fde7dc17",
  "client_customer_id": "checkers_user",
  "client_reference": "9d8184a1-4a19-b74d-4797-9896aed01333",
  "source": {
    "source_type": "external",
    "methods": [
      "bank_transfer"
    ]
  },
  "destination": {
    "destination_type": "external_crypto_wallet",
    "wallet_address": "0x445906a6766927c5da8b2fca0e0db5d7b5565ef8",
    "network": "polygon"
  },
  "metadata": {
    "bank_account_number": "0123456789"
  }
}
'

Attach custom data with metadata

Use the optional metadata field to attach custom JSON data to collection requests. Gravv returns this data in webhook notifications, so you can track extra details for each transaction:

{
  "metadata": {
    "reference": "12345",
    "bank_account_number": "0123456789"
  }
}