TDME Pay Integration Guide

Create the payment

Call this from your backend when the customer starts checkout.

curl -X POST "https://crypto-pay-service.cryptosrvc.com/v1/payment" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Invoice",
    "pricing_mode": "LongLivedQuote",
    "merchant_order_currency_id": "USD",
    "amount_required": 100.00,
    "merchant_order_id": "ORDER-12345",
    "merchant_order_description": "Premium Subscription",
    "expiration": "01:00:00",
    "fees_in_price": true
  }'

Parameter	Type	Req.	Description
type	string	yes	Invoice or OpenDeposit.
pricing_mode	string	yes	LongLivedQuote or ConvertOnArrival.
merchant_order_currency_id	string	yes*	Invoice currency, e.g. USD. *Required for Invoice.
amount_required	decimal	yes*	Amount to collect. Must be > 0. *Required for Invoice.
merchant_order_id	string	no	Your order reference (max 36 chars).
merchant_order_description	string	no	Description shown in the widget.
merchant_order_metadata	JSON	no	Custom JSON echoed back in webhooks.
expiration	string	no	Format HH:MM:SS (or d:HH:MM:SS). Minimum 1 hour.
fees_in_price	boolean	no	Include fees in the quoted amount. Default true.
passthrough_fees	boolean	no	Pass network fees on to the customer.

The response returns the payment with status New. The example below reflects the exact PaymentResponse shape returned by the service:

{
  "success": true,
  "message": "",
  "payment": {
    "id": "857e94e4-f7f0-490d-9a53-9c0c99b47978",
    "owner_user_id": "1a1909b9-f0dc-4de1-a2a8-afaa04e6b482",
    "status": "New",
    "kyt_status": null,
    "currency_id": "USD",
    "expiration": 3599,
    "target_currency_amount_required": 100.5,
    "target_currency_amount_paid": 0,
    "merchant_label": "TD Markets Merchant",
    "merchant_order_id": "ORDER-12345",
    "merchant_order_metadata": null,
    "merchant_order_description": "Premium Subscription",
    "own_merchant_fee": 0.25,
    "type": "Invoice",
    "pricing_mode": "Long Lived Quote",
    "fees_in_price": true,
    "passthrough_fees": false,
    "created": "2026-02-08T12:52:47.006606+00:00",
    "updated": "2026-02-08T12:52:46.986953+00:00",
    "expired": "2026-02-08T13:52:47.006606+00:00"
  }
}

Field	Type	Description
success / message	boolean / string	Envelope status and message (empty on success).
id	UUID	Payment identifier. Use it to build the widget URL.
owner_user_id	string	Your merchant user id.
status	string	Payment status; initially New.
kyt_status	string	Know-Your-Transaction screening status: Pending, Approved, Partially KYT Rejected or Rejected. null until screening runs.
currency_id	string	Invoice currency.
expiration	integer	Seconds remaining until expiry.
target_currency_amount_required / _paid	decimal	Amount to collect and amount received so far.
merchant_label	string	Merchant display name.
merchant_order_id / _description / _metadata	string / JSON	Your order reference, description and custom metadata.
own_merchant_fee	decimal	Calculated merchant fee.
type	string	Invoice or Open Deposit.
pricing_mode	string	Long Lived Quote or Convert On Arrival.
fees_in_price / passthrough_fees	boolean	Fee handling flags.
created / updated / expired	datetime	ISO-8601 timestamps with offset.

Redirect the customer to the widget

Build the widget URL from the payment id and redirect the customer (or embed it in an iframe).

const paymentUrl =
  `https://crypto-pay-widget.cryptosrvc.com/?invoice=${payment.id}`;

// redirect
window.location.href = paymentUrl;

// or embed
const iframe = document.createElement("iframe");
iframe.src = paymentUrl;
document.body.appendChild(iframe);

The remaining steps (3 to 5) are performed by the widget against the public /v1/client endpoints. They are documented here so you can build your own checkout UI if you prefer not to use the hosted widget.

Get payment details & create a quote

The widget first loads the payment, then, for LongLivedQuote payments, creates a quote for the currency the customer chose. The quote fixes the exact crypto amount and its expiration.

The response returns the payment (with a simplified, client-facing status), the widget configuration and languages, and any transactions received so far:

