2Pay API [ v1 ]

The 2Pay API lets banks, fintechs and other companies buy and sell USDT for Azerbaijani manat (AZN) from their own systems. It is a REST API over HTTPS: JSON requests and replies, every call signed with your API key.

Buy: you pay AZN by bank transfer and 2Pay sends USDT to your wallet. Sell: you send USDT to 2Pay's deposit address and 2Pay pays AZN to your company's bank account. A 2Pay operator checks every payment before anything is sent; nothing is sent automatically.

Access is by agreement: the 2Pay team onboards each partner after due diligence (KYB). There is no self-service sign-up. Request access.

Base URL

https://api.2pay.az/v1

Signing

HMAC-SHA256

Quotes

5 min, single use

Payment window

2 hours

Webhooks

10 retries, about 28 h

Rate limit

120 a minute per key

Minimum order

10 AZN

Networks

8, USDT only

1. 01Get your API key (tp_live_…) and secret (tps_…) from the 2Pay team. The secret is shown once: keep it in a secrets manager on your server.
2. 02Send 2Pay the public IP addresses of your servers (for the key's allowlist) and your webhook URL (https).
3. 03Sign a call to GET /v1/account to check your setup: it returns your company, limits and keys.
4. 04Ask for a quote with POST /v1/quotes, then place the order with POST /v1/orders within 5 minutes.
5. 05Pay as paymentInstructions says, report it with POST /v1/orders/{id}/payment, and follow the status by webhook or with GET /v1/orders/{id}.

# Check the setup.
twopay GET /v1/account

# Lock a price for 5 minutes: buy USDT for 1,700.00 AZN on TRON.
twopay POST /v1/quotes '{"side":"buy","amount":"1700.00","network":"TRC20"}'

# Place the order with the quote id and your own unique id.
twopay POST /v1/orders '{"quoteId":"3c8f5e2a-91d4-4b6e-a7f0-5d2e8c1b9a46","clientOrderId":"inv-20261015-0042","walletAddress":"<your TRC20 address>"}'

# After the bank transfer, report your bank's reference for it.
twopay POST /v1/orders/inv-20261015-0042/payment '{"reference":"FT26288QX7Z1"}'

# Follow the status (webhooks tell you too).
twopay GET /v1/orders/inv-20261015-0042

Every endpoint is under https://api.2pay.az/v1. There is one environment, production: no sandbox and no test mode. Once your account is set up, test with small real orders; the minimum order value is 10 AZN.

Use HTTPS only. Every reply carries an X-Request-Id header (req_…); quote it when you write to 2Pay about a call. Replies can gain new fields over time, so ignore fields you do not know.

Every call except GET /v1/openapi.yaml is signed with HMAC-SHA256 and carries three headers:

<X-Timestamp>
<HTTP method in upper case>
<path and query string exactly as sent, e.g. /v1/orders?status=completed&limit=20>
<hex SHA-256 of the raw request body>

• Sign the exact bytes you send: serialize the JSON once and send that string. Build the query string yourself and send it unchanged.
• A call without a body (every GET, POST …/cancel, POST /v1/webhooks/test) hashes the empty string: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.
• Each signature works once. Sign every retry again with a new timestamp; a repeated signature returns 401 INVALID_SIGNATURE.
• Missing headers return 401 UNAUTHENTICATED. An unknown or revoked key, a wrong signature or a timestamp more than 5 minutes off return 401 INVALID_SIGNATURE. An IP address outside the key's allowlist, or a suspended account, return 403 FORBIDDEN.
• Keep your server clock synchronised (NTP).

# Bash 4+, GNU date, OpenSSL and curl. Export TWOPAY_KEY and TWOPAY_SECRET first.
twopay() {
  local method=$1 path=$2 body=${3-}
  local ts body_hash signature
  ts=$(date +%s%3N)  # Unix time in milliseconds
  body_hash=$(printf '%s' "$body" | openssl dgst -sha256 -r | cut -d' ' -f1)
  signature=$(printf '%s\n%s\n%s\n%s' "$ts" "$method" "$path" "$body_hash" \
    | openssl dgst -sha256 -hmac "$TWOPAY_SECRET" -r | cut -d' ' -f1)
  curl -sS -X "$method" "https://api.2pay.az$path" \
    -H "Content-Type: application/json" \
    -H "X-Api-Key: $TWOPAY_KEY" \
    -H "X-Timestamp: $ts" \
    -H "X-Signature: $signature" \
    ${body:+--data-raw "$body"}
}

twopay GET /v1/account
twopay POST /v1/quotes '{"side":"buy","amount":"1700.00","network":"TRC20"}'

• Send JSON in UTF-8 with Content-Type: application/json. A body can be at most 64 KB; a bigger one returns 400 VALIDATION_ERROR. Unknown fields are ignored.
• Money is a decimal string, never a number: AZN with 2 decimals ("1700.00"), USDT with 6 ("969.252507"). Send amount as a string too. A Money object is {"amount": "…", "currency": "AZN" | "USDT"}.
• Rates are AZN per 1 USDT. platformRate is a fraction: "0.010000" is 1%.
• Times are ISO 8601 in UTC with milliseconds, e.g. 2026-10-15T09:31:05.120Z.
• Ids are UUIDs; order references look like 2P-7KQ4M9XD. Empty fields are null, not left out (except in paymentInstructions).

Errors come in one envelope with a stable code and an English message for people. Program against the code: messages can change. VALIDATION_ERROR messages start with the field name, e.g. amount: AZN amount with at most 2 decimals. See Errors.

{
  "error": {
    "code": "QUOTE_EXPIRED",
    "message": "The quote has expired. Request a new one."
  }
}

• POST /v1/orders takes clientOrderId, your own unique id for the order (1–64 characters of A–Z a–z 0–9 . _ : -). Use an id from your system, such as a payment or invoice id, not a new random one per attempt.
• Sending it again with the same clientOrderId and the same quoteId returns the existing order with 200 OK and the header Idempotent-Replayed: true instead of 201 Created, even after the quote has expired. Two calls at the same moment still make one order.
• The same clientOrderId with a different quoteId returns 409 IDEMPOTENCY_CONFLICT.
• walletAddress is not compared on a replay: the order keeps the address it was created with.
• A quote backs one order: using it with a new clientOrderId returns 409 QUOTE_ALREADY_USED.
• clientOrderId works in place of the order id in every /v1/orders/{id} path.
• Reporting a payment or cancelling changes an order once: repeating it returns 409 ORDER_NOT_AWAITING_PAYMENT or 409 ORDER_NOT_CANCELLABLE.

• 120 requests a minute per API key, counting the calls that pass the signature check.
• 300 requests a minute per client IP address, counting every signed call before it is checked. GET /v1/openapi.yaml is not limited.
• Each 2Pay gateway process counts on its own, in one-minute windows that start with the first request.
• Over a limit you get 429 RATE_LIMITED without a Retry-After header. Back off, then retry with a new signature.

• Minimum order value: 10 AZN. The value of an order is in AZN: what you pay (buy) or what 2Pay pays you (sell).
• Maximum per order: your maxOrderAzn (100,000.00 AZN unless your agreement sets another). Checked when you ask for a quote, and again when you place a sell order: 422 AMOUNT_OUT_OF_RANGE. A quote too small to cover the fees gets the same code.
• Daily limit: your dailyLimitAzn (500,000.00 AZN unless your agreement sets another) per UTC day, 00:00–24:00 UTC. Checked when you place an order: the value of today's orders, not counting rejected, expired and cancelled ones, plus the new order must fit, otherwise 422 LIMIT_EXCEEDED.
• Quote validity: 5 minutes (expiresAt).
• Payment window: 2 hours from the order (paymentDeadline); then an unpaid order becomes expired.
• GET /v1/account shows your limits.

An order has one of six statuses. completed, rejected, expired and cancelled are final. A webhook is sent when the order is created and at every change.

1. 01Quote: POST /v1/quotes with side "buy", amount in AZN and network, one of buyNetworks in GET /v1/rates. receive.amount is the USDT you get after fees.
2. 02Order: POST /v1/orders with quoteId, clientOrderId and walletAddress, your USDT address on that network. The address is checked first.
3. 03Pay: transfer exactly paymentInstructions.amount AZN to paymentInstructions.bankAccount with paymentInstructions.reference (the order reference) in the transfer description, before paymentDeadline.
4. 04Report: POST /v1/orders/{id}/payment with reference, your bank's reference for the transfer. The order becomes payment_submitted.
5. 05Settlement: a 2Pay operator matches the transfer and sends the USDT to walletAddress. The order becomes completed, with payoutTxHash when recorded, or rejected with rejectionReason.

Example: 1,700.00 AZN at a rate of 1.7346 with a 1% platform fee and a 1 USDT network fee gives (1700 ÷ 1.7346) × 0.99 − 1 = 969.252507 USDT.

1. 01Networks: sellNetworks in GET /v1/rates lists where you can sell now.
2. 02Quote: POST /v1/quotes with side "sell", amount in USDT and network. receive.amount is the AZN for that amount; the order asks for its own amount close to it (see below), and the order's send and receive are what you send and what 2Pay pays.
3. 03Order: POST /v1/orders with quoteId and clientOrderId, without walletAddress. Your account needs a payout bank account registered by 2Pay (a new payout account takes effect once a second 2Pay staff member approves it); without one the call returns 400 VALIDATION_ERROR.
4. 04Send: transfer exactly paymentInstructions.amount USDT on paymentInstructions.network to paymentInstructions.address before paymentDeadline. It is 2Pay's deposit address for that network, shared and not made for your order: send only USDT, only on that network. Do not send while paymentInstructions.paused is true.
5. 05Own amount: the order asks for its own USDT amount, the quote's cut to whole cents plus 0.01–0.99 USDT (below the quote's near the top of your limits), so a transfer to the shared address matches one order only. send and receive on the order show that amount and the AZN for it, at the quote's rate. Send it to the cent; if every amount near the quote's is taken by other open sales on the network, 409 AMOUNT_BUSY.
6. 06Report: POST /v1/orders/{id}/payment with txHash, the hash of your transaction. One transaction backs one order (409 TX_ALREADY_USED).
7. 07Settlement: 2Pay looks your transaction up on its blockchain (that 2Pay's deposit address received the order's USDT in it and that it is final), then a 2Pay operator pays the AZN to your payout account. The order becomes completed, or rejected with rejectionReason.

