Reconcile a day of movements

Match every movement dated yesterday to your own records and split the movements into final and still open, even though the list has no date filter.

This recipe matches every movement dated yesterday to your own records. It splits the movements into final and still open, even though the list has no date filter. It is for the finance team of a payroll app that pays contractors from a USD account on Gravv and closes its books every morning.

Status. Available.

Money example

On 12 October 2026, the app sent three payouts from its USD account.

1. The 250 USD payout to Ada, with a 1.50 USD fee, is completed. Book it as paid.
2. The 400 USD payout to Bayo is failed, and a 400 USD transfer_refund row brought the money back. Book it as refunded. The money went out and came back in, so the net is zero.
3. The 120 USD payout to Kemi is still pending. Leave it open and check again tomorrow.

Before you start

• For every transfer you sent, you saved the reference and transaction_id from POST /v1/transfer, and your own client_reference.
• You know the id of the account to reconcile (from GET /v2/accounts).

Find out what is required

These are the transaction row fields you use to reconcile:

Steps

1. Pull the day, newest first

The list has no date filter. The API ignores start_date and end_date and returns no error. Page from the newest row, and stop at the first row older than the day you are reconciling.

curl --request GET \
 --url 'https://api.gravv.xyz/v1/transactions?account_id=43b7a3a6-9a8d-4a03-980d-7b71d8f56413&items_per_page=100&page=1' \
 --header 'Api-Key: <API_KEY>'