{
  "success": true,
  "message": "",
  "payment": {
    "id": "857e94e4-f7f0-490d-9a53-9c0c99b47978",
    "client_status": "Pending",
    "currency_id": "USD",
    "currency_network": "DEFAULT",
    "currency_type": "Fiat",
    "target_currency_amount_required": 100.00,
    "total_fee_amount": 0.50,
    "merchant_fee_amount": 0.25,
    "parent_merchant_fee_amount": 0.25,
    "target_currency_amount_paid": 0,
    "target_currency_amount_left": 100.00,
    "expiration": 3540,
    "created": "2026-02-08T12:52:47.006606+00:00",
    "updated": "2026-02-08T12:52:47.006606+00:00",
    "currency_settings": [
      {
        "enabled": true,
        "currency_id": "BTC",
        "network": "BITCOIN",
        "is_converted": true,
        "required_confirmations": 3,
        "is_preferred": true,
        "type": "Crypto",
        "currency_metadata": null
      },
      {
        "enabled": true,
        "currency_id": "USDT",
        "network": "ETHEREUM",
        "is_converted": true,
        "required_confirmations": 12,
        "is_preferred": false,
        "type": "Crypto",
        "currency_metadata": {
          "contract_address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
          "is_native_token": false,
          "is_erc20": true
        }
      }
    ],
    "type": "Invoice",
    "pricing_mode": "Long Lived Quote",
    "is_fees_in_price_quote": true,
    "merchant_order_description": "Premium Subscription",
    "fees_values": [
      { "currency_id": "BTC", "deposit_fee": 0.25, "deposit_flat_fee": 0.0001 }
    ],
    "passthrough_fees": false
  },
  "widget_setting": "{\"primary_color\":\"#E4C030\"}",
  "widget_languages": [
    { "id": "en", "name": "English" }
  ],
  "transactions": [
    {
      "source_currency_id": "BTC",
      "source_currency_network": "BITCOIN",
      "source_amount_received": 0.0025,
      "estimated_target_amount": 100.00,
      "confirmations": 1,
      "crypto_transaction_id": "8dca4a17...089ffb",
      "sub_merchant_fee_amount": null,
      "is_overpayment": false,
      "status": "Detected"
    }
  ]
}

Top-level fields

Field	Type	Description
success / message	boolean / string	Envelope status and message.
payment	object	The payment details (see below).
widget_setting	string	JSON string of the merchant's widget customization.
widget_languages	array	Available widget languages, each { id, name }.
transactions	array	Transactions received against this payment so far.

payment object

Field	Type	Description
id	UUID	Payment identifier.
client_status	string	Simplified client-facing status: New, Pending, Processing, PartiallyCompleted, Completed, Expired or Rejected.
currency_id / currency_network	string	Invoice currency and its network (DEFAULT for fiat).
currency_type	string	Crypto or Fiat. null for open deposits.
target_currency_amount_required / _paid / _left	decimal	Amount to collect, amount paid, and remaining (invoice only).
total_fee_amount / merchant_fee_amount / parent_merchant_fee_amount	decimal	Fee breakdown. All 0 when passthrough_fees is enabled.
expiration	integer	Seconds remaining until expiry.
created / updated	datetime	Timestamps.
currency_settings	array	Crypto currencies the customer may pay with (see below).
type	string	Invoice or Open Deposit.
pricing_mode	string	Long Lived Quote or Convert On Arrival.
is_fees_in_price_quote	boolean	Whether fees are included in the quoted amount.
merchant_order_description	string	Description to show the customer.
fees_values	array	Per-currency fees: currency_id, deposit_fee (progressive), deposit_flat_fee (flat). Empty when passthrough_fees is enabled.
passthrough_fees	boolean	Whether network fees are passed to the customer.

currency_settings[] and transactions[]

Object	Fields
currency_settings[]	enabled, currency_id, network, is_converted, required_confirmations, is_preferred, type, and currency_metadata (contract_address, is_native_token, is_erc20; null for native coins).
transactions[]	source_currency_id, source_currency_network, source_amount_received, estimated_target_amount, confirmations, crypto_transaction_id, sub_merchant_fee_amount, is_overpayment, and status (Detected, Completed or Rejected).

Once the customer chooses a currency, create a quote:

curl -X POST "https://crypto-pay-service.cryptosrvc.com/v1/client/quote" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "857e94e4-f7f0-490d-9a53-9c0c99b47978",
    "currency_id": "BTC",
    "network": "BITCOIN"
  }'

Field	Type	Req.	Description
payment_id	UUID	yes	The payment to quote.
currency_id	string	yes	Currency the customer will pay in.
network	string	yes	Blockchain network (upper-cased server-side).

Response:

{
  "success": true,
  "quote": {
    "quote_id": "7b0d...c31a",
    "source_currency_id": "BTC",
    "source_currency_amount": 0.0025,
    "price": 40000.00,
    "instrument": "BTC-USD",
    "expiration": 120,
    "fees_in_price": true
  }
}

Generate the payment address

Create the deposit address the customer will send funds to. Pass the quote_id from step 3. For the preferred currency you may omit the quote and an address is generated directly.

curl -X POST "https://crypto-pay-service.cryptosrvc.com/v1/client/address" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "857e94e4-f7f0-490d-9a53-9c0c99b47978",
    "quote_id": "7b0d...c31a",
    "currency": "BTC",
    "currency_network": "BITCOIN"
  }'

Field	Type	Req.	Description
payment_id	UUID	yes	The payment to attach the address to.
quote_id	UUID	cond.	Quote from step 3. Optional when generating a preferred-currency address without a quote.
currency	string	yes	Currency symbol for the address.
currency_network	string	yes	Blockchain network (upper-cased server-side).

Response, the payment now moves to Pending:

{
  "success": true,
  "address_id": "a1b2c3d4-...",
  "address": "bc1qhll33g6azrpfwx7pyl6fannjahcrnutk66hk2p",
  "address_currency_id": "BTC",
  "address_currency_network": "BITCOIN",
  "tag_type": null,
  "tag_value": null
}

Track the transaction & confirmations

After the customer sends funds, poll the payment's addresses to reflect progress in your UI. The payment advances to Processing when a transaction is detected and to a completed status once the required confirmations are received.

Stage	Typical timing
Address generation	< 1 second
Transaction detection	10 to 60 seconds
Blockchain confirmations	Varies by network

Receive the result via webhooks

Register a webhook once, and TDME Pay will push payment and transaction events to your server as they happen. Do not rely on webhooks alone; keep polling as a fallback.

curl -X POST "https://crypto-pay-service.cryptosrvc.com/v1/webhook" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yoursite.com/webhooks/payments",
    "label": "Payment Notifications"
  }'

Manage webhooks with GET /v1/webhook, PUT /v1/webhook/{id} (enable/disable) and DELETE /v1/webhook/{id}. You may have up to 5 enabled at once.

Event payloads

Completed transaction event (a confirmed transaction against a payment):

{
  "payment_id": "550e8400-e29b-41d4-a716-446655440000",
  "payment_status": "Pending",
  "transaction_status": "Completed",
  "crypto_transaction_id": "8dca4a17...089ffb",
  "confirmations": 3,
  "address": "bc1qhll33g6azrpfwx7pyl6fannjahcrnutk66hk2p",
  "currency": "BTC",
  "currency_amount_paid": 0.0025,
  "is_converted": true,
  "preferred_currency_amount_received": 100,
  "preferred_currency_id": "USDT",
  "merchant_order_id": "ORDER-12345",
  "merchant_order_metadata": "{ \"custom-property\": \"value\" }"
}

Payment status event (the payment itself changed state, e.g. Completed or PartiallyCompleted):

{
  "payment_id": "550e8400-e29b-41d4-a716-446655440000",
  "payment_status": "Completed",
  "address": "bc1qhll33g6azrpfwx7pyl6fannjahcrnutk66hk2p",
  "confirmations": 3,
  "currency": "USD",
  "currency_amount_paid": 0.0025,
  "merchant_order_id": "ORDER-12345",
  "merchant_order_metadata": "{ \"custom-property\": \"value\" }"
}

Verifying signatures

Every webhook is signed. The signature is the SHA-256 hash of your webhook id concatenated with the raw JSON body, sent in the x-webhook-signature header.

const crypto = require("crypto");

function verify(payload, signature, webhookId) {
  const stringToSign = webhookId + JSON.stringify(payload);
  const expected = crypto.createHash("sha256")
    .update(stringToSign, "utf8").digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature), Buffer.from(expected));
}

Retry policy

If your endpoint does not return a 2xx status, TDME Pay retries with increasing delays. Always return 200 promptly and process asynchronously; make handling idempotent.

Attempt	Delay
1	Immediate
2	2 seconds
3	3 seconds
4	4 seconds

Create the payout

curl -X POST "https://crypto-pay-service.cryptosrvc.com/v1/payout" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "currency_id": "BTC",
    "network": "BITCOIN",
    "amount": 0.05,
    "destination_address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "note": "Refunding"
  }'