Example: 1,000 USDT at a rate of 1.6984 with a 1% platform fee and a 1 USDT network fee gives (1000 − 1) × 1.6984 × 0.99 = 1,679.73 AZN.

Paths are relative to https://api.2pay.az. Besides its own errors, every signed endpoint can return VALIDATION_ERROR, UNAUTHENTICATED, INVALID_SIGNATURE, FORBIDDEN, RATE_LIMITED, INTERNAL_ERROR and SERVICE_UNAVAILABLE.

The order object

{
  "id": "6f1d2c8e-4b7a-4e0f-9a51-3c2d8e7f1a90",
  "reference": "2P-7KQ4M9XD",
  "clientOrderId": "inv-20261015-0042",
  "side": "buy",
  "status": "pending_payment",
  "network": "TRC20",
  "walletAddress": "<your TRC20 address>",
  "send": {
    "amount": "1700.00",
    "currency": "AZN"
  },
  "receive": {
    "amount": "969.252507",
    "currency": "USDT"
  },
  "rate": "1.73460000",
  "fees": {
    "network": {
      "amount": "1.000000",
      "currency": "USDT"
    },
    "platformRate": "0.010000"
  },
  "paymentInstructions": {
    "method": "bank_transfer",
    "amount": {
      "amount": "1700.00",
      "currency": "AZN"
    },
    "bankAccount": "<2Pay bank account details>",
    "reference": "2P-7KQ4M9XD"
  },
  "paymentReference": null,
  "depositTxHash": null,
  "payoutTxHash": null,
  "rejectionReason": null,
  "paymentDeadline": "2026-10-15T11:31:05.120Z",
  "createdAt": "2026-10-15T09:31:05.120Z",
  "updatedAt": "2026-10-15T09:31:05.120Z"
}

