Skip to content

Bank transfer

Customers can make payments with bank transfers from their bank accounts. The API returns a payment instruction, including a reference number that customers will use when making the payment.

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

To create a bank transfer collection, Initiate a collection request with payment method set to local_bank_transfer. You can collect funds to either an internal account, internal crypto wallet, or external crypto wallet. For internal destinations, provide the account or wallet ID. For external crypto wallets, provide the wallet address and network:

curl --request POST \
     --url https://api.gravv.xyz/v1/collections \
     --header 'Api-Key: <Api Key>' \
     --header 'Idempotency-Key: order_789_attempt_1' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": "50",
  "currency": "ETB",
  "country": "ET",
  "customer_id": "04dfb2e5-1274-4214-b5fd-3415fde7dc17",
  "client_customer_id": "checkers_user",
  "client_reference": "9d8184a1-4a19-b74d-4797-9896aed01332",
  "source": {
    "source_type": "external",
    "methods": [
      "local_bank_transfer"
    ]
  },
  "destination": {
    "id": "bccb74d8-9715-478d-bcac-9d8184a19530",
    "destination_type": "internal_account"
    },
  "metadata": {
    "branch_code": "ET001"
  }
}
'

You will receive a response with an instruction field containing HTML-formatted payment details to display to the customer.

{
  "instruction": "<p>You have a Pending Payment.</p><p>Please go to your nearest Bank branch and make the following payment to complete your travel booking:</p><p>PNR: <strong>83842144</strong></p><p>Price: <strong>ETB 15.00</strong></p>",
  "client_reference": "04dfb2e5-1274-4214-b5fd-3415fde7dc17",
  "transaction_id": "e07aa829-cda4-4c51-bd43-09a2f1e6604d",
  "transaction_status": "pending",
  "onramp_status": "initialized",
  "amount": "50",
  "currency": "ETB",
  "country": "ET"
}

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: order_789_attempt_1' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": "50",
  "currency": "ETB",
  "country": "ET",
  "customer_id": "04dfb2e5-1274-4214-b5fd-3415fde7dc17",
  "client_customer_id": "checkers_user",
  "client_reference": "9d8184a1-4a19-b74d-4797-9896aed01332",
  "source": {
    "source_type": "external",
    "methods": [
      "local_bank_transfer"
    ]
  },
  "destination": {
    "destination_type": "external_crypto_wallet",
    "wallet_address": "0x445906a6766927c5da8b2fca0e0db5d7b5565ef8",
    "network": "polygon"
  },
  "metadata": {
    "branch_code": "ET001"
  }
}
'

Attach custom data with metadata

Use the optional metadata field to attach custom JSON data to collection requests. This data is returned in webhook notifications, allowing you to track additional transaction details:

"metadata": {
  "reference": "12345",
  "branch_code": "ET001"
}