API reference

Create a transfer

POST/transfers

Sends funds from your wallet to a bank account or mobile money destination. Requires an Idempotency-Key. The amount and fees are reserved atomically before the provider is called; on failure the reservation is released. In the Sandbox the outcome is simulated deterministically from the destination identifier — see Sandbox testing.

Required scope: transfers:write
Idempotency-Key: Required
Environments: Sandbox; Live when authorized

In Live this endpoint returns live_operations_disabled or provider_not_configured until a payment provider is authorized for this deployment.

Request body

amountintegerrequired
Amount in the currency's minor unit (for example cents). Integer.
max 100,000,000,000
currencyenumrequired
ISO 4217 currency code.
"USD", "EUR", "GBP", "XOF", "XAF", "NGN", "GHS", "KES"
destinationone ofrequired
destination.typeenumwhen type = bank_accountrequired
"bank_account"
destination.account_numberstringwhen type = bank_accountrequired
pattern ^[A-Za-z0-9]{6,34}$
destination.bank_codestringwhen type = bank_accountrequired
pattern ^[A-Za-z0-9]{2,16}$
destination.account_namestringwhen type = bank_accountrequired
min length 2 · max length 140
destination.countrystringwhen type = bank_accountrequired
pattern ^[A-Z]{2}$
destination.typeenumwhen type = mobile_moneyrequired
"mobile_money"
destination.phone_numberstringwhen type = mobile_moneyrequired
pattern ^\+[1-9][0-9]{7,14}$
destination.networkstringwhen type = mobile_moneyrequired
pattern ^[A-Za-z0-9_-]{2,32}$
destination.account_namestringwhen type = mobile_moneyrequired
min length 2 · max length 140
destination.countrystringwhen type = mobile_moneyrequired
pattern ^[A-Z]{2}$
referencestringoptional
Your own reference, returned on the transfer and in webhooks.
max length 64
descriptionstringoptional
max length 255
metadatamap of stringoptional
Up to 20 string key/value pairs stored with the object.

Example request

curl -X POST "https://api.gloresend.com/sandbox/v1/transfers" \
  -H "Authorization: Bearer $GLORESEND_TEST_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 125000,
    "currency": "XOF",
    "destination": {
      "type": "bank_account",
      "account_number": "GS0000000001",
      "bank_code": "GSBANK",
      "account_name": "Ada Example",
      "country": "BJ"
    },
    "reference": "INV-2026-0042",
    "description": "Supplier payout",
    "metadata": {
      "order_id": "A-1042"
    }
  }'

Response · 201

201 · application/json

{
  "id": "tr_4k2m9q8w7e6r5t3y",
  "object": "transfer",
  "environment": "sandbox",
  "amount": 125000,
  "fee": 0,
  "currency": "XOF",
  "status": "succeeded",
  "destination": {
    "type": "bank_account",
    "account_name": "Ada Example",
    "country": "BJ",
    "bank_code": "GSBANK",
    "last4": "0001"
  },
  "reference": "INV-2026-0042",
  "description": "Supplier payout",
  "metadata": {
    "order_id": "A-1042"
  },
  "failure_code": null,
  "failure_message": null,
  "created_at": "2026-10-15T09:30:00.000Z",
  "completed_at": "2026-10-15T09:30:00.120Z",
  "test_data": true
}

Response fields

idstringrequired
objectenumrequired
"transfer"
environmentenumrequired
"sandbox", "live"
amountintegerrequired
feeintegerrequired
Fee charged by GLORESEND in minor units. Pricing is not yet configured, so this is currently 0.
currencyenumrequired
ISO 4217 currency code.
"USD", "EUR", "GBP", "XOF", "XAF", "NGN", "GHS", "KES"
statusenumrequired
"processing", "succeeded", "failed"
destinationobjectrequired
destination.typeenumrequired
"bank_account", "mobile_money"
destination.account_namestringrequired
destination.countrystringrequired
destination.bank_codestringoptional
destination.networkstringoptional
destination.last4stringrequired
Last four characters of the account or phone number. Full identifiers are never returned or stored after the request.
referencestring | nullrequired
descriptionstring | nullrequired
metadatamap of stringrequired
failure_codestring | nullrequired
failure_messagestring | nullrequired
created_atstringrequired
date-time
completed_atstring | nullrequired
date-time
test_databooleanrequired

Errors

401authentication_requiredNo credentials were supplied. Send Authorization: Bearer <api key>.
401invalid_api_keyThe API key is unknown, revoked or expired.
401environment_mismatchThe API key belongs to a different environment than the base URL you called. Sandbox keys (gs_test_) only work against the Sandbox base URL, Live keys (gs_live_) only against the Live base URL.
429rate_limitedToo many requests. Wait for the number of seconds in the Retry-After header.
400validation_errorThe request body, query or headers failed validation. param points at the first invalid field.
400idempotency_key_requiredThis endpoint can create side effects and requires an Idempotency-Key header.
422idempotency_key_reuseThe Idempotency-Key was already used with a different request body or endpoint.
409idempotency_in_progressA request with the same Idempotency-Key is still being processed. Retry later.
403insufficient_scopeThe API key does not have the scope required for this endpoint.
402insufficient_fundsThe wallet's available balance is lower than the amount plus fees.
502provider_errorThe downstream provider returned an error. The transfer was marked as failed and reserved funds were released.
504provider_timeoutThe downstream provider did not answer in time. The transfer was marked as failed and reserved funds were released.
503live_operations_disabledLive money movement is not enabled on this deployment. No provider has been authorized yet.
503provider_not_configuredNo payment provider is configured for this environment and operation.