GET /v1/rates HTTP/1.1
Host: api.2pay.az
X-Api-Key: tp_live_ed698ee2317701eaaccfacf9
X-Timestamp: 1792056665120
X-Signature: <hex HMAC-SHA256 of the canonical string>

{
  "buy": {
    "rate": "1.7346",
    "platformRate": "0.01",
    "networkFees": {
      "TRC20": "1",
      "BEP20": "0.5",
      "SOL": "1",
      "ARBITRUM": "0.5",
      "AVAXC": "0.5",
      "TON": "0.5",
      "ERC20": "5",
      "MANTLE": "0.5"
    }
  },
  "sell": {
    "rate": "1.6984",
    "platformRate": "0.01",
    "networkFees": {
      "TRC20": "1",
      "BEP20": "0.5",
      "SOL": "1",
      "ARBITRUM": "0.5",
      "AVAXC": "0.5",
      "TON": "0.5",
      "ERC20": "5",
      "MANTLE": "0.5"
    }
  },
  "buyNetworks": [
    "TRC20",
    "BEP20",
    "SOL",
    "ARBITRUM",
    "AVAXC",
    "TON",
    "ERC20",
    "MANTLE"
  ],
  "sellNetworks": [
    "TRC20",
    "BEP20",
    "TON"
  ],
  "fetchedAt": "2026-10-15T09:30:58.000Z"
}

