Payout Fiat

curl -X POST "https://sandbox-api.tender.cash/v1/api/payout/fiat" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-2026-10-15-0001" \
  -H "x-access-id: your-access-id-here" \
  -H "x-request-id: 550e8400-e29b-41d4-a716-446655440000" \
  -H "x-timestamp: 2026-10-15T09:45:53.000Z" \
  -H "authorization: <signature>" \
  -d '{"method":"internal","asset":"usdc","amount":"100","bank_code":"090267","account_number":"0123456789","reference":"user-8821"}'

curl -X POST "https://sandbox-api.tender.cash/v1/api/payout/fiat" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-2026-10-15-0002" \
  -H "x-access-id: your-access-id-here" \
  -H "x-request-id: 6f1c2a4e-8b3d-4c5e-9f7a-1b2c3d4e5f60" \
  -H "x-timestamp: 2026-10-15T09:46:10.000Z" \
  -H "authorization: <signature>" \
  -d '{"method":"moneygram","asset":"usdc","amount":"100","reference":"user-8821","first_name":"John","last_name":"Doe","dob":"1990-06-15","mobile_number":"+2348012345678","address":"12 Marina Street","city":"Lagos","postal_code":"100001","state_or_province":"LA","country":"NG"}'

{
  "status": "success",
  "message": "Fiat payout initiated",
  "data": {
    "id": "6a45c1d2e4b0a1b2c3d4e5f9",
    "status": "pending",
    "amount": "100",
    "asset": "usdc",
    "usdValue": "100",
    "bankName": "KUDA MICROFINANCE BANK",
    "bankCode": "090267",
    "accountNumber": "0123456789",
    "createdAt": "2026-10-15T09:20:15.650Z"
  }
}

{
  "status": "success",
  "message": "Withdrawal initiated",
  "data": {
    "url": "https://extstellar.moneygram.com/...",
    "transactionId": "abc123",
    "id": "6a45c1d2e4b0a1b2c3d4e5fa"
  }
}

{
  "status": "error",
  "message": "No withdrawal provider available for the selected asset",
  "data": {}
}

POST

api

payout

fiat

curl -X POST "https://sandbox-api.tender.cash/v1/api/payout/fiat" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-2026-10-15-0001" \
  -H "x-access-id: your-access-id-here" \
  -H "x-request-id: 550e8400-e29b-41d4-a716-446655440000" \
  -H "x-timestamp: 2026-10-15T09:45:53.000Z" \
  -H "authorization: <signature>" \
  -d '{"method":"internal","asset":"usdc","amount":"100","bank_code":"090267","account_number":"0123456789","reference":"user-8821"}'

curl -X POST "https://sandbox-api.tender.cash/v1/api/payout/fiat" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-2026-10-15-0002" \
  -H "x-access-id: your-access-id-here" \
  -H "x-request-id: 6f1c2a4e-8b3d-4c5e-9f7a-1b2c3d4e5f60" \
  -H "x-timestamp: 2026-10-15T09:46:10.000Z" \
  -H "authorization: <signature>" \
  -d '{"method":"moneygram","asset":"usdc","amount":"100","reference":"user-8821","first_name":"John","last_name":"Doe","dob":"1990-06-15","mobile_number":"+2348012345678","address":"12 Marina Street","city":"Lagos","postal_code":"100001","state_or_province":"LA","country":"NG"}'

{
  "status": "success",
  "message": "Fiat payout initiated",
  "data": {
    "id": "6a45c1d2e4b0a1b2c3d4e5f9",
    "status": "pending",
    "amount": "100",
    "asset": "usdc",
    "usdValue": "100",
    "bankName": "KUDA MICROFINANCE BANK",
    "bankCode": "090267",
    "accountNumber": "0123456789",
    "createdAt": "2026-10-15T09:20:15.650Z"
  }
}

{
  "status": "success",
  "message": "Withdrawal initiated",
  "data": {
    "url": "https://extstellar.moneygram.com/...",
    "transactionId": "abc123",
    "id": "6a45c1d2e4b0a1b2c3d4e5fa"
  }
}

