Creating invoice

POST /api/public/v1/invoices

This endpoint creates invoices.

XRP Invoice Addresses Format:

For XRP invoices, addresses are returned in the following format:

rwCQVZLSMNY6DgMH61317qvH3nHYqm68PF?dt=xyz

where xyz is a unique destination tag generated for each invoice.

A destination tag acts like a reference number in bank transfers, identifying the intended beneficiary of the transaction.

Displaying Invoice Deposit Addresses:

• When showing the deposit address to your customers, separate the address and the destination tag, and ensure both are clearly viewable and copyable

Warning: If XRP is sent to the invoice address without specifying the destination tag, the deposit will not be processed.

Headers

Name	Value
Content-Type	application/vnd.api+json
Authorization	Bearer <api_key>

Request Body

Name	Type	Required	Description
data.type	string	Yes	Can only be invoices.
data.attributes.amountBilled	string	Yes	Invoice amount to display to end users. Determines the amount due after conversion.
data.attributes.billedCurrency	string	Yes	Invoice currency to display to end users. Determines the currency due after conversion. Refer to supported currencies.
data.attributes.chargedCurrency	string	Yes	Crypto currency that customer must pay in. Refer to supported currencies.
data.attributes.network	string	Yes	Payment network. Refer to supported networks.
data.attributes.reference	string	No	The custom reference ID to tie the invoice to end-user who pays. This can be anything you choose. Must be a unique value for each invoice you create.
data.attributes.successRedirectUrl	string	No	URL you want your customer to be redirected from our hosted page to if the invoice completes.
data.attributes.unsuccessRedirectUrl	string	No	URL you want your customer to be redirected from our hosted page to if the invoice gets expired, cancelled or rejected.

cURL

curl -X "POST" "https://api.sandbox.txn.pro/api/public/v1/invoices" \
     -H 'Content-Type: application/vnd.api+json' \
     -H 'Authorization: Bearer <api_key>' \
     -d $'{
  "data": {
    "type": "invoices",
    "attributes": {
      "billedCurrency": "usd",
      "reference": "9556e207-b785-4faf-9486-8e79fb442e76",
      "network": "TTRX:USDT",
      "amountBilled": "100",
      "chargedCurrency": "USDT",
      "successRedirectUrl": "https://example.com/success",
      "unsuccessRedirectUrl": "https://example.com/fail"
    }
  }
}'

Response Body

Name	Type	Description
data.id	string	Invoice ID.
data.type	string	Entity type returned. Always invoices.
data.attributes	object	Set of invoice attributes.
data.attributes.amountBilled	string	Invoice amount to display to end users. Determines the amount due after conversion.
data.attributes.amountCharged	string	Amount due. Determines the amount of cryptucurrency the end-user is required to pay.
data.attributes.billedCurrency	string	Invoice currency to display to end users. Determines the currency due after conversion. Refer to supported currencies.
data.attributes.chargedCurrency	string	Crypto currency that customer must pay in. Refer to supported currencies.
data.attributes.reference	string	The custom reference ID to tie the invoice to end-user who pays. This can be anything you choose.
data.attributes.statusContext	string	Invoice status context. Refer to Invoice status flow.
data.attributes.network	string	Network code. Refer to Supported currencies.
data.attributes.networkName	string	Network name to display.
data.attributes.status	string	Invoice status. Refer to Invoice status flow.
data.attributes.successRedirectUrl	string	URL your customer will be redirected from our hosted page to if the invoice completes.
data.attributes.unsuccessRedirectUrl	string	URL your customer will be redirected from our hosted page to if the invoice gets expired, cancelled or rejected.
data.attributes.paymentStatus	string	Invoice payment status. Refer to Invoice status flow.
data.attributes.exchangeRate	string	Invoice exchange rate valid for 20 minutes.
data.attributes.expiresAt	string	Invoice expiry date and time.
data.attributes.createdAt	string	Date and time invoice was created at.
data.attributes.hostedPageUrl	string	Invoice hosted page.
included.type(addresses).attributes	object	Invocie receiving address. This is the address the end-user must send their crytpocurrency payment to.

Response

HTTP 201

{
  "data": {
    "id": "55f7832f-9745-4553-8548-1a06e30fb251",
    "type": "invoices",
    "attributes": {
      "amountBilled": "1000.00",
      "amountCharged": "1011.233592",
      "billedCurrency": "USD",
      "chargedCurrency": "USDT",
      "reference": "9556e207-b785-4faf-9486-8e79fb442e76",
      "statusContext": "unpaid",
      "network": "TTRX:USDT",
      "networkName": "Tron (TRC20)",
      "status": "pending",
      "successRedirectUrl": "https://example.com/success",
      "unsuccessRedirectUrl": "https://example.com/fail",
      "paymentStatus": "expecting",
      "exchangeRate": "0.9888912",
      "expiresAt": "2024-06-14T12:50:53.637Z",
      "createdAt": "2024-06-14T12:30:53.693Z",
      "hostedPageUrl": "https://sandbox.txn.pro/redirect?invoice_id=55f7832f-9745-4553-8548-1a06e30fb251\u0026request_type=invoice_hosted_page"
    },
    "relationships": {
      "address": {
        "data": {
          "type": "addresses",
          "id": "b5c97775-1378-4170-a7f0-78c2c5d60720"
        }
      },
      "invoiceTransactions": {
        "meta": {
          "included": false
        }
      },
      "coinDeposits": {
        "meta": {
          "included": false
        }
      }
    }
  },
  "included": [
    {
      "id": "b5c97775-1378-4170-a7f0-78c2c5d60720",
      "type": "addresses",
      "attributes": {
        "label": "USDT TTRX",
        "value": "TBq5k63KV9q4reE6JEF9e7wTYGo3RUkMQU",
        "createdAt": "2024-06-14T12:18:47.095Z"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}

HTTP 422

{
  "errors": [
    {
      "title": "amount is below minimum",
      "detail": "amount: 10.0, minimum: 30.00",
      "code": "amount_below_minimum"
    }
  ]
}

// Amoun too low.

HTTP 422

{
  "errors": [
    {
      "title": "amount is above maximum",
      "detail": "amount: 500000.0, maximum: 100000.00",
      "code": "amount_above_maximum"
    }
  ]
}

// Amount too high.

HTTP 422

{
  "errors": [
    {
      "title": "Invalid attribute",
      "detail": "Reference has already been taken",
      "code": "invoice_invalid",
      "source": {
        "pointer": "/data/attributes/externalId"
      }
    }
  ]
}

// Dplicate reference.