POST /v1/quotes HTTP/1.1
Host: api.2pay.az
X-Api-Key: tp_live_ed698ee2317701eaaccfacf9
X-Timestamp: 1792056665120
X-Signature: <hex HMAC-SHA256 of the canonical string>
Content-Type: application/json

{
  "side": "buy",
  "amount": "1700.00",
  "network": "TRC20"
}

{
  "id": "3c8f5e2a-91d4-4b6e-a7f0-5d2e8c1b9a46",
  "side": "buy",
  "network": "TRC20",
  "send": {
    "amount": "1700.00",
    "currency": "AZN"
  },
  "receive": {
    "amount": "969.252507",
    "currency": "USDT"
  },
  "rate": "1.73460000",
  "fees": {
    "network": {
      "amount": "1.000000",
      "currency": "USDT"
    },
    "platformRate": "0.010000"
  },
  "expiresAt": "2026-10-15T09:35:58.410Z"
}

POST /v1/orders HTTP/1.1
Host: api.2pay.az
X-Api-Key: tp_live_ed698ee2317701eaaccfacf9
X-Timestamp: 1792056665120
X-Signature: <hex HMAC-SHA256 of the canonical string>
Content-Type: application/json

{
  "quoteId": "3c8f5e2a-91d4-4b6e-a7f0-5d2e8c1b9a46",
  "clientOrderId": "inv-20261015-0042",
  "walletAddress": "<your TRC20 address>"
}

{
  "id": "6f1d2c8e-4b7a-4e0f-9a51-3c2d8e7f1a90",
  "reference": "2P-7KQ4M9XD",
  "clientOrderId": "inv-20261015-0042",
  "side": "buy",
  "status": "pending_payment",
  "network": "TRC20",
  "walletAddress": "<your TRC20 address>",
  "send": {
    "amount": "1700.00",
    "currency": "AZN"
  },
  "receive": {
    "amount": "969.252507",
    "currency": "USDT"
  },
  "rate": "1.73460000",
  "fees": {
    "network": {
      "amount": "1.000000",
      "currency": "USDT"
    },
    "platformRate": "0.010000"
  },
  "paymentInstructions": {
    "method": "bank_transfer",
    "amount": {
      "amount": "1700.00",
      "currency": "AZN"
    },
    "bankAccount": "<2Pay bank account details>",
    "reference": "2P-7KQ4M9XD"
  },
  "paymentReference": null,
  "depositTxHash": null,
  "payoutTxHash": null,
  "rejectionReason": null,
  "paymentDeadline": "2026-10-15T11:31:05.120Z",
  "createdAt": "2026-10-15T09:31:05.120Z",
  "updatedAt": "2026-10-15T09:31:05.120Z"
}

GET /v1/orders?status=payment_submitted&limit=20 HTTP/1.1
Host: api.2pay.az
X-Api-Key: tp_live_ed698ee2317701eaaccfacf9
X-Timestamp: 1792056665120
X-Signature: <hex HMAC-SHA256 of the canonical string>

