Fiat Payouts

A fiat payout debits crypto from your Tender merchant balance and delivers fiat to a recipient. There are two methods, both on the same endpoint, POST /v1/api/payout/fiat: Internal — sends fiat directly to a Nigerian bank account using the recipient’s bank code and account number. Tender chooses the payout provider for each payout; you can’t select one. MoneyGram — starts a MoneyGram payout. You get back a url; your user opens it to complete the payout with MoneyGram. Every request needs an Idempotency-Key header, so a retried request never pays out twice. See Idempotency.

Prerequisites

Authentication guide

These endpoints use Signed (HMAC) authentication — an HMAC-SHA256 signature is required on every request. See the authentication guide for code examples.

const BASE = 'https://sandbox-api.tender.cash/v1/api';
// makeHeaders() → { 'x-access-id', 'x-request-id', 'x-timestamp', 'authorization', ... }

Internal bank transfer

Submit the payout

Call POST /payout/fiat with an Idempotency-Key header, method: "internal", the asset, the amount, and the recipient’s bank_code and account_number.

Confirm initiation

A successful response returns the payout record with status: "pending" and its id.

Poll for completion

Call GET /payout/{id} until status is completed or failed. There are no payout webhooks.

asset can be any coin you hold, for example usdc or usdt. Your balance of that asset across all chains must cover amount; Tender pays out from the chain where you hold the most of it.
The amount must be at least 20 units of the asset and worth at least $20 USD.
The bank code must be a supported Nigerian bank.
An optional reference is stored on the payout as withdrawalReference, so you can match it to your own records.

const res = await fetch(`${BASE}/payout/fiat`, {
  method: 'POST',
  headers: { ...makeHeaders(), 'Idempotency-Key': crypto.randomUUID() },
  body: JSON.stringify({
    method:         'internal',
    asset:          'usdc',
    amount:         '100',
    bank_code:      '090267',
    account_number: '0123456789',
    reference:      'user-8821',
  }),
});
const { data } = await res.json();
// data → { id, status: "pending", amount, asset, usdValue, bankName, bankCode, accountNumber, createdAt }

import uuid

res = requests.post(
    f"{BASE}/payout/fiat",
    headers={**make_headers(), "Idempotency-Key": str(uuid.uuid4())},
    json={
        "method":         "internal",
        "asset":          "usdc",
        "amount":         "100",
        "bank_code":      "090267",
        "account_number": "0123456789",
        "reference":      "user-8821",
    },
)
payout_id = res.json()["data"]["id"]

Payout Fiat API reference

Full parameter list, errors and interactive playground for both methods.

MoneyGram payout

Submit the payout

Call POST /payout/fiat with an Idempotency-Key header, method: "moneygram", the asset and the amount (at least 15 units). Add any recipient details you already have.

Send your user to MoneyGram

The response contains url, transactionId and id. Open url to let your user complete the payout.

Poll for completion

Call GET /payout/{id}. Each call refreshes the status from MoneyGram: providerStatus holds MoneyGram’s raw status and status becomes completed, failed or processing.

The recipient details — first_name, last_name, dob (or date_of_birth), mobile_number, address, city, postal_code, state_or_province and country — are all optional. Any you send are pre-filled in the MoneyGram form so your user doesn’t have to type them again. Funds come from your merchant Stellar wallet. To pay out from one of your Stellar subwallet addresses instead, pass its address_reference.

const res = await fetch(`${BASE}/payout/fiat`, {
  method: 'POST',
  headers: { ...makeHeaders(), 'Idempotency-Key': crypto.randomUUID() },
  body: JSON.stringify({
    method:        'moneygram',
    asset:         'usdc',
    amount:        '100',
    reference:     'user-8821',
    first_name:    'John',
    last_name:     'Doe',
    mobile_number: '+2348012345678',
    country:       'NG',
  }),
});
const { data } = await res.json();
// Open data.url to let your user complete the payout; poll GET /payout/{data.id}

import uuid

res = requests.post(
    f"{BASE}/payout/fiat",
    headers={**make_headers(), "Idempotency-Key": str(uuid.uuid4())},
    json={
        "method":        "moneygram",
        "asset":         "usdc",
        "amount":        "100",
        "reference":     "user-8821",
        "first_name":    "John",
        "last_name":     "Doe",
        "mobile_number": "+2348012345678",
        "country":       "NG",
    },
)
data = res.json()["data"]  # {"url": ..., "transactionId": ..., "id": ...}

Identifying the end user with `reference`

MoneyGram payouts accept an optional reference field — a stable identifier for the end user the payout is for. It is sent to MoneyGram for reconciliation, and it also determines which MoneyGram consumer the payout is attributed to.

When you serve many end users through one Tender merchant account, pass a reference so each user maps to a distinct MoneyGram consumer — each with its own KYC record and its own transaction-limit window. Without a reference, every payout collapses into a single consumer for your merchant account, so all your users share one KYC identity and one aggregate limit.

The value must be stable per end user: reuse the same reference for the same person on every payout, and use a different reference for a different person. A per-transaction value (a new order or invoice id each time) would create a new MoneyGram consumer on every payout — re-triggering KYC and fragmenting limits. Omit reference (or set it to your own merchant id) to attribute the payout to your merchant account itself.

Retries and idempotency

Retrying with the same key and body returns the original response; no second payout is made.
Reusing a key with a different body, or while the first request is still running, returns 409.
If the first request failed, the key is released and you can retry with it.
Keys are kept for 24 hours.

Payout status values

Status	Meaning
`pending`	Queued, not yet processed
`processing`	Being handled by the payout provider or MoneyGram
`completed`	Successfully delivered
`failed`	The payout did not go through

Error handling

Scenario	Action
Insufficient balance	Ensure your balance of the asset covers the amount before submitting
`Bank code "…" is not supported`	Verify the bank code against the list of supported Nigerian banks
Below the minimum	`internal`: at least 20 units and $20; `moneygram`: at least 15 units
HTTP 503 `No withdrawal provider available for the selected asset`	MoneyGram doesn’t support this asset right now; try another asset or later
HTTP 409	Retry the same body later, or use a new key for a new payout
`status: "failed"`	Create a new payout with a new key, or contact support

Getting started

Online payments

Subwallets

Webhooks

Prerequisites

Authentication guide

Internal bank transfer

Payout Fiat API reference

MoneyGram payout

Identifying the end user with `reference`

Retries and idempotency

Payout status values

Error handling

​Prerequisites

Authentication guide

​Internal bank transfer

Payout Fiat API reference

​MoneyGram payout

​Identifying the end user with reference

​Retries and idempotency

​Payout status values

​Error handling

Prerequisites

Internal bank transfer

MoneyGram payout

Identifying the end user with `reference`

Retries and idempotency

Payout status values

Error handling