Your first Gravv integration
Integrating Gravv begins with creating a customer, then verifying the customer. Once the customer is verified, you can create an account for them. The customer can then fund their account and initiate a transfer to another account, which settles within minutes.
In this tutorial, you will create two customers and open an account for each of them. You will then fund one of the accounts, titled source account, and transfer the funds to the other account, titled destination account.
Prerequisites
To complete this tutorial, you will need the following:
- your Api Key for every request
If you haven't obtained it yet, follow the steps in Obtain your API Key.
- basic understanding of REST APIs and cURL
- a document to save response details
- ability to send a wire transfer
The document can be a Google Docs or another format.
Create a customer
To create a customer, make a POST request using the Add a customer endpoint.
curl -X POST https://api.gravv.xyz/v1/customers \
-H "Api-Key: grvSec_sandbox_6f72cfc99581469f834fb13015130a966f72cfc99581zB77Ij" \
-H 'Idempotency-Key: 979879887678789_attempt_1' \
-H "Content-Type: application/json" \
-d '{
"first_name": "Bode",
"last_name": "Thomas",
"middle_name": "Olaoye",
"email": "bode@gmail.com",
"phone": "+2348069867745",
"type": "individual",
"gender": "male",
"date_of_birth": "2024-04-16",
"address": {
"address_line1": "Same Global Housing Estate",
"city": "Lokogoma",
"country": "NG",
"postal_code": "900107",
"state": "NG-FC"
}
}'
__first_name and last_name are required fields. middle_name is optional and should only be provided if it appears in the customer’s verification documents._
After sending the request, you will receive a response containing the customer details and their id. Save id from the response in your document as source account customer_id:
{
"data": {
"address": {
"address_line1": "Same Global Housing Estate",
"city": "Lokogoma",
"country": "NG",
"postal_code": "900107",
"state": "FCT"
},
"date_of_birth": "1992-04-16",
"email": "bode.thomas@example.com",
"first_name": "Bode",
"gender": "male",
"id": "d12ded01-9081-4a3c-a76c-70654f0a0175",
"last_name": "Thomas",
"middle_name": "Olaoye",
"phone": "+2348069867745",
"status": "active",
"type": "individual"
},
"error": null
}
Initiate Know Your Customer (KYC)
After creating your customer, the next step is to initiate a KYC to verify the customer. You can do this with the Start KYC Verification endpoint. For this, you will need your source account customer_id:
curl --request POST \
--url https://api.gravv.xyz/v1/risk/start-kyc \
--header 'Api-Key: grvSec_sandbox_6f72cfc99581469f834fb13015130a966f72cfc99581zB77Ij' \
--header 'Idempotency-Key: 979879887678789_attempt_1' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"kyc_level": "basic",
"customer_id": "d12ded01-9081-4a3c-a76c-70654f0a0175"
}
'
After sending the request, you will get a response similar to this:
{
"data": {
"applicant_id": "68e4e0dda90f5ec3a13f21ef",
"external_user_id": "d12ded01-9081-4a3c-a76c-70654f0a0175",
"kyc_level": "basic",
"review_status": "pending",
"status": "success"
},
"error": null
}
Create an account for a customer
You can now Create an account for the customer. To do this, you will need your source account customer_id:
curl --request POST \
--url https://api.gravv.xyz/v1/accounts \
--header 'Api-Key: grvSec_sandbox_6f72cfc99581469f834fb13015130a966f72cfc99581zB77Ij' \
--header 'Idempotency-Key: 979879887678789_attempt_1' \
--header 'content-type: application/json' \
--data '
{
"currency": "USD",
"type": "regular",
"label": "Bode Thomas",
"customer_id": "d12ded01-9081-4a3c-a76c-70654f0a0175"
}
'
After sending the request, you will get a response that includes a virtual account details:
{
"data": {
"balance": "0.00",
"capabilities": [
"transfer",
"receive",
"remittance"
],
"currency": "USD",
"customer_id": "d12ded01-9081-4a3c-a76c-70654f0a0175",
"date_created": "2025-10-07T09:49:23Z",
"id": "a4d83e55-435e-41c9-9a0b-dcb99f690c95",
"label": "Bode Thomas",
"status": "active",
"tenant_id": "cd90c45c-fa78-4624-a80a-642be301c812",
"tenant_name": "Dahmoh",
"tier": "",
"type": "regular",
"virtual_account_bank_account_number": "900300758080",
"virtual_account_bank_address": "1800 North Pole St., Orlando, FL 32801",
"virtual_account_bank_beneficiary_address": "1206 BEAR CREEK RD APT 1100, Hung, NJ 12345, US",
"virtual_account_bank_name": "Bank of Nowhere",
"virtual_account_bank_routing_number": "101019644",
"virtual_account_id": "73cea894-bca7-43e2-b278-02bd6d991e2e",
},
"error": null
}
Notice that the response contains both customer_id and id. The customer_id is the same as the source account customer_id that you saved earlier. The id, on the other hand, is a unique identifier for the customer's account. Save the id as source account_id in your document.
Fund the customer's account
Now fund the customer account by sending a wire transfer to the the virtual account details you got from the Create an account response.
Confirm the customer's account balance
Now that the customer's account is funded, the received money will reflect in the customer's account balance. To confirm this, use the source account_id with the Get a single account endpoint to retrieve the customer’s account information:
curl --request GET \
--url https://api.gravv.xyz/v1/accounts/a4d83e55-435e-41c9-9a0b-dcb99f690c95 \
--header 'Api-Key: grvSec_sandbox_6f72cfc99581469f834fb13015130a966f72cfc99581zB77Ij'
You will get a response showing the customer's account balance:
{
"data": {
"balance": "100.00",
"capabilities": [
"transfer",
"receive",
"remittance"
],
"currency": "USD",
"customer_id": "d12ded01-9081-4a3c-a76c-70654f0a0175",
"date_created": "2025-10-07T09:49:23Z",
"id": "a4d83e55-435e-41c9-9a0b-dcb99f690c95",
"label": "Bode Thomas",
"status": "active",
"tenant_id": "cd90c45c-fa78-4624-a80a-642be301c812",
"tenant_name": "Dahmoh",
"tier": "",
"type": "regular",
"virtual_account_bank_account_number": "900300758080",
"virtual_account_bank_address": "1800 North Pole St., Orlando, FL 32801",
"virtual_account_bank_beneficiary_address": "1206 BEAR CREEK RD APT 1100, Hung, NJ 12345, US",
"virtual_account_bank_name": "Bank of Nowhere",
"virtual_account_bank_routing_number": "101019644",
"virtual_account_id": "73cea894-bca7-43e2-b278-02bd6d991e2e",
},
"error": null
}
Initiate a transfer to another account
Now that you've confirmed the Customer's account balance, you can initiate a transfer from the customer account to a destination account. Any account created through the Create an account endpoint is an internal account.
Since you are transferring to an Internal Account here, all you need is the source account customer_id, source account_id, and the account id of the destination account:
- Follow the instructions in Create a customer, Initiate Know Your Customer (KYC), and Create an account for a customer to create a destination account.
Use different personal details, such as names and email address, for this second customer.
- Save the
idfrom the Create an account for a customer response asdestination account_id. -
Prepare the following values for the transfer request:
-
source account
customer_id - source
account_id -
destination
account_id -
Send the transfer request using the prepared values:
curl --request POST \
--url https://api.gravv.xyz/v1/transfer \
--header 'Api-Key: grvSec_sandbox_6f72cfc99581469f834fb13015130a966f72cfc99581zB77Ij' \
--header 'Idempotency-Key: 979879887678789_attempt_1' \
--header 'content-type: application/json' \
--data '
{
"source": {
"source_type": "internal_account",
"id": "a4d83e55-435e-41c9-9a0b-dcb99f690c95"
},
"destination": {
"destination_type": "internal_account",
"id": "d33981df-26d6-4905-9557-aacccd363adb"
},
"amount": 100,
"description": "transfer testing",
"customer_id": "d12ded01-9081-4a3c-a76c-70654f0a0175",
"client_reference": "987908790"
}
'
Congratulations🎉! You’ve completed your first Gravv integration. You’ve experienced the core capabilities of the Gravv API. You can now build on this foundation to create payment solutions for your users.