{
  "data": [
    {
      "id": "b2e4a7c1-0d9f-4e3a-8c6b-1f5d7e9a2c48",
      "reference": "2P-H3TZ8RWE",
      "clientOrderId": "payout-20261015-0007",
      "side": "sell",
      "status": "payment_submitted",
      "network": "TRC20",
      "walletAddress": null,
      "send": {
        "amount": "1000.370000",
        "currency": "USDT"
      },
      "receive": {
        "amount": "1680.35",
        "currency": "AZN"
      },
      "rate": "1.69840000",
      "fees": {
        "network": {
          "amount": "1.000000",
          "currency": "USDT"
        },
        "platformRate": "0.010000"
      },
      "paymentInstructions": {
        "method": "crypto_deposit",
        "amount": {
          "amount": "1000.370000",
          "currency": "USDT"
        },
        "network": "TRC20",
        "address": "<2Pay TRC20 deposit address>"
      },
      "paymentReference": null,
      "depositTxHash": "9c1e0b5a7d3f42e6b8a1c4d7e2f05b9a3c6d8e1f4a7b0c3d6e9f2a5b8c1d4e7f",
      "payoutTxHash": null,
      "rejectionReason": null,
      "paymentDeadline": "2026-10-15T12:02:40.300Z",
      "createdAt": "2026-10-15T10:02:40.300Z",
      "updatedAt": "2026-10-15T10:09:12.870Z"
    }
  ],
  "nextCursor": "MjAyNi0xMC0xNVQwOTozMTowNS4xMlp8NmYxZDJjOGUtNGI3YS00ZTBmLTlhNTEtM2MyZDhlN2YxYTkw"
}

GET /v1/orders/inv-20261015-0042 HTTP/1.1
Host: api.2pay.az
X-Api-Key: tp_live_ed698ee2317701eaaccfacf9
X-Timestamp: 1792056665120
X-Signature: <hex HMAC-SHA256 of the canonical string>

{
  "id": "6f1d2c8e-4b7a-4e0f-9a51-3c2d8e7f1a90",
  "reference": "2P-7KQ4M9XD",
  "clientOrderId": "inv-20261015-0042",
  "side": "buy",
  "status": "pending_payment",
  "network": "TRC20",
  "walletAddress": "<your TRC20 address>",
  "send": {
    "amount": "1700.00",
    "currency": "AZN"
  },
  "receive": {
    "amount": "969.252507",
    "currency": "USDT"
  },
  "rate": "1.73460000",
  "fees": {
    "network": {
      "amount": "1.000000",
      "currency": "USDT"
    },
    "platformRate": "0.010000"
  },
  "paymentInstructions": {
    "method": "bank_transfer",
    "amount": {
      "amount": "1700.00",
      "currency": "AZN"
    },
    "bankAccount": "<2Pay bank account details>",
    "reference": "2P-7KQ4M9XD"
  },
  "paymentReference": null,
  "depositTxHash": null,
  "payoutTxHash": null,
  "rejectionReason": null,
  "paymentDeadline": "2026-10-15T11:31:05.120Z",
  "createdAt": "2026-10-15T09:31:05.120Z",
  "updatedAt": "2026-10-15T09:31:05.120Z"
}

POST /v1/orders/inv-20261015-0042/payment HTTP/1.1
Host: api.2pay.az
X-Api-Key: tp_live_ed698ee2317701eaaccfacf9
X-Timestamp: 1792056665120
X-Signature: <hex HMAC-SHA256 of the canonical string>
Content-Type: application/json

{
  "reference": "FT26288QX7Z1"
}

{
  "id": "6f1d2c8e-4b7a-4e0f-9a51-3c2d8e7f1a90",
  "reference": "2P-7KQ4M9XD",
  "clientOrderId": "inv-20261015-0042",
  "side": "buy",
  "status": "payment_submitted",
  "network": "TRC20",
  "walletAddress": "<your TRC20 address>",
  "send": {
    "amount": "1700.00",
    "currency": "AZN"
  },
  "receive": {
    "amount": "969.252507",
    "currency": "USDT"
  },
  "rate": "1.73460000",
  "fees": {
    "network": {
      "amount": "1.000000",
      "currency": "USDT"
    },
    "platformRate": "0.010000"
  },
  "paymentInstructions": {
    "method": "bank_transfer",
    "amount": {
      "amount": "1700.00",
      "currency": "AZN"
    },
    "bankAccount": "<2Pay bank account details>",
    "reference": "2P-7KQ4M9XD"
  },
  "paymentReference": "FT26288QX7Z1",
  "depositTxHash": null,
  "payoutTxHash": null,
  "rejectionReason": null,
  "paymentDeadline": "2026-10-15T11:31:05.120Z",
  "createdAt": "2026-10-15T09:31:05.120Z",
  "updatedAt": "2026-10-15T09:44:20.016Z"
}