{
  "status": "error",
  "message": "No withdrawal provider available for the selected asset",
  "data": {}
}

Auth method: Signed (HMAC) — this endpoint requires the full set of signed headers: x-access-id, x-request-id, x-timestamp, and an HMAC-SHA256 authorization signature. See Authentication.

Set method to choose how the payout is delivered:

`method`	What happens	Response
`internal`	Tender converts the asset and sends fiat to a Nigerian bank account. Tender chooses the payout provider; you can’t select one.	The payout record (`id`, `status`, …)
`moneygram`	Starts a MoneyGram payout. Your user opens the returned `url` to complete it.	`{ url, transactionId, id }`

Payouts are processed asynchronously. There are no payout webhooks: poll Get Payout with the returned id until status is completed or failed. All payout endpoints share a bucket of 10 requests per minute per merchant, on top of the general limit. See Rate limits.

Headers

string

required

Base64-encoded HMAC-SHA256 signature of {"timeStamp":"<x-timestamp>","requestId":"<x-request-id>","accessId":"<x-access-id>"}, signed with your access secret. The request body is not part of the signature.Example: "pV3n0o8kq0lK2mJ8bZ1yq3Yt6hR0cXK9u4mVJ2l9sE0="

string

required

ISO 8601 timestamp; must be within 5 minutes of server timeExample: "2026-10-15T09:45:53.000Z"

string

required

A unique UUID v4 per requestExample: "550e8400-e29b-41d4-a716-446655440000"

string

required

Your API access ID provided by TenderExample: "your-access-id-here"

string

required

Must be application/jsonExample: "application/json"

string

required

A unique key you generate for this payout, up to 200 characters (a UUID works well). Retrying with the same key and the same body returns the original response instead of creating a second payout. See Idempotency.Example: "payout-2026-10-15-0001"

Body

string

required

Payout method.Allowed values: internal, moneygramExample: "internal"

string

required

Coin to pay out from your balance. For internal, any coin ID you hold (for example usdc or usdt). For moneygram, an asset MoneyGram supports (for example usdc).Example: "usdc"

string | number

required

Amount of asset to pay out. Accepts a number or a numeric string.

internal: at least 20 units of the asset, and at least $20 USD in value.
moneygram: at least 15 units of the asset.

Example: "100"

string

A stable identifier for the end user this payout is for, up to 500 characters. It is stored on the payout as withdrawalReference.For moneygram, it is also sent to MoneyGram for reconciliation and decides which MoneyGram consumer the payout belongs to. Each distinct reference is a separate consumer, with its own KYC record and transaction-limit window. Reuse the same value for the same person on every payout, and use a different value for a different person. Don’t use a per-transaction value such as an order ID. Omit it (or set it to your own merchant ID) to attribute the payout to your merchant account itself.Example: "user-8821"

`internal` fields

string

Recipient’s Nigerian bank code. Required for internal. The bank must be supported.Example: "090267"

string

Recipient’s bank account number. Required for internal.Example: "0123456789"

`moneygram` fields

All of these are optional. Any you send are pre-filled in the MoneyGram form your user completes, so they don’t have to type them again.

string

Send from one of your Stellar subwallet addresses instead of your merchant wallet. Use the address_reference you gave the address when you created it.Example: "slot-2"

string

Example: "John"

string

Example: "Doe"

string

Date of birth, YYYY-MM-DD. date_of_birth is accepted as an alias.Example: "1990-06-15"

string

Mobile number in international formatExample: "+2348012345678"

string

Street addressExample: "12 Marina Street"

string

Example: "Lagos"

string

Example: "100001"

string

Example: "LA"

string

ISO 3166-1 alpha-2 country codeExample: "NG"

Idempotency

Send a unique Idempotency-Key header with every payout request. Keys are scoped to your merchant account and to this endpoint, and are kept for 24 hours.

Same key, same body: you get the original response again; no new payout is created.
Same key, different body: 409 with Idempotency-Key was already used with a different request.
Same key while the first request is still running: 409 with A request with this Idempotency-Key is already being processed. Wait and retry.
First request failed: the key is released, so you can retry with the same key.
Missing key: 400 with Idempotency-Key header is required.

