Recipes
View as Markdown Open in ChatGPT Open in Claude

Share account details and receive a deposit

Show a payer the right bank details for each currency, and credit your customer once when the deposit webhooks arrive.

API version: v2.

Who it is for. Any integrator whose account has become active, and who needs to show the payer how to pay and credit the customer when the money arrives.

Status. Available.

Money example

Ada's US client pays 1,200.00 USD.

  1. You show the client Ada's bank name, beneficiary name, account number and routing number. The client sends 1,200.00 USD by ACH.
  2. Her account is wallet-backed, so you receive both inflow.onchain.completed (the USDC reached the wallet) and transfer.inflow.deposit_settled. You credit her once.
  3. GET /v2/accounts/{id} shows the new balance.

Before you start

The account is active. An account has no bank details while it is pending.

Find out what is required

curl --request GET \
 --url https://api.gravv.xyz/v2/accounts/6f1c2a9e-3b1d-4f7a-9c62-0d8e4b7a5c11 \
 --header 'Api-Key: <API_KEY>'

const response = await fetch("https://api.gravv.xyz/v2/accounts/6f1c2a9e-3b1d-4f7a-9c62-0d8e4b7a5c11", {
method: "GET",
headers: {
"Api-Key": process.env.GRAVV_API_KEY,
},
});
console.log(response.status, await response.json());

import os

import requests

response = requests.get(
"https://api.gravv.xyz/v2/accounts/6f1c2a9e-3b1d-4f7a-9c62-0d8e4b7a5c11",
headers={
    "Api-Key": os.environ["GRAVV_API_KEY"],
},
)
print(response.status_code, response.json())

{
  "data": {
    "id": "6f1c2a9e-3b1d-4f7a-9c62-0d8e4b7a5c11",
    "status": "active",
    "currency": "USD",
    "category": "sub_account",
    "wallet_address": "0x5a3e9b0c7d2f41e8a6b4c3d2e1f0a9b8c7d6e5f4",
    "blockchain_network": "polygon",
    "virtual_account_bank_name": "Example Bank NA",
    "virtual_account_bank_account_number": "9876543210",
    "virtual_account_bank_routing_number": "123456780",
    "virtual_account_bank_beneficiary_name": "Ada Okafor",
    "balance": "0",
    "balance_source": "wallet",
    "application_id": "5e7a9c1b-2d4f-4a6b-8c0d-e1f2a3b4c5d6"
  },
  "error": null
}

Show the payer these details:

Account virtual_account_bank_account_number virtual_account_bank_routing_number Also show
USD US account number ABA routing number Bank name and address, beneficiary name and address
EUR, wallet-backed IBAN BIC Bank name, beneficiary name
GBP, wallet-backed UK account number Sort code Bank name, beneficiary name
EUR or GBP with one IBAN The full IBAN Sort code The BIC from virtual_account_bank_metadata. For a UK Faster Payment, the account number is the last 8 digits of the IBAN
NGN 10-digit account number Empty Bank name, beneficiary name
KES Account number Empty Bank name
Any wallet-backed account wallet_address and blockchain_network. Tell the payer to send only USDC on that network

bank_name and bank_code say which option holds the account. virtual_account_bank_name is the bank the payer names. The payer can use the rails listed in the option's rails in capabilities.

Steps

1. Show the details

Read the details from the account. Never read them from applications.accounts.completed, which carries none.

2. Credit the customer when the deposit lands

Account Webhooks
Fiat-only transfer.inflow.completed, with amount (a decimal string), currency, account_id, sender_name, sender_account_number, sender_bank and narration
Wallet-backed transfer.inflow.deposit_settled (status settled, tokenized true) and, from the wallet, inflow.onchain.completed. To link them, match settlement_event_group_id to the on-chain event's event_group_id
Held for a decision on the Dashboard transfer.inflow.awaiting_approval first
The credit failed or was reversed transfer.inflow.payout_failed or transfer.inflow.compensated

Credit your customer once per deposit. Deduplicate events on the body's event_id.

3. Read the balance

Read the account again. Use balance_details.available when it is present. balance is in major units, and balance_source says where it comes from. ledger_balance.posted and .projected are in minor units. With scale 2, 120000 is 1,200.00.

What can go wrong

Response Why Fix
No virtual_account_bank_* fields The account is still pending Wait for active
On a wallet-backed account, the payer says they sent the money, but no webhook arrives The deposit finishes only when the matching USDC reaches the wallet Wait. If the rail's normal time passes, give support the account id, amount and date
The payer sent a non-USDC token, or used another network, to wallet_address The wallet books only USDC on its blockchain_network Contact support
The webhook amount is lower than what the payer sent The sending side took charges, such as a bank's fees on the way. Gravv bills its deposit fee to your business separately, and never takes it from the deposit Ask the payer's bank. For Gravv's fee, see See a deposit arrive
You see the same deposit twice Gravv sends two events for a wallet-backed deposit, and retries repeat events Deduplicate on event_id. Link the events by settlement_event_group_id
400 invalid request payload: unknown field "sort" on the list You sent an unknown query parameter Send only the documented filters

Webhooks you will receive

You receive the deposit webhooks listed in step 2. See Receive deposits.

Testing in sandbox

Simulate a deposit to produce these webhooks.

Reference

Was this page helpful?