POST /v1/orders/inv-20261015-0042/cancel HTTP/1.1
Host: api.2pay.az
X-Api-Key: tp_live_ed698ee2317701eaaccfacf9
X-Timestamp: 1792056665120
X-Signature: <hex HMAC-SHA256 of the canonical string>

{
  "id": "6f1d2c8e-4b7a-4e0f-9a51-3c2d8e7f1a90",
  "reference": "2P-7KQ4M9XD",
  "clientOrderId": "inv-20261015-0042",
  "side": "buy",
  "status": "cancelled",
  "network": "TRC20",
  "walletAddress": "<your TRC20 address>",
  "send": {
    "amount": "1700.00",
    "currency": "AZN"
  },
  "receive": {
    "amount": "969.252507",
    "currency": "USDT"
  },
  "rate": "1.73460000",
  "fees": {
    "network": {
      "amount": "1.000000",
      "currency": "USDT"
    },
    "platformRate": "0.010000"
  },
  "paymentInstructions": {
    "method": "bank_transfer",
    "amount": {
      "amount": "1700.00",
      "currency": "AZN"
    },
    "bankAccount": "<2Pay bank account details>",
    "reference": "2P-7KQ4M9XD"
  },
  "paymentReference": null,
  "depositTxHash": null,
  "payoutTxHash": null,
  "rejectionReason": null,
  "paymentDeadline": "2026-10-15T11:31:05.120Z",
  "createdAt": "2026-10-15T09:31:05.120Z",
  "updatedAt": "2026-10-15T09:40:02.550Z"
}

GET /v1/account HTTP/1.1
Host: api.2pay.az
X-Api-Key: tp_live_ed698ee2317701eaaccfacf9
X-Timestamp: 1792056665120
X-Signature: <hex HMAC-SHA256 of the canonical string>

{
  "id": "0b7c6a2e-5d1f-4c3b-8e9a-2f4d6b8c0a1e",
  "name": "Example Bank OJSC",
  "status": "active",
  "payoutAccount": "<your AZN bank account>",
  "maxOrderAzn": "100000.00",
  "dailyLimitAzn": "500000.00",
  "webhookUrl": "https://example.com/webhooks/2pay",
  "createdAt": "2026-10-13T08:00:00.000Z",
  "kind": "bank",
  "taxId": "1234567890",
  "contactEmail": "treasury@example.com",
  "keys": [
    {
      "id": "tp_live_ed698ee2317701eaaccfacf9",
      "label": "Production",
      "allowedIps": [
        "203.0.113.10/32"
      ],
      "createdAt": "2026-10-13T08:05:00.000Z",
      "lastUsedAt": "2026-10-15T09:31:05.000Z",
      "revokedAt": null
    }
  ]
}

POST /v1/webhooks/test HTTP/1.1
Host: api.2pay.az
X-Api-Key: tp_live_ed698ee2317701eaaccfacf9
X-Timestamp: 1792056665120
X-Signature: <hex HMAC-SHA256 of the canonical string>

{
  "delivered": true,
  "status": 204,
  "error": null
}

GET /v1/openapi.yaml HTTP/1.1
Host: api.2pay.az

openapi: 3.1.0
info:
  title: 2Pay API
  …

2Pay POSTs an event to your webhook URL when one of your orders is created, every time its status changes, and when a sell order's deposit address is paused or resumed. 2Pay sets the URL (https only) on your account; the signing secret (whsec_…) is shown once.