const response = await fetch("https://api.gravv.xyz/v1/transactions?account_id=43b7a3a6-9a8d-4a03-980d-7b71d8f56413&items_per_page=100&page=1", {
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/v1/transactions?account_id=43b7a3a6-9a8d-4a03-980d-7b71d8f56413&items_per_page=100&page=1",
headers={
    "Api-Key": os.environ["GRAVV_API_KEY"],
},
)
print(response.status_code, response.json())

{
  "data": {
    "items": [
      {
        "id": "1a2a73ed-562b-4f79-8374-59eef50bea63",
        "customer_id": "5be6128e-18c2-4797-a142-ea7d17be3111",
        "amount": "250",
        "date_created": "2026-10-12T14:02:10.4Z",
        "direction": "out",
        "transaction_type": "global_remittance",
        "description": "Contractor payout October",
        "sending_account_id": "43b7a3a6-9a8d-4a03-980d-7b71d8f56413",
        "receiving_account_id": null,
        "reference": "371ecd7b-27cd-4130-8722-9389571aa876",
        "channel": "bank_transfer",
        "status": "completed",
        "remark": null,
        "client_reference": "pay-ada-2026-10",
        "fee": "1.5",
        "tx_hash": null,
        "metadata": { "recipient_name": "Ada Obi", "local_amount": "382500", "local_amount_currency": "NGN" },
        "balance_before": "10000",
        "balance_after": "9748.5",
        "currency": "USD"
      },
      {
        "id": "ab9099a4-35a2-40ae-9af3-05535ec42e08",
        "amount": "400",
        "date_created": "2026-10-12T11:30:45.1Z",
        "direction": "in",
        "transaction_type": "transfer_refund",
        "reference": "7412b293-4729-4739-a14f-f3d719db3ad0",
        "status": "completed",
        "currency": "USD"
      },
      {
        "id": "29a3b2e9-5d65-4441-9588-42dea2bc372f",
        "amount": "400",
        "date_created": "2026-10-12T09:12:03.7Z",
        "direction": "out",
        "transaction_type": "global_remittance",
        "reference": "7412b293-4729-4739-a14f-f3d719db3ad0",
        "status": "failed",
        "remark": "The recipient's account details are invalid. Your transfer has been refunded.",
        "client_reference": "pay-bayo-2026-10",
        "currency": "USD"
      }
    ],
    "page": 1,
    "items_per_page": 3,
    "total_pages": 1,
    "total_items": 3
  },
  "error": null
}

Paging rules:

• items_per_page in the response is the number of rows returned, not the number you asked for.
• total_items is an estimate when there are several pages.
• Request the next page (page + 1) until a page comes back empty or a row's date_created is before 2026-10-12T00:00:00Z.

2. Match each row

For each row of the day, match id to your stored transaction_id. If no id matches, match reference to your stored transfer reference, then client_reference. A refund row (transfer_refund, direction in) matches the failed transfer by reference.

3. Classify

4. Re-check the open rows the next day

Read each open row again by its id.

curl --request GET \
 --url https://api.gravv.xyz/v1/transactions/29a3b2e9-5d65-4441-9588-42dea2bc372f \
 --header 'Api-Key: <API_KEY>'

const response = await fetch("https://api.gravv.xyz/v1/transactions/29a3b2e9-5d65-4441-9588-42dea2bc372f", {
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/v1/transactions/29a3b2e9-5d65-4441-9588-42dea2bc372f",
headers={
    "Api-Key": os.environ["GRAVV_API_KEY"],
},
)
print(response.status_code, response.json())

5. Optional: a quick CSV of the newest rows

The export holds at most the 10 newest matching rows. Use it for a quick look, never as the full day. Its dates must be YYYY-MM-DD, and export_format is lower case.

curl --request GET \
 --url 'https://api.gravv.xyz/v1/transactions/export?account_id=43b7a3a6-9a8d-4a03-980d-7b71d8f56413&start_date=2026-10-12&end_date=2026-10-12&export_format=csv' \
 --header 'Api-Key: <API_KEY>'

const response = await fetch("https://api.gravv.xyz/v1/transactions/export?account_id=43b7a3a6-9a8d-4a03-980d-7b71d8f56413&start_date=2026-10-12&end_date=2026-10-12&export_format=csv", {
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/v1/transactions/export?account_id=43b7a3a6-9a8d-4a03-980d-7b71d8f56413&start_date=2026-10-12&end_date=2026-10-12&export_format=csv",
headers={
    "Api-Key": os.environ["GRAVV_API_KEY"],
},
)
print(response.status_code, response.json())

{
  "data": {
    "file_content": "aWQsZGF0ZV9jcmVhdGVkLGFtb3VudCxjdXJyZW5jeQo=",
    "file_name": "transactions_2026-10-13.csv",
    "content_type": "text/csv",
    "total_records": 10
  },
  "error": null
}

file_content is base64-encoded. The CSV columns are id,date_created,amount,currency,direction,transaction_type,status,channel,description,fee,reference,tx_hash,sending_account_id,receiving_account_id,client_reference,balance_before,balance_after. If you leave out export_format, you get JSON. The response then has content_type application/json and a file_name ending in .json, and file_content is W10= (an empty list) when nothing matches.

6. Optional: a running total

curl --request GET \
 --url 'https://api.gravv.xyz/v1/transactions/volume?sending_account_id=43b7a3a6-9a8d-4a03-980d-7b71d8f56413&direction=out&status=completed&transaction_type=global_remittance' \
 --header 'Api-Key: <API_KEY>'

const response = await fetch("https://api.gravv.xyz/v1/transactions/volume?sending_account_id=43b7a3a6-9a8d-4a03-980d-7b71d8f56413&direction=out&status=completed&transaction_type=global_remittance", {
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/v1/transactions/volume?sending_account_id=43b7a3a6-9a8d-4a03-980d-7b71d8f56413&direction=out&status=completed&transaction_type=global_remittance",
headers={
    "Api-Key": os.environ["GRAVV_API_KEY"],
},
)
print(response.status_code, response.json())

The response, such as {"data":{"total_volume":"18250.5"},"error":null}, is an all-time total, because the volume endpoint has no date filter. It adds every currency and transaction type together unless you filter them, so it is not a daily figure.

7. Catch the webhooks your server missed

List the transfer events your endpoint never accepted on that day. A date-only end_date means midnight, so 2026-10-13 covers all of 12 October.

curl --request GET \
 --url 'https://api.gravv.xyz/v1/webhooks/history?event_type=transfer&start_date=2026-10-12&end_date=2026-10-13&status=failed' \
 --header 'Api-Key: <API_KEY>'

const response = await fetch("https://api.gravv.xyz/v1/webhooks/history?event_type=transfer&start_date=2026-10-12&end_date=2026-10-13&status=failed", {
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/v1/webhooks/history?event_type=transfer&start_date=2026-10-12&end_date=2026-10-13&status=failed",
headers={
    "Api-Key": os.environ["GRAVV_API_KEY"],
},
)
print(response.status_code, response.json())

Resend each one as in Trace a transfer and resend a webhook.

What can go wrong

Webhooks you will receive

Gravv sends no webhook when you read transactions. For the movements themselves, Gravv sends transfer.status.* (transfers), transfer.inflow.* (deposits) and inflow.onchain.* (on-chain wallet deposits).

Testing in sandbox

Create rows with a simulated deposit and a few sandbox transfers, then run the steps with your grvSec_sandbox_ key. Sandbox rows never appear with a live key.

Reference

• List transactions
• Get a transaction
• Export transactions
• Transaction volume
• Webhook history