Initiate Payment By Fiat Currency

curl --request POST \
  --url https://secureapi.tender.cash/v1/api/payment/initiate/{currency} \
  --header 'Content-Type: <content-type>' \
  --header 'x-access-id: <api-key>' \
  --data '
{
  "amount": "15000",
  "chain": "tron",
  "currency": "usdt",
  "reference": "ORDER-9821",
  "meta": {
    "customerEmail": "customer@example.com"
  }
}
'

const options = {
  method: 'POST',
  headers: {'x-access-id': '<api-key>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    amount: '15000',
    chain: 'tron',
    currency: 'usdt',
    reference: 'ORDER-9821',
    meta: {customerEmail: 'customer@example.com'}
  })
};

fetch('https://secureapi.tender.cash/v1/api/payment/initiate/{currency}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://secureapi.tender.cash/v1/api/payment/initiate/{currency}"

payload = {
    "amount": "15000",
    "chain": "tron",
    "currency": "usdt",
    "reference": "ORDER-9821",
    "meta": { "customerEmail": "customer@example.com" }
}
headers = {
    "x-access-id": "<api-key>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://secureapi.tender.cash/v1/api/payment/initiate/{currency}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => '15000',
    'chain' => 'tron',
    'currency' => 'usdt',
    'reference' => 'ORDER-9821',
    'meta' => [
        'customerEmail' => 'customer@example.com'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: <content-type>",
    "x-access-id: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "status": "success",
  "message": "success",
  "data": {
    "txId": "66aec7de809b7f45c42a49f9",
    "type": "receive",
    "chain": "tron",
    "chainId": "64f782bb4278fc475eb30e29",
    "currency": "64fc4cda43812c15552311d7",
    "walletAddress": "TQn9Y2khDD9JHTfVE5oB2h8BKWWM4LxKLT",
    "gasFreeAddress": "<string>",
    "walletAddressIndex": 7,
    "contractAddress": "<string>",
    "requestedAmount": "10.00",
    "amount": "10.15",
    "coinAmount": "10.15",
    "usdAmount": "10.15",
    "fee": 0.1,
    "feeUSD": 0.1,
    "activationFee": 0,
    "activationFeeUSD": 0,
    "gasFreeServiceFee": 123,
    "gasFreeServiceFeeUSD": 123,
    "feeBreakdown": {
      "settlement": "pending",
      "charged": {
        "receive": {
          "coin": "0.1",
          "usd": 0.1
        },
        "activation": {
          "coin": "0.1",
          "usd": 0.1
        },
        "autoPayoutSwap": {
          "coin": "0.1",
          "usd": 0.1
        },
        "autoPayoutWithdrawal": {
          "coin": "0.1",
          "usd": 0.1
        },
        "gasFreeService": {
          "coin": "0.1",
          "usd": 0.1
        },
        "totalCoin": "0.1",
        "totalUSD": 0.1
      }
    },
    "feeSent": false,
    "rate": 1,
    "fxRateAt": 1,
    "agentAmount": "10.00",
    "agentCurrency": "usd",
    "agentRate": 1,
    "agentRateUSD": 1,
    "balanceRequired": "10.15",
    "balanceRequiredUSD": "10.15",
    "balanceRequiredAgent": "10.00",
    "referenceId": "ORDER-9821",
    "meta": {
      "customerEmail": "<string>"
    },
    "agentId": "6538eaaebdec6d1a21978e6a",
    "merchantId": "6538e8f9bdec6d1a21978a64"
  }
}

{
  "status": "error",
  "message": "Minimum initiated amount is 5 USD",
  "data": null
}

{
  "status": "error",
  "message": "INVALID_REQUEST_SIGNATURE",
  "data": {}
}

{
  "status": "error",
  "message": "You are not authorized to initiate transactions with this currency",
  "data": null
}

{
  "status": "error",
  "message": "A transaction with reference 'ORDER-9821' already exists",
  "data": null
}

{
  "status": "error",
  "message": "Too many requests. Max 120 per 60s.",
  "data": null
}

POST

api

payment

initiate

{currency}

Initiate Payment By Fiat Currency

curl --request POST \
  --url https://secureapi.tender.cash/v1/api/payment/initiate/{currency} \
  --header 'Content-Type: <content-type>' \
  --header 'x-access-id: <api-key>' \
  --data '
{
  "amount": "15000",
  "chain": "tron",
  "currency": "usdt",
  "reference": "ORDER-9821",
  "meta": {
    "customerEmail": "customer@example.com"
  }
}
'

const options = {
  method: 'POST',
  headers: {'x-access-id': '<api-key>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    amount: '15000',
    chain: 'tron',
    currency: 'usdt',
    reference: 'ORDER-9821',
    meta: {customerEmail: 'customer@example.com'}
  })
};

fetch('https://secureapi.tender.cash/v1/api/payment/initiate/{currency}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://secureapi.tender.cash/v1/api/payment/initiate/{currency}"

payload = {
    "amount": "15000",
    "chain": "tron",
    "currency": "usdt",
    "reference": "ORDER-9821",
    "meta": { "customerEmail": "customer@example.com" }
}
headers = {
    "x-access-id": "<api-key>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://secureapi.tender.cash/v1/api/payment/initiate/{currency}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => '15000',
    'chain' => 'tron',
    'currency' => 'usdt',
    'reference' => 'ORDER-9821',
    'meta' => [
        'customerEmail' => 'customer@example.com'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: <content-type>",
    "x-access-id: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "status": "success",
  "message": "success",
  "data": {
    "txId": "66aec7de809b7f45c42a49f9",
    "type": "receive",
    "chain": "tron",
    "chainId": "64f782bb4278fc475eb30e29",
    "currency": "64fc4cda43812c15552311d7",
    "walletAddress": "TQn9Y2khDD9JHTfVE5oB2h8BKWWM4LxKLT",
    "gasFreeAddress": "<string>",
    "walletAddressIndex": 7,
    "contractAddress": "<string>",
    "requestedAmount": "10.00",
    "amount": "10.15",
    "coinAmount": "10.15",
    "usdAmount": "10.15",
    "fee": 0.1,
    "feeUSD": 0.1,
    "activationFee": 0,
    "activationFeeUSD": 0,
    "gasFreeServiceFee": 123,
    "gasFreeServiceFeeUSD": 123,
    "feeBreakdown": {
      "settlement": "pending",
      "charged": {
        "receive": {
          "coin": "0.1",
          "usd": 0.1
        },
        "activation": {
          "coin": "0.1",
          "usd": 0.1
        },
        "autoPayoutSwap": {
          "coin": "0.1",
          "usd": 0.1
        },
        "autoPayoutWithdrawal": {
          "coin": "0.1",
          "usd": 0.1
        },
        "gasFreeService": {
          "coin": "0.1",
          "usd": 0.1
        },
        "totalCoin": "0.1",
        "totalUSD": 0.1
      }
    },
    "feeSent": false,
    "rate": 1,
    "fxRateAt": 1,
    "agentAmount": "10.00",
    "agentCurrency": "usd",
    "agentRate": 1,
    "agentRateUSD": 1,
    "balanceRequired": "10.15",
    "balanceRequiredUSD": "10.15",
    "balanceRequiredAgent": "10.00",
    "referenceId": "ORDER-9821",
    "meta": {
      "customerEmail": "<string>"
    },
    "agentId": "6538eaaebdec6d1a21978e6a",
    "merchantId": "6538e8f9bdec6d1a21978a64"
  }
}

{
  "status": "error",
  "message": "Minimum initiated amount is 5 USD",
  "data": null
}

{
  "status": "error",
  "message": "INVALID_REQUEST_SIGNATURE",
  "data": {}
}

{
  "status": "error",
  "message": "You are not authorized to initiate transactions with this currency",
  "data": null
}

{
  "status": "error",
  "message": "A transaction with reference 'ORDER-9821' already exists",
  "data": null
}

{
  "status": "error",
  "message": "Too many requests. Max 120 per 60s.",
  "data": null
}

Auth method: Basic (Access ID) — this endpoint only requires your x-access-id header. No request signing is needed. See Authentication.

Works exactly like Initiate Payment, except that amount is denominated in the fiat currency you name in the path instead of the outlet’s default fiat currency. Tender converts it to the cryptocurrency at the current rate. If the path currency is the outlet’s default fiat currency and the outlet uses a manual rate, the manual rate applies. Payment endpoints share a limit of 120 requests per minute. See Rate limits.

Path Parameters

string

required

Fiat currency code that amount is priced in, such as ngn or usd. Use a fiat currency listed by Fetch All Currencies with type=fiat. This is a fiat code, not the cryptocurrency the customer pays with.Example: "ngn"

Headers

string

required

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

string

required

Media type of the request bodyExample: "application/json"

Body

string

required

The price to charge, in the fiat currency named in the path. Send it as a decimal string. Tender converts it to the cryptocurrency amount and adds fees on top.Example: "15000"

string

required

Chain identifier, as returned by Fetch Allowed ChainsExample: "tron"

string

required

Cryptocurrency identifier, as returned by Fetch Chain Currencies. The currency must be supported on chain and allowed for your outlet.Example: "usdt"

string

Your own reference for this payment, such as an order ID. referenceId is accepted as an alias. A reference can be used by only one payment at a time: reusing the reference of a payment that isn’t cancelled returns 409.Example: "ORDER-9821"

object

Optional metadata attached to the payment. Only the keys below are stored; any other keys are ignored.

Show meta properties

string

The customer’s email address. Must be a valid email.Example: "customer@example.com"

Response

string

required

Status of the API requestExample: "success"

string

required

Human-readable message describing the resultExample: "success"

object

required

The new payment request. Additional fields may be present; ignore fields you don’t recognise.

Show data properties

string

The payment’s transaction ID. Use it to validate or cancel the payment.Example: "66aec7de809b7f45c42a49f9"

string

Transaction type. Always receive for payments.Example: "receive"

string

Chain identifierExample: "tron"

string

Internal ID of the chain recordExample: "64f782bb4278fc475eb30e29"

string

Internal ID of the cryptocurrency recordExample: "64fc4cda43812c15552311d7"

string

The deposit address the customer must pay toExample: "TQn9Y2khDD9JHTfVE5oB2h8BKWWM4LxKLT"

string

Present on chains where Tender collects payments through a gasless deposit address. When present, it equals walletAddress.Example: "TQn9Y2khDD9JHTfVE5oB2h8BKWWM4LxKLT"

number

Index of the generated deposit addressExample: 7

string | null

Token contract address, or null for a native coinExample: "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"

string

The amount you sent, in the path fiat currencyExample: "15000"

string

The all-in cryptocurrency amount the customer must send: the payment plus every fee. Show this amount to the customer.Example: "10.15"

string

Same as amountExample: "10.15"

string

USD value of amountExample: "10.15"

number

Fees charged on this payment, in the cryptocurrency: the receive fee, any activation fee and any auto-payout fees. The Tron gasless service fee is reported separately in gasFreeServiceFee.Example: 0.1

number

fee in USDExample: 0.1

number

Activation fee included in fee, if anyExample: 0

number

activationFee in USDExample: 0

number

Tron gasless network service fee added to amount. Omitted when it doesn’t apply.Example: 0.05

number

gasFreeServiceFee in USD. Omitted when it doesn’t apply.Example: 0.05

object

Itemised fees charged to the customer

Show feeBreakdown properties

string

Fee settlement stateExample: "pending"

object

Each fee leg as { coin, usd }, where coin is a string and usd a number: receive, activation, autoPayoutSwap, autoPayoutWithdrawal and gasFreeService. totalCoin (string) and totalUSD (number) equal fee and feeUSD.

boolean

Whether the fee has been collected. Always false at initiation.Example: false

number

USD price of one unit of the cryptocurrency at initiationExample: 1

number

The USD rate used to calculate usdAmount, frozen at initiationExample: 1

string

The requested amount in agentCurrencyExample: "15000"

string

The fiat currency amount was priced in (the path currency)Example: "ngn"

number

Price of one unit of the cryptocurrency in agentCurrencyExample: 1500

number

USD price of one unit of the cryptocurrency, or the outlet’s manual rate if it uses oneExample: 1

string

Cryptocurrency amount still owed. Equals amount at initiation.Example: "10.15"

string

balanceRequired in USDExample: "10.15"

string

Amount still owed in agentCurrencyExample: "15000"

string

Your reference, if you sent oneExample: "ORDER-9821"

object

The metadata you sent, if anyExample: {"customerEmail": "customer@example.com"}

string

ID of the outlet receiving the paymentExample: "6538eaaebdec6d1a21978e6a"

string

ID of your merchant accountExample: "6538e8f9bdec6d1a21978a64"

The initiate response has no status field. A new payment always starts as pending; call Validate Payment to read its current status.

Errors

HTTP	Message	Cause
400	`currency must be a string` (or another validation message)	A required field is missing or has the wrong type
400	`Invalid chain` / `Chain not active`	Unknown or disabled `chain`
400	`invalid Currency` / `Currency not allowed`	Unknown `currency`, or not supported on `chain`
400	`Amount can't be Zero`	`amount` is zero or negative
400	`Minimum initiated amount is <n> USD`	The payment is below the minimum
400	`Invalid Coin Exchange Price`	No price is available for the currency right now
403	`You are not authorized to initiate transactions with this currency`	The currency isn’t in your outlet’s allowed currencies
409	`A transaction with reference '<reference>' already exists`	Another payment that isn’t cancelled already uses this `reference`

An unsupported fiat code in the path fails the request; use a code listed by Fetch All Currencies. Error responses use the standard envelope with data: null. See Errors.

Example request

curl -X POST https://sandbox-api.tender.cash/v1/api/payment/initiate/ngn \
  -H "x-access-id: your-access-id-here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "15000",
    "chain": "tron",
    "currency": "usdt",
    "reference": "ORDER-9821",
    "meta": { "customerEmail": "customer@example.com" }
  }'

Example response

{
  "status": "success",
  "message": "success",
  "data": {
    "txId": "66aec7de809b7f45c42a49f9",
    "type": "receive",
    "chain": "tron",
    "chainId": "64f782bb4278fc475eb30e29",
    "currency": "64fc4cda43812c15552311d7",
    "walletAddress": "TQn9Y2khDD9JHTfVE5oB2h8BKWWM4LxKLT",
    "gasFreeAddress": "TQn9Y2khDD9JHTfVE5oB2h8BKWWM4LxKLT",
    "walletAddressIndex": 7,
    "contractAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "requestedAmount": "15000",
    "amount": "10.15",
    "coinAmount": "10.15",
    "usdAmount": "10.15",
    "fee": 0.1,
    "feeUSD": 0.1,
    "activationFee": 0,
    "activationFeeUSD": 0,
    "gasFreeServiceFee": 0.05,
    "gasFreeServiceFeeUSD": 0.05,
    "feeBreakdown": {
      "settlement": "pending",
      "charged": {
        "receive": { "coin": "0.1", "usd": 0.1 },
        "activation": { "coin": "0", "usd": 0 },
        "autoPayoutSwap": { "coin": "0", "usd": 0 },
        "autoPayoutWithdrawal": { "coin": "0", "usd": 0 },
        "gasFreeService": { "coin": "0.05", "usd": 0.05 },
        "totalCoin": "0.1",
        "totalUSD": 0.1
      }
    },
    "feeSent": false,
    "rate": 1,
    "fxRateAt": 1,
    "agentAmount": "15000",
    "agentCurrency": "ngn",
    "agentRate": 1500,
    "agentRateUSD": 1,
    "balanceRequired": "10.15",
    "balanceRequiredUSD": "10.15",
    "balanceRequiredAgent": "15000",
    "referenceId": "ORDER-9821",
    "meta": { "customerEmail": "customer@example.com" },
    "agentId": "6538eaaebdec6d1a21978e6a",
    "merchantId": "6538e8f9bdec6d1a21978a64"
  }
}

Authorizations

x-access-id

string

header

required

Basic (Access ID) authentication. Only the x-access-id header is required; no request signing.

Headers

x-access-id

string

required

Your API access ID provided by Tender

Content-Type

string

required

Media type of the request body

Path Parameters

currency

string

required

Fiat currency code that amount is priced in (e.g. ngn, usd). Not the cryptocurrency.

Body

application/json

Same fields as InitiatePaymentRequest; amount is in the fiat currency named in the path.

amount

string

required

Price in the outlet's default fiat currency (USD if none is set), as a decimal string

Example:

"10.00"

chain

string

required

Chain identifier

Example:

"tron"

currency

string

required

Cryptocurrency identifier; must be supported on chain and allowed for the outlet

Example:

"usdt"

reference

string

Your own reference, such as an order ID. Must not be in use by another payment that isn't cancelled.

Maximum string length: 500

Example:

"ORDER-9821"

referenceId

string

Alias of reference

Maximum string length: 500

Response

Payment initiated

status

string

Example:

"success"

message

string

Example:

"success"

data

object

Additional fields may be present; ignore fields you don't recognise.

Show child attributes

Payment

Transactions

System

Agents

Conversions

Payouts

Subwallets

Webhooks

On-ramp

Initiate Payment By Fiat Currency

Path Parameters

Headers

Body

Response

Errors

Example request

Example response

Authorizations

Headers

Path Parameters

Body

Response

​Path Parameters

​Headers

​Body

​Response

​Errors

​Example request

​Example response

Authorizations

Headers

Path Parameters

Body

Response

Path Parameters

Headers

Body

Response

Errors

Example request

Example response