{
  "id": "evt_1842",
  "type": "order.updated",
  "createdAt": "2026-10-15T09:44:20.016Z",
  "data": {
    "status": "payment_submitted",
    "order": {
      "id": "6f1d2c8e-4b7a-4e0f-9a51-3c2d8e7f1a90",
      "reference": "2P-7KQ4M9XD",
      "clientOrderId": "inv-20261015-0042",
      "side": "buy",
      "status": "payment_submitted",
      "network": "TRC20",
      "walletAddress": "<your TRC20 address>",
      "send": {
        "amount": "1700.00",
        "currency": "AZN"
      },
      "receive": {
        "amount": "969.252507",
        "currency": "USDT"
      },
      "rate": "1.73460000",
      "fees": {
        "network": {
          "amount": "1.000000",
          "currency": "USDT"
        },
        "platformRate": "0.010000"
      },
      "paymentInstructions": {
        "method": "bank_transfer",
        "amount": {
          "amount": "1700.00",
          "currency": "AZN"
        },
        "bankAccount": "<2Pay bank account details>",
        "reference": "2P-7KQ4M9XD"
      },
      "paymentReference": "FT26288QX7Z1",
      "depositTxHash": null,
      "payoutTxHash": null,
      "rejectionReason": null,
      "paymentDeadline": "2026-10-15T11:31:05.120Z",
      "createdAt": "2026-10-15T09:31:05.120Z",
      "updatedAt": "2026-10-15T09:44:20.016Z"
    }
  }
}

Verify every delivery

1. 01Read the raw body before you parse it.
2. 02Compute HMAC-SHA256 of the timestamp, a dot and the raw body with your webhook secret, in hex.
3. 03Compare it with X-2Pay-Signature in constant time, after checking the lengths match (some constant-time functions throw on different lengths).
4. 04Reject timestamps more than 5 minutes from your clock.
5. 05Answer 2xx within 10 seconds, then do the work.

# Check a saved delivery with OpenSSL: body.json holds the raw body exactly as received.
TIMESTAMP=1792056665120  # the X-2Pay-Timestamp header
SIGNATURE=0c5f…          # the X-2Pay-Signature header

expected=$({ printf '%s.' "$TIMESTAMP"; cat body.json; } \
  | openssl dgst -sha256 -hmac "$TWOPAY_WEBHOOK_SECRET" -r | cut -d' ' -f1)
if [ "$expected" = "$(printf '%s' "$SIGNATURE" | tr 'A-F' 'a-f')" ]; then echo valid; else echo invalid; fi

# Ask 2Pay to send a signed "ping" event to your webhook URL now.
twopay POST /v1/webhooks/test

Delivery and retries

• A 2xx answer counts as delivered. Any other status, a timeout (10 seconds) or a connection error is a failure. Redirects are not followed: a 3xx is a failure.
• A failed delivery is retried after the waits below: 10 retries after the first try, about 28 hours in all. After the last one it is marked failed and not sent again; use GET /v1/orders to catch up.
• Each attempt is signed again: X-2Pay-Timestamp and X-2Pay-Signature change, the event id and body do not.
• Events can arrive more than once and out of order. Deduplicate on the id and compare data.order.updatedAt, or read the order with GET /v1/orders/{id}.
• Events are queued only while your account has a webhook URL; changes made while it has none are not sent later.
• While your account is suspended, deliveries pause; they resume when it is active again.
• POST /v1/webhooks/test sends a signed ping right away to check your endpoint.

For a buy order 2Pay checks walletAddress before it creates the order. A failed check returns 422 INVALID_ADDRESS with a message that says what is wrong, and no order is made. An address over 128 characters returns 400 VALIDATION_ERROR.

• Format for the quote's network: TRON base58check, EVM 0x and 40 hex characters, Solana base58 public key, TON user-friendly or raw form.
• Checksum: EIP-55 for mixed-case EVM addresses (all lower or all upper case passes), base58check for TRON, CRC16 for TON. A typo fails here.
• Network: an address of another chain family is refused, e.g. a Solana address on TRC20, a TRON address on SOL, an EVM address on TON or a Bitcoin address anywhere.
• TON testnet and masterchain addresses are refused.
• Token contracts and system addresses are refused, e.g. the USDT contracts themselves, the zero address or the Solana token programs.
• 2Pay's own deposit addresses are refused.
• On the blockchain these are refused: a TRON smart contract; a Solana program, token mint, data account, program-derived address with no account yet or token account (the message names the wallet that owns it); a TON jetton, NFT, SBT or DNS contract and a frozen TON account; an EVM smart-contract wallet that exists on another EVM network but not on this one.
• A wallet address on which Tether has frozen USDT. 2Pay checks it again before it sends; if Tether froze it after the order was placed, 2Pay does not send the USDT: an operator rejects the order with a reason that says so, and 2Pay refunds the AZN by bank transfer, outside the API. Neither happens by itself.

