Initiate Payment

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

fetch('https://secureapi.tender.cash/v1/api/payment/initiate', 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"

payload = {
    "amount": "10.00",
    "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",
  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' => '10.00',
    '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

Initiate Payment

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

fetch('https://secureapi.tender.cash/v1/api/payment/initiate', 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"

payload = {
    "amount": "10.00",
    "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",
  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' => '10.00',
    '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.

Creates a payment request for the outlet your access ID belongs to. Tender generates a unique deposit address, calculates the all-in amount the customer must send, and returns both. Track the payment with Validate Payment or the transaction_requested, transaction_completed and related webhook events. amount is denominated in the outlet’s default fiat currency (USD if the outlet has none set). To price the payment in a specific fiat currency, use Initiate Payment By Fiat Currency. To show the customer the total before creating a payment, use Quote Payment. Payment endpoints share a limit of 120 requests per minute. See Rate limits.

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 outlet’s default fiat currency (USD if none is set). Send it as a decimal string. Tender converts it to the cryptocurrency amount and adds fees on top.Example: "10.00"

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 fiatExample: "10.00"

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 the outlet’s fiat currencyExample: "10.00"

string

The fiat currency amount was priced inExample: "usd"

number

Price of one unit of the cryptocurrency in agentCurrencyExample: 1

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 the outlet’s fiat currencyExample: "10.00"

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`

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 \
  -H "x-access-id: your-access-id-here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10.00",
    "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": "10.00",
    "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": "10.00",
    "agentCurrency": "usd",
    "agentRate": 1,
    "agentRateUSD": 1,
    "balanceRequired": "10.15",
    "balanceRequiredUSD": "10.15",
    "balanceRequiredAgent": "10.00",
    "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

Body

application/json

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

Headers

Body

Response

Errors

Example request

Example response

Authorizations

Headers

Body

Response

​Headers

​Body

​Response

​Errors

​Example request

​Example response

Authorizations

Headers

Body

Response

Headers

Body

Response

Errors

Example request

Example response