See Idempotency.

Response

`internal`

string

required

Example: "success"

string

required

Example: "Fiat payout initiated"

object

required

Show data properties

string

Payout ID. Use it with Get Payout.Example: "6a45c1d2e4b0a1b2c3d4e5f9"

string

pending on creationExample: "pending"

string

Amount of asset paid outExample: "100"

string

Example: "usdc"

string

USD value of amountExample: "100"

string

Bank name resolved from bank_codeExample: "KUDA MICROFINANCE BANK"

string

Example: "090267"

string

Example: "0123456789"

string

Example: "2026-10-15T09:20:15.650Z"

`moneygram`

string

required

Example: "success"

string

required

Example: "Withdrawal initiated"

object

required

Show data properties

string

MoneyGram page for this payout. Open url to let your user complete the payout.Example: "https://extstellar.moneygram.com/..."

string

MoneyGram transaction ID. It also appears as providerTransactionId on the payout record.Example: "abc123"

string | null

Payout ID. Use it with Get Payout. In rare cases it is null; the MoneyGram payout still goes ahead.Example: "6a45c1d2e4b0a1b2c3d4e5f9"

Errors

HTTP	Message	Cause
400	`Idempotency-Key header is required`	The header is missing or blank
400	`method must be one of the following values: moneygram, internal`	Missing or unknown `method`
400	`amount, bank_code, account_number, and asset are required for internal`	A required `internal` field is missing
400	`Invalid asset` / `Exchange price not available`	Unknown or unpriced `asset` (`internal`)
400	`Insufficient USDC balance: requested 100, available 40`	Your balance doesn’t cover `amount`
400	`Minimum withdrawal amount is 20 USDC` / `Minimum withdrawal amount is $20 USD`	Below the `internal` minimum
400	`Bank code "123" is not supported`	Unsupported `bank_code` (`internal`)
400	`Withdrawal exceeds your 30-day offramp limit (...)`	The payout would exceed your account’s 30-day limit (`internal`)
400	`Minimum MoneyGram withdrawal amount is 15 USDC`	Below the `moneygram` minimum
400	`Merchant Stellar wallet not found`	You have no Stellar merchant wallet (`moneygram`)
404	`Stellar subwallet address not found`	No active Stellar subwallet address matches `address_reference`
409	`Idempotency-Key was already used with a different request`	Reused key with a different body
409	`A request with this Idempotency-Key is already being processed`	The first request with this key hasn’t finished
503	`No withdrawal provider available for the selected asset`	MoneyGram doesn’t support `asset` right now

curl -X POST "https://sandbox-api.tender.cash/v1/api/payout/fiat" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-2026-10-15-0001" \
  -H "x-access-id: your-access-id-here" \
  -H "x-request-id: 550e8400-e29b-41d4-a716-446655440000" \
  -H "x-timestamp: 2026-10-15T09:45:53.000Z" \
  -H "authorization: <signature>" \
  -d '{"method":"internal","asset":"usdc","amount":"100","bank_code":"090267","account_number":"0123456789","reference":"user-8821"}'

curl -X POST "https://sandbox-api.tender.cash/v1/api/payout/fiat" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-2026-10-15-0002" \
  -H "x-access-id: your-access-id-here" \
  -H "x-request-id: 6f1c2a4e-8b3d-4c5e-9f7a-1b2c3d4e5f60" \
  -H "x-timestamp: 2026-10-15T09:46:10.000Z" \
  -H "authorization: <signature>" \
  -d '{"method":"moneygram","asset":"usdc","amount":"100","reference":"user-8821","first_name":"John","last_name":"Doe","dob":"1990-06-15","mobile_number":"+2348012345678","address":"12 Marina Street","city":"Lagos","postal_code":"100001","state_or_province":"LA","country":"NG"}'

