Tell why a transfer is stuck

Tell a transfer that is still moving from one that is paused, under review or failed, and take the one action that applies without sending the money twice.

Use this recipe to tell a transfer that is still moving from one that is paused, under review or failed. You then take the one action that applies, and you do not send the money twice. It is for a developer at a remittance app whose user says "my 300 USD to Ghana has said processing for two days".

Status. Available.

Money example

Kofi's 300 USD payout can be in one of four states, and each needs a different answer.

1. Gravv is still waiting on the bank or the mobile-money operator. Wait.
2. It is paused because sender details are missing. Send the details and resume it, and the transfer continues.
3. It is under review. The money may already have left, so do not send it again. Contact support.
4. It failed, and 300 USD comes back as a refund row. Fix the cause and send a new transfer.

Before you start

You have the transaction_id and the reference from POST /v1/transfer.

Find out what is required

Read the transaction row first, then the latest webhook.

Steps

1. Read the row

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())

{
  "data": {
    "id": "29a3b2e9-5d65-4441-9588-42dea2bc372f",
    "amount": "300",
    "date_created": "2026-10-11T09:12:03.7Z",
    "direction": "out",
    "transaction_type": "global_remittance",
    "reference": "7412b293-4729-4739-a14f-f3d719db3ad0",
    "channel": "mobile_money",
    "status": "pending",
    "remark": "Transfer is under review. Please contact support before trying again.",
    "client_reference": "kofi-gh-0042",
    "currency": "USD"
  },
  "error": null
}

Here the transfer is under review. Stop, and contact support with the reference 7412b293-4729-4739-a14f-f3d719db3ad0.

2. Read the latest event

List the transfer's events, then open the newest with GET /v1/webhooks/event/{id} and read payload.event_type, payload.event_data.reason and payload.event_data.limit_details.

curl --request GET \
 --url 'https://api.gravv.xyz/v1/webhooks/history?transaction_id=29a3b2e9-5d65-4441-9588-42dea2bc372f&event_type=transfer' \
 --header 'Api-Key: <API_KEY>'

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

3. If it is paused, answer the pause

Use Check what a sender can still send to see how much the sender has left. Then resume the transfer with only the fields requirements asks for and a new Idempotency-Key. Get a stuck remittance moving shows each kind of pause and its resume body.

4. If it failed, confirm the refund

List the customer's transfer_refund rows.

curl --request GET \
 --url 'https://api.gravv.xyz/v1/transactions?customer_id=5be6128e-18c2-4797-a142-ea7d17be3111&transaction_type=transfer_refund' \
 --header 'Api-Key: <API_KEY>'

const response = await fetch("https://api.gravv.xyz/v1/transactions?customer_id=5be6128e-18c2-4797-a142-ea7d17be3111&transaction_type=transfer_refund", {
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?customer_id=5be6128e-18c2-4797-a142-ea7d17be3111&transaction_type=transfer_refund",
headers={
    "Api-Key": os.environ["GRAVV_API_KEY"],
},
)
print(response.status_code, response.json())

Match the refund row to the transfer by reference.

What can go wrong

Webhooks you will receive

• transfer.status.pending, many times while the transfer moves.
• transfer.requires_information for a pause, with limit_details.
• transfer.resumed, with reason resumed or released.
• transfer.status.completed.
• transfer.status.failed, with a reason when a pause ended.
• transfer.status.returned.

Testing in sandbox

A transfer above your sandbox limits policy produces a pause when the policy is in enforce mode. You cannot force a failed crypto transfer or a review from the API. Both are Not yet available in sandbox.

For example, a 5 USD sandbox mobile-money payout went to review. Its webhook was transfer.status.failed with no reason, and the row stayed pending with remark null. In sandbox, a pending row whose latest webhook says failed is the under-review case, even without the remark.

Reference

• Get a transaction
• Webhook history
• Webhook event
• Resume a transfer
• Paused transfers