TreasuryWireAPI docsSign inGet API keys

Amounts, errors & idempotency

The rules that apply to every endpoint.

Amounts

  • Requests take amounts in major units: 1500.50 is ₦1,500.50.
  • Responses that describe stored money (balances, statement lines, journal entries) give amounts in minor units: 150050 is ₦1,500.50. Balances also include a ready-formatted formattedBalance.
  • Currencies are three-letter ISO codes, such as NGN.

Idempotency

Endpoints that move money accept a reference that you choose. Sending the same reference again never moves money twice. You get the original result back with status 200, so it is always safe to retry after a timeout or a network error.

  • Use a value that is unique per operation and that you can regenerate, such as your own order or invoice ID.
  • Service charges check that a repeated reference describes the same charge. If it names a different customer or amount, the request is rejected with 409. Transfers and payouts simply return the original result.
  • Transfers and payouts generate a reference for you if you leave it out, but then you can't safely retry, so send your own.

Status codes

StatusMeaning
200OK. Also returned when a reference was already processed.
201Created.
202Accepted but not final yet, such as a payout whose outcome is still being confirmed.
401 / 403Authentication failed. See Authentication.
404The account, customer, service or transaction doesn't exist in this mode.
409A conflict: the resource already exists, or a reference was reused for a different operation.
422Validation failed, or the request can't be done (for example insufficient balance).
500Something went wrong on our side. Retry with the same reference.

Error format

Most errors carry a message:

Error
{
  "message": "Insufficient balance"
}

Validation failures return 422 with an errors array naming each bad field:

Validation error
{
  "errors": [
    {
      "msg": "Invalid value",
      "param": "amount",
      "location": "body"
    }
  ]
}

Successful responses include status: "OK" and a human-readable message. Always branch on the HTTP status code, not on the message text, which may change.