{
  "status": "success",
  "message": "Fiat payout initiated",
  "data": {
    "id": "6a45c1d2e4b0a1b2c3d4e5f9",
    "status": "pending",
    "amount": "100",
    "asset": "usdc",
    "usdValue": "100",
    "bankName": "KUDA MICROFINANCE BANK",
    "bankCode": "090267",
    "accountNumber": "0123456789",
    "createdAt": "2026-10-15T09:20:15.650Z"
  }
}

{
  "status": "success",
  "message": "Withdrawal initiated",
  "data": {
    "url": "https://extstellar.moneygram.com/...",
    "transactionId": "abc123",
    "id": "6a45c1d2e4b0a1b2c3d4e5fa"
  }
}

{
  "status": "error",
  "message": "No withdrawal provider available for the selected asset",
  "data": {}
}

Authorizations

authorization

string

header

required

Signed (HMAC) authentication. Required headers: x-access-id, x-request-id (UUID v4), x-timestamp (ISO 8601, must be within 5 minutes of server time), and authorization: the Base64 HMAC-SHA256 of the JSON string {"timeStamp":"","requestId":"","accessId":""} (keys in that order, no whitespace) using your access secret. The request body, method and path are not signed. The API key must be linked to an outlet.

Headers

authorization

string

required

x-timestamp

string<date-time>

required

ISO 8601 timestamp; must be within 5 minutes of server time

x-request-id

string<uuid>

required

A unique UUID v4 per request

x-access-id

string

required

Content-Type

enum<string>

required

Available options:

application/json

Idempotency-Key

string

required

Unique key for this payout, up to 200 characters. Same key and body within 24 hours replays the original response; a different body or a request still in flight returns 409. Scoped to your merchant account and this endpoint.

Maximum string length: 200

Body

application/json

method

enum<string>

required

Available options:

internal,

moneygram

asset

string

required

Coin ID to pay out. internal: any coin you hold; moneygram: a MoneyGram-supported asset such as usdc.

Maximum string length: 500

Example:

"usdc"

amount

required

internal: at least 20 units and $20 USD. moneygram: at least 15 units.

Example:

"100"

reference

string

Stable per-end-user identifier. Stored as withdrawalReference; for moneygram it also selects the MoneyGram consumer.

Maximum string length: 500

Example:

"user-8821"

bank_code

string

Nigerian bank code. Required for internal.

Maximum string length: 500

Example:

"090267"

account_number

string

Required for internal.

Maximum string length: 500

Example:

"0123456789"

address_reference

string

moneygram: pay out from this Stellar subwallet address instead of your merchant wallet.

Maximum string length: 500

Example:

"slot-2"

first_name

string

moneygram, optional (pre-filled)

Maximum string length: 500

Example:

"John"

last_name

string

moneygram, optional (pre-filled)

Maximum string length: 500

Example:

"Doe"

dob

string

moneygram, optional. YYYY-MM-DD

Maximum string length: 500

Example:

"1990-06-15"

date_of_birth

string

Alias of dob

Maximum string length: 500

mobile_number

string

moneygram, optional

Maximum string length: 500

Example:

"+2348012345678"

address

string

moneygram, optional

Maximum string length: 500

Example:

"12 Marina Street"

city

string

moneygram, optional

Maximum string length: 500

Example:

"Lagos"

postal_code

string

moneygram, optional

Maximum string length: 500

Example:

"100001"

state_or_province

string

moneygram, optional

Maximum string length: 500

Example:

"LA"

country

string

moneygram, optional. ISO 3166-1 alpha-2

Maximum string length: 500

Example:

"NG"

Response

Payout initiated

status

string

required

Example:

"success"

message

string

required

Example:

"success"

data

internal · object

required

internal
moneygram

Show child attributes

Payment

System

Agents

Conversions

Payouts

Subwallets

Webhooks

On-ramp

Headers

Body

`internal` fields

`moneygram` fields

Idempotency

Response

`internal`

`moneygram`

Errors

Authorizations

Headers

Body

Response

​Headers

​Body

​internal fields

​moneygram fields

​Idempotency

​Response

​internal

​moneygram

​Errors

Authorizations

Headers

Body

Response

Headers

Body

`internal` fields

`moneygram` fields

Idempotency

Response

`internal`

`moneygram`

Errors