A new address without transactions, a smart-contract wallet and an EVM address active on another network are accepted: they can receive USDT, but make sure they are right. On EVM networks and TON, any smart contract not refused above counts as a smart-contract wallet. When the blockchain cannot be reached, the offline checks decide.

{
  "error": {
    "code": "INVALID_ADDRESS",
    "message": "This is a Solana address, but you chose TRON (TRC20). Choose the matching network or enter your TRON (TRC20) address."
  }
}

Every error is {"error": {"code": "…", "message": "…"}} with the HTTP status below. Retry 429, 500 and 503 with backoff and a new signature; do not retry other 4xx unchanged.

• API keys: the key id (tp_live_…) names the key; the secret (tps_…) signs requests. 2Pay shows the secret once and stores it encrypted (AES-256-GCM). Keep it on your servers, in a secrets manager: never in a browser, a mobile app, logs or source control.
• IP allowlist: a key can be limited to IP addresses or CIDR ranges (IPv4 and IPv6, up to 50 entries). Calls from other addresses get 403 FORBIDDEN. A key without a list accepts any address, so ask 2Pay to set one.
• Rotation: an account can have several active keys. To rotate, ask 2Pay for a new key, switch to it, then ask 2Pay to revoke the old one; a revoked key stops working on the next request. Do this at once if a secret may have leaked.
• Replay protection: signatures are single-use and timestamps must be within 5 minutes.
• Webhook secret: whsec_…, shown once and stored encrypted. 2Pay can replace it on request; the new secret signs the next delivery, so update your endpoint promptly. Verify every webhook and reject unsigned or stale ones.
• Suspension: 2Pay can suspend an account; its calls then get 403 FORBIDDEN and webhooks pause.
• Transport: HTTPS only, for the API and for webhook URLs.

USDT is the only asset, on the networks below. You can buy on the networks in buyNetworks and sell on those in sellNetworks (GET /v1/rates); 2Pay can turn a network off for a while. Network fees differ per network: see networkFees. 2Pay also pauses selling on a network while Tether has frozen its deposit address, or may have while 2Pay confirms it: the network leaves sellNetworks, an open sell order on it gets paymentInstructions.paused: true and a webhook with data.change: "deposit_paused"; do not send USDT to its address.

1. 2026-11-04
   • Buy orders: walletAddress is refused when Tether has frozen USDT on it. If Tether freezes it after the order is placed, 2Pay does not send the USDT: an operator rejects the order with a reason, and 2Pay refunds the AZN by bank transfer, outside the API; neither happens by itself, and no status or webhook follows the refund. Selling on a network is paused while Tether has frozen 2Pay's deposit address there, or may have while 2Pay confirms it (sellNetworks, paymentInstructions.paused, webhook data.change).
2. 2026-11-03
   • Sell orders ask for their own USDT amount: the quote's cut to whole cents, plus 0.01–0.99 USDT (minus, near the top of your limits), so less than 1 USDT from the quote's. The order's send, receive and paymentInstructions.amount show it: send exactly paymentInstructions.amount. POST /v1/orders can answer 409 AMOUNT_BUSY, and for a sell 422 AMOUNT_OUT_OF_RANGE when your limits changed since the quote.
   • An order of 20,000 AZN or more is approved by two different 2Pay staff members, so it may take a little longer. Nothing changes in the API: the order stays payment_submitted until the second approval, its updatedAt does not move in between, and no webhook is sent before it is decided.
3. 2026-10-16
   • GET /v1/rates also returns buyNetworks. 2Pay can turn a network off for buying or selling for a while: quotes and orders on it get UNSUPPORTED_NETWORK, also for a quote made before.
4. 2026-10-15
   • walletAddress is checked more strictly: checksums, the network the address belongs to, TON testnet and masterchain addresses, token contracts, 2Pay's own deposit addresses and an on-chain lookup (INVALID_ADDRESS).
   • GET /v1/account also returns kind, taxId and contactEmail.
5. 2026-10-13
   • v1 launch: rates, quotes, orders, payments, cancellation, account, webhooks.