Remittance and crypto

Choose the recipe for paying a local bank account or mobile wallet abroad, or for sending, moving and converting stablecoins.

These recipes pay recipients outside the US, EU and UK bank rails. They cover local bank accounts and mobile wallets in Africa, the current state of bank payouts in Latin America and Asia, and stablecoin payouts. Each recipe lists what to collect, the call that tells you what is required, the full requests and responses, and the errors the API returns when something is wrong.

For US ACH, wire and RTP, SWIFT, SEPA and Faster Payments, see Bank payouts.

A money example. Ada in Houston sends 250.00 USD to her brother's bank account in Lagos. Your plan charges a 1.50 USD fee. At 1,530.00 NGN per USD, the transfer response prices 382,500.00 NGN for him (local_amount). Her account pays 251.50 USD, and transfer.status.completed arrives when his bank confirms the payment.

Choose your recipe

"Not yet available" means Gravv has not confirmed the route for every business. Ask support to confirm that it is on for your business before you promise it to users. The full list is on Payments and supported countries.

Two questions decide a local payout

1. Are the country and currency open? GET /v1/transfer/supported-countries lists the countries the API knows, not the routes that are open. Only the transfer call tells you. A closed route returns transfers to XX/CCC are not available at this time.
2. Did you pick the bank or wallet operator from GET /v1/external-accounts/institutions? The payee must carry that institution_id. Without it, the transfer returns this payee is not yet set up for transfers — please contact support to complete its setup.

Rules every recipe relies on

• Send every request to https://api.gravv.xyz with the Api-Key header. A key that starts with grvSec_sandbox_ reaches sandbox.
• Every POST needs its own new Idempotency-Key (except verify and the webhook resend). Gravv replays a 4xx response for 24 hours under its key, so use a new key after you fix a request.
• Send amounts as strings with at most 2 decimal places, such as "250.00".
• For local payouts, leave rail out. Never send "wire", which means a US domestic wire.
• Send source.id and customer_id as the UUIDs the API returned.
• HTTP 200 does not always mean the money is on its way. Read transfer_status, which is pending or paused.
• Payee errors carry no code, so match on the start of the message. Some transfer errors carry a code.
• A failed transfer returns the amount and fee to the source, as a transfer_refund transaction.
• There is no rate lock. Gravv takes the rate when you send, and local_amount in the response is the amount priced for the recipient. POST /v1/fx/quote is for FX orders only.
• Deduplicate webhooks on the body's event_id, never on X-Event-ID.