Parameter	Type	Req.	Description
currency_id	string	yes	Currency to withdraw.
network	string	yes	Blockchain network.
amount	decimal	yes	Amount to withdraw. Must be > 0.
destination_address	string	yes	External wallet address.
note	string	no	Informational note (max 256 chars).
destination_address_tag_type	string	no	Tag/memo type (XRP, XLM, ...).
destination_address_tag_value	string	no	Tag/memo value (XRP, XLM, ...).
passthrough_fees	boolean	no	Deduct network fees from the payout amount.

Response, the payout is created with approval_status: Pending and execution_status: New:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "currency": "BTC",
  "network": "BITCOIN",
  "amount": 0.05,
  "fee": 0.0001,
  "own_merchant_fee": 0,
  "parent_merchant_fee": 0,
  "final_amount": 0.0499,
  "destination_address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "tag_type": null,
  "tag_value": null,
  "blockchain_hash": null,
  "note": "Refunding",
  "approval_status": "Pending",
  "execution_status": "New",
  "payout_passthrough_fees": false,
  "is_refund": false,
  "created_at": "2026-02-18T09:49:09Z",
  "updated_at": "2026-02-18T09:49:09Z"
}

Approve the payout (with MFA)

Approving moves the payout to approval_status: Approved and execution_status: Processing. It requires a valid MFA code and the source wallet id.

curl -X PATCH "https://crypto-pay-service.cryptosrvc.com/v1/payout/3fa85f64-.../approve" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mfa_code": "123456",
    "wallet_id": "wallet_abc123"
  }'

Field	Type	Req.	Description
mfa_code	string	yes	6-digit code from your authenticator.
wallet_id	string	yes	Source wallet id to draw funds from.

Reject a payout

Reject a still-pending payout so it never executes. No MFA is required to reject.

curl -X PATCH "https://crypto-pay-service.cryptosrvc.com/v1/payout/3fa85f64-.../reject" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

The payout returns with approval_status: Rejected and execution_status: Rejected.

curl -X GET "https://crypto-pay-service.cryptosrvc.com/v1/payout/list?approvalStatus=Pending&pageSize=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

curl -X GET "https://crypto-pay-service.cryptosrvc.com/v1/payout/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "currency": "BTC",
  "network": "BITCOIN",
  "amount": 0.05,
  "fee": 0.0001,
  "parent_merchant_fee": 0,
  "own_merchant_fee": 0,
  "final_amount": 0.0499,
  "destination_address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "tag_type": null,
  "tag_value": null,
  "exchange_payment_id": "a7f3c1b2-9d84-4e21-8c0a-1f2e3d4c5b6a",
  "blockchain_hash": "a3f19ec1f6bf2fb8b64a9392e32dac433e05bc5b288468f01b4277b1c82e893b",
  "note": "Refunding",
  "approval_status": "Approved",
  "execution_status": "Completed",
  "created_at": "2026-02-18T09:49:09.379Z",
  "updated_at": "2026-02-18T09:51:12.500Z",
  "kyt": null,
  "payout_passthrough_fees": false,
  "is_refund": false,
  "manual_refund": null
}

curl -X GET "https://crypto-pay-service.cryptosrvc.com/v1/payout/fee-estimation/BTC/BITCOIN/0.05" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "fee_estimation": 0.0001,
  "final_amount": 0.0499,
  "fees": {
    "parent_merchant_fee": 0,
    "merchant_fee": 0,
    "exchange_fee": 0.0001
  }
}

curl -X GET "https://crypto-pay-service.cryptosrvc.com/v1/payout/info/BTC" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "account_balance": {
    "free_balance": 1.25,
    "total_balance": 1.30,
    "exposed_balance": 0.05
  },
  "payment_limit": {
    "currency": "BTC",
    "payout_minimal_amount": 0.0005,
    "payout_daily_limit": 5.0,
    "payout_weekly_limit": 20.0,
    "payout_monthly_limit": 50.0
  },
  "pending_payouts_amount": 0.05
}

curl -X GET "https://crypto-pay-service.cryptosrvc.com/v1/payout/addresses-history" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "addresses": [
    {
      "destination_address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
      "network": "BITCOIN",
      "currency": "BTC"
    },
    {
      "destination_address": "rN7n3473SaZBCG4dFL83w7a1RXtXtbk2D9",
      "network": "RIPPLE",
      "currency": "XRP",
      "address_tag_type": "tag",
      "address_tag_value": "324234"
    }
  ]
}

curl -X GET "https://crypto-pay-service.cryptosrvc.com/v1/payout/payment-routes" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "payment_routes": [
    { "currency": "BTC", "crypto_network": "BITCOIN" },
    { "currency": "XRP", "crypto_network": "RIPPLE", "crypto_tag_type": "tag" }
  ]
}