Base URL

https://api.paychainly.com

Overview

Customers

Deposit Addresses

Payment Links

Transactions

Invoices

Withdrawals

Sandbox

Try API Playground

API Reference

REST API for integrating USDT (BEP-20) payments into your platform. Manage customers, generate deposit addresses or payment links, and query transactions — all secured with an API key. Never expose your key in client-side code.

Authentication

Create an API key in API Keys. Pass it in every request as a header — both formats are accepted:

Bearer Token

Authorization: Bearer YOUR_API_KEY

API Key Header

X-Api-Key: YOUR_API_KEY

Integration Patterns

#PatternCustomerAddressPayment LinkUser Pays ViaBest For

1Wallet — address only✓ Required

reusepermanent, never changes

✗ Not needed

Address or QR — user sends anytimeDeposit wallets, open-ended top-ups

2Wallet — with payment link✓ Required

reusesame address every time

✓ createForAddress()

① Redirect to payUrl ② Custom UI ③ QR codeTop-up with a specific fixed amount

3Order Checkout — logged-in user✓ Required

generate_newfresh per order

✓ paymentLinks.create()

① Redirect to payUrl ② Custom UI ③ QR codeE-commerce, invoices, subscriptions

4Guest Checkout✗ Not needed

generate_newfresh per order

✓ paymentLinks.create()

① Redirect to payUrl ② Custom UI ③ QR codeOne-off payments, fully anonymous

For patterns 2, 3, and 4 — all three payment options come from the same single API call. Pick whichever fits your UI:

link.payUrl    → https://paychainly.com/pay/:slug   // ① redirect to hosted page
link.address   → 0xABC...                            // ② show in your own UI
link.address   → 0xABC... (QR-encode it)             // ③ QR code
link.amount    → "49.99"
link.expiresAt → "2026-06-03T10:00:00.000Z"

Customers

POST/api/integration/customers

Create Customer

Creates a new customer record. The identifier is required and must be unique per account — use your internal user ID, order reference, or email. Once created, generate-address will reuse the same wallet for this customer automatically via their identifier.

Headers

Content-Typeapplication/jsonrequired

X-Api-KeyYOUR_API_KEYrequired

Body Parametersapplication/json

ParameterTypeRequiredDescription

identifierstringrequiredUnique key for this customer — e.g. your internal user ID, order ID, or email. Used by generate-address in reuse mode to return the same wallet every time.

namestringoptionalCustomer display name

emailstringoptionalCustomer email address

notestringoptionalInternal note visible only to you

metadataobjectoptionalAny custom JSON payload e.g. { "plan": "pro", "region": "EU" }

Responses

{
  "success": true,
  "data": {
    "id": 7,
    "identifier": "user_12345",
    "name": "John Doe",
    "email": "john@example.com",
    "note": "VIP customer",
    "metadata": { "plan": "pro" },
    "mode": "production",
    "createdAt": "2026-05-24T10:00:00.000Z",
    "updatedAt": "2026-05-24T10:00:00.000Z"
  }
}

curl -X POST https://api.paychainly.com/api/integration/customers \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "identifier": "user_12345",
    "name": "John Doe",
    "email": "john@example.com",
    "note": "VIP customer",
    "metadata": { "plan": "pro" }
  }'

GET/api/integration/customers

List Customers

Returns a paginated list of all your customers. Search by name, email, or identifier. Useful for looking up a customer before generating a deposit address or checking payment history.

Headers

X-Api-KeyYOUR_API_KEYrequired

Query Parameters

ParameterTypeRequiredDescription

limitnumberoptionalMax results per page (max 100). Default: 20

offsetnumberoptionalNumber of results to skip. Default: 0

searchstringoptionalFull-text search across name, email, and identifier fields.

modestringoptionalproduction or sandbox

Responses

{
  "success": true,
  "data": [
    {
      "id": 7,
      "identifier": "user_12345",
      "name": "John Doe",
      "email": "john@example.com",
      "note": "VIP customer",
      "metadata": { "plan": "pro" },
      "mode": "production",
      "createdAt": "2026-05-24T10:00:00.000Z",
      "updatedAt": "2026-05-24T10:00:00.000Z"
    }
  ],
  "meta": { "total": 1, "limit": 20, "offset": 0 }
}

# List all customers
curl "https://api.paychainly.com/api/integration/customers?limit=20&offset=0" \
  -H "X-Api-Key: YOUR_API_KEY"

# Search by email
curl "https://api.paychainly.com/api/integration/customers?search=john@example.com" \
  -H "X-Api-Key: YOUR_API_KEY"

GET/api/integration/customers/:customerUid

Get Customer

Get a customer by their customerUid (the UUID assigned at creation). Use get_customer_by_identifier for lookup by your own reference.

Headers

X-Api-KeyYOUR_API_KEYrequired

Path Parameters

ParameterTypeRequiredDescription

customerUidstring (UUID)requiredCustomer UUID assigned at creation (the customerUid field in the response, e.g. "dd8693ec-8b5f-43ef-b4e5-1d0a088df1a3")

Responses

{
  "success": true,
  "data": {
    "id": 7,
    "identifier": "user_12345",
    "name": "John Doe",
    "email": "john@example.com",
    "note": "VIP customer",
    "metadata": { "plan": "pro" },
    "mode": "production",
    "createdAt": "2026-05-24T10:00:00.000Z",
    "updatedAt": "2026-05-24T10:00:00.000Z"
  }
}

# By numeric ID
curl "https://api.paychainly.com/api/integration/customers/7" \
  -H "X-Api-Key: YOUR_API_KEY"

# By email
curl "https://api.paychainly.com/api/integration/customers/john@example.com" \
  -H "X-Api-Key: YOUR_API_KEY"

# By custom identifier
curl "https://api.paychainly.com/api/integration/customers/user_12345" \
  -H "X-Api-Key: YOUR_API_KEY"

GET/api/integration/customers/by-email/:email

Get Customer by Email

Looks up a customer by their exact email address. Returns 404 if no customer with that email exists. URL-encode the email before embedding it in the path (e.g. john%40example.com).

Headers

X-Api-KeyYOUR_API_KEYrequired

Path Parameters

ParameterTypeRequiredDescription

emailstringrequiredCustomer email address. URL-encode the @ symbol as %40 (e.g. john%40example.com).

Responses

{
  "success": true,
  "data": {
    "id": 7,
    "identifier": "user_12345",
    "name": "John Doe",
    "email": "john@example.com",
    "note": "VIP customer",
    "metadata": { "plan": "pro" },
    "mode": "production",
    "createdAt": "2026-05-24T10:00:00.000Z",
    "updatedAt": "2026-05-24T10:00:00.000Z"
  }
}

# URL-encode the @ as %40
curl "https://api.paychainly.com/api/integration/customers/by-email/john%40example.com" \
  -H "X-Api-Key: YOUR_API_KEY"

GET/api/integration/customers/by-identifier/:identifier

Get Customer by Identifier

Looks up a customer by their exact identifier — the unique key you set when creating the customer (e.g. your internal user ID, order reference, or any string). Returns 404 if not found.

Headers

X-Api-KeyYOUR_API_KEYrequired

Path Parameters

ParameterTypeRequiredDescription

identifierstringrequiredThe exact identifier value used when creating the customer (e.g. user_12345, ORD-999). URL-encode special characters if needed.

Responses

{
  "success": true,
  "data": {
    "id": 7,
    "identifier": "user_12345",
    "name": "John Doe",
    "email": "john@example.com",
    "note": "VIP customer",
    "metadata": { "plan": "pro" },
    "mode": "production",
    "createdAt": "2026-05-24T10:00:00.000Z",
    "updatedAt": "2026-05-24T10:00:00.000Z"
  }
}

curl "https://api.paychainly.com/api/integration/customers/by-identifier/user_12345" \
  -H "X-Api-Key: YOUR_API_KEY"

GET/api/integration/customers/by-deposit-address/:address

Get Customer by Deposit Address

Resolves the customer who owns a given deposit wallet address. Useful when a webhook delivers a wallet address and you need to know which of your customers it belongs to. Returns the customer record alongside the matched deposit address details.

Headers

X-Api-KeyYOUR_API_KEYrequired

Path Parameters

ParameterTypeRequiredDescription

addressstringrequiredFull 0x-prefixed BEP-20 wallet address (e.g. 0x1234567890abcdef...)

Responses

{
  "success": true,
  "data": {
    "customer": {
      "id": 7,
      "identifier": "user_12345",
      "name": "John Doe",
      "email": "john@example.com",
      "note": "VIP customer",
      "metadata": { "plan": "pro" },
      "mode": "production",
      "createdAt": "2026-05-24T10:00:00.000Z",
      "updatedAt": "2026-05-24T10:00:00.000Z"
    },
    "depositAddress": {
      "id": 42,
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "network": "BNB",
      "status": "active"
    }
  }
}

# From a webhook payload — find which customer owns this address
ADDR="0x1234567890abcdef1234567890abcdef12345678"

curl "https://api.paychainly.com/api/integration/customers/by-deposit-address/${ADDR}" \
  -H "X-Api-Key: YOUR_API_KEY"

PUT/api/integration/customers/by-identifier/:identifier

Update Customer by Identifier

Update a customer by their identifier. Pass the identifier in the path and only the fields to change in the body — omitted fields are left untouched.

Headers

Content-Typeapplication/jsonrequired

X-Api-KeyYOUR_API_KEYrequired

Path Parameters

ParameterTypeRequiredDescription

identifierstringrequiredThe exact identifier of the customer to update (e.g. user_12345).

Body Parametersapplication/json

ParameterTypeRequiredDescription

namestringoptionalUpdated display name.

emailstringoptionalUpdated email address.

identifierstringoptionalUpdated identifier value.

notestringoptionalUpdated note.

metadataobjectoptionalUpdated metadata (replaces existing).

Responses

{
  "success": true,
  "data": {
    "id": 7,
    "identifier": "user_12345",
    "name": "John Doe",
    "email": "john@example.com",
    "note": "VIP customer",
    "metadata": { "plan": "pro" },
    "mode": "production",
    "createdAt": "2026-05-24T10:00:00.000Z",
    "updatedAt": "2026-05-24T10:00:00.000Z"
  }
}

curl -X PUT "https://api.paychainly.com/api/integration/customers/by-identifier/user_12345" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{ "name": "John Doe Jr.", "note": "Upgraded to enterprise", "metadata": { "plan": "enterprise" } }'

PUT/api/integration/customers/by-email/:email

Update Customer by Email

Update a customer by their email address. URL-encode @ as %40 in the path. Only the fields included in the body are updated.

Headers

Content-Typeapplication/jsonrequired

X-Api-KeyYOUR_API_KEYrequired

Path Parameters

ParameterTypeRequiredDescription

emailstringrequiredCustomer email — URL-encode @ as %40 (e.g. john%40example.com).

Body Parametersapplication/json

ParameterTypeRequiredDescription

namestringoptionalUpdated display name.

emailstringoptionalUpdated email address.

identifierstringoptionalUpdated identifier value.

notestringoptionalUpdated note.

metadataobjectoptionalUpdated metadata (replaces existing).

Responses

{
  "success": true,
  "data": {
    "id": 7,
    "identifier": "user_12345",
    "name": "John Doe",
    "email": "john@example.com",
    "note": "VIP customer",
    "metadata": { "plan": "pro" },
    "mode": "production",
    "createdAt": "2026-05-24T10:00:00.000Z",
    "updatedAt": "2026-05-24T10:00:00.000Z"
  }
}

curl -X PUT "https://api.paychainly.com/api/integration/customers/by-email/john%40example.com" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{ "name": "John Doe Jr.", "metadata": { "plan": "enterprise" } }'

Deposit Addresses

POST/api/integration/addresses/generate

Generate Wallet

Generate a fresh deposit address without linking a customer. A new address is always created. Monitoring starts immediately — the address listens for incoming transfers the moment it is returned.

Headers

Content-Typeapplication/jsonrequired

X-Api-KeyYOUR_API_KEYrequired

Body Parametersapplication/json

ParameterTypeRequiredDescription

networkstringrequiredBlockchain network. Currently only "BNB" is supported.

tokenSymbolstringrequiredToken symbol to accept (e.g. "USDT"). Case-insensitive — stored uppercase.

notestringoptionalFree-form note attached to the deposit address.

metadataobjectoptionalArbitrary JSON metadata stored alongside the deposit address.

Responses

{
  "success": true,
  "data": {
    "id": 42,
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "status": "active",
    "mode": "production",
    "type": "wallet",
    "network": { "id": 1, "name": "BNB Smart Chain", "slug": "bnb", "chainId": 56, "nativeSymbol": "BNB" },
    "token": { "id": 2, "symbol": "USDT", "decimals": 18 },
    "customer": null,
    "note": "Payment for order #1234",
    "metadata": { "orderId": "1234" },
    "createdAt": "2026-05-24T10:00:00.000Z"
  }
}

curl -X POST "https://api.paychainly.com/api/integration/addresses/generate" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "network": "BNB",
    "tokenSymbol": "USDT",
    "note": "Payment for order #1234",
    "metadata": { "orderId": "1234" }
  }'

POST/api/integration/addresses/generate

Generate Wallet with Customer

Generate (or reuse) a deposit address and link it to a customer. Pass a customer object with customerUid (lookup only), identifier, or email — if the customer does not exist it is created automatically. The response includes the full customer object.

Headers

Content-Typeapplication/jsonrequired

X-Api-KeyYOUR_API_KEYrequired

Body Parametersapplication/json

ParameterTypeRequiredDescription

networkstringrequiredBlockchain network. Currently only "BNB" is supported.

tokenSymbolstringrequiredToken symbol to accept (e.g. "USDT"). Case-insensitive.

mode"reuse"|"generate_new"optional"reuse" returns the existing active address for this customer; "generate_new" always creates a fresh one. Default: reuse

customerobjectoptionalCustomer to link. Pass one of the sub-fields below.

customer.customerUidstring (UUID)optionalLook up an existing customer by their customerUid. Returns 404 if not found.

customer.identifierstringoptionalLook up or create a customer by identifier (e.g. user_12345).

customer.emailstringoptionalLook up or create a customer by email address.

notestringoptionalFree-form note attached to the deposit address.

metadataobjectoptionalArbitrary JSON metadata stored alongside the deposit address.

Responses

{
  "success": true,
  "data": {
    "id": 42,
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "status": "active",
    "mode": "production",
    "type": "wallet",
    "network": { "id": 1, "name": "BNB Smart Chain", "slug": "bnb", "chainId": 56, "nativeSymbol": "BNB" },
    "token": { "id": 2, "symbol": "USDT", "decimals": 18 },
    "customer": {
      "id": 52,
      "customerUid": "93c7e7b7-f6e3-4708-8881-a4e0de50ab6b",
      "identifier": "user_12345",
      "name": "John Doe",
      "email": "john@example.com"
    },
    "note": "Payment for order #1234",
    "metadata": { "orderId": "1234" },
    "createdAt": "2026-05-24T10:00:00.000Z"
  }
}

curl -X POST "https://api.paychainly.com/api/integration/addresses/generate" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "network": "BNB",
    "tokenSymbol": "USDT",
    "mode": "reuse",
    "customer": { "identifier": "user_12345" }
  }'

GET/api/integration/addresses

List Deposit Addresses

Returns a paginated list of all deposit addresses for your account. Filter by network, mode, or customer ID. Search matches wallet address, note, and metadata values.

Headers

X-Api-KeyYOUR_API_KEYrequired

Query Parameters

ParameterTypeRequiredDescription

limitnumberoptionalMax results per page (max 100). Default: 20

offsetnumberoptionalResults to skip. Default: 0

networkstringoptionalFilter by network e.g. BNB.

mode"production"|"sandbox"optionalFilter by deposit mode.

customerIdnumberoptionalFilter addresses linked to a specific customer ID.

searchstringoptionalSearch by wallet address, note, or metadata (JSON text match). Ignored when customerId is set.

sort"ASC"|"DESC"optionalSort by creation date. Default: DESC

Responses

{
  "success": true,
  "data": [
    {
      "id": 42,
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "status": "active",
      "mode": "production",
      "type": "wallet",
      "isDefault": false,
      "note": "Pro plan upgrade",
      "metadata": { "orderId": "1234", "plan": "pro" },
      "createdAt": "2026-05-24T10:00:00.000Z",
      "updatedAt": "2026-05-24T10:00:00.000Z",
      "network": {
        "id": 1,
        "name": "BNB Smart Chain",
        "slug": "bnb",
        "chainId": 56,
        "nativeSymbol": "BNB",
        "explorerUrl": "https://bscscan.com"
      },
      "token": {
        "id": 2,
        "symbol": "USDT",
        "displayName": "Tether USD",
        "contractAddress": "0x55d398326f99059ff775485246999027b3197955",
        "decimals": 18
      },
      "customer": {
        "id": 52,
        "customerUid": "93c7e7b7-f6e3-4708-8881-a4e0de50ab6b",
        "identifier": "user_12345",
        "name": "John Doe",
        "email": "john@example.com"
      }
    }
  ],
  "meta": { "total": 1, "limit": 20, "offset": 0, "sort": "DESC" }
}

# All addresses
curl "https://api.paychainly.com/api/integration/addresses?limit=20&offset=0" \
  -H "X-Api-Key: YOUR_API_KEY"

# Filter by customer
curl "https://api.paychainly.com/api/integration/addresses?customerId=52" \
  -H "X-Api-Key: YOUR_API_KEY"

# Search by note or metadata
curl "https://api.paychainly.com/api/integration/addresses?search=pro+plan" \
  -H "X-Api-Key: YOUR_API_KEY"

GET/api/integration/addresses/:id

Get Deposit Address

Retrieves a single deposit address. The :id segment accepts either a numeric ID or a full 0x-prefixed wallet address string — useful when you have the address from a webhook and need to fetch its full record.

Headers

X-Api-KeyYOUR_API_KEYrequired

Path Parameters

ParameterTypeRequiredDescription

idinteger | stringrequiredNumeric ID (e.g. 42) or full wallet address (0x1234...)

Responses

{
  "success": true,
  "data": {
    "id": 42,
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "status": "active",
    "mode": "production",
    "type": "wallet",
    "isDefault": false,
    "note": "Pro plan upgrade",
    "metadata": { "orderId": "1234", "plan": "pro" },
    "createdAt": "2026-05-24T10:00:00.000Z",
    "updatedAt": "2026-05-24T10:00:00.000Z",
    "network": {
      "id": 1,
      "name": "BNB Smart Chain",
      "slug": "bnb",
      "chainId": 56,
      "nativeSymbol": "BNB",
      "explorerUrl": "https://bscscan.com"
    },
    "token": {
      "id": 2,
      "symbol": "USDT",
      "displayName": "Tether USD",
      "contractAddress": "0x55d398326f99059ff775485246999027b3197955",
      "decimals": 18
    },
    "customer": {
      "id": 52,
      "customerUid": "93c7e7b7-f6e3-4708-8881-a4e0de50ab6b",
      "identifier": "user_12345",
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}

curl "https://api.paychainly.com/api/integration/addresses/42" \
  -H "X-Api-Key: YOUR_API_KEY"

GET/api/integration/addresses/by-address/:address

Get Wallet by Address

Retrieve full details of a wallet by its 0x wallet address string, including network, token and customer information.

Headers

X-Api-KeyYOUR_API_KEYrequired

Path Parameters

ParameterTypeRequiredDescription

addressstringrequiredThe 0x-prefixed wallet address (e.g. 0xabc…). URL-encode if needed.

Responses

{
  "success": true,
  "data": {
    "id": 42,
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "status": "active",
    "mode": "production",
    "type": "wallet",
    "network": { "id": 1, "name": "BNB Smart Chain", "slug": "bnb", "chainId": 56, "nativeSymbol": "BNB" },
    "token": { "id": 2, "symbol": "USDT", "decimals": 18 },
    "customer": { "id": 52, "customerUid": "93c7e7b7-…", "identifier": "user_12345", "name": "John Doe", "email": "john@example.com" },
    "createdAt": "2026-05-24T10:00:00.000Z"
  }
}

ADDR="0x1234567890abcdef1234567890abcdef12345678"
curl "https://api.paychainly.com/api/integration/addresses/by-address/${ADDR}" \
  -H "X-Api-Key: YOUR_API_KEY"

Payment Links

POST/api/integration/payment-links/generate

Create Payment Link

Generates a hosted payment page with a unique deposit address and optional fixed amount. Share the returned payUrl with your customer — they open it to see a QR code, wallet address, and real-time confirmation status.

Headers

Content-Typeapplication/jsonrequired

X-Api-KeyYOUR_API_KEYrequired

Body Parametersapplication/json

ParameterTypeRequiredDescription

networkstringoptionalBlockchain network. Default: BNB

amountstringoptionalFixed USDT amount to collect. Omit to accept any amount.

memostringoptionalMessage shown to the customer on the payment page.

expiresAtstring (ISO 8601)conditionalExact expiry timestamp. Use either expiresAt or expiryHours — not both.

expiryHoursnumberconditionalHours until the link expires. Common: 1, 24, 168 (7d), 720 (30d).

Responses

{
  "success": true,
  "data": {
    "id": 1,
    "slug": "pl_abc123xyz",
    "payUrl": "https://paychainly.com/pay/pl_abc123xyz",
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "network": "BNB",
    "amount": "100.50",
    "memo": "Order #ORD-999",
    "status": "active",
    "expiresAt": "2026-05-25T10:00:00.000Z",
    "createdAt": "2026-05-24T10:00:00.000Z"
  }
}

curl -X POST https://api.paychainly.com/api/integration/payment-links/generate \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "network": "BNB",
    "amount": "100.50",
    "memo": "Order #ORD-999",
    "expiryHours": 24
  }'

GET/api/integration/payment-links

List Payment Links

Returns a paginated list of all payment links for your account, ordered by creation date descending.

Headers

X-Api-KeyYOUR_API_KEYrequired

Query Parameters

ParameterTypeRequiredDescription

limitnumberoptionalMax results per page. Default: 20

offsetnumberoptionalResults to skip. Default: 0

modestringoptionalproduction or sandbox

Responses

{
  "success": true,
  "data": [
    {
      "id": 1,
      "slug": "pl_abc123xyz",
      "payUrl": "https://paychainly.com/pay/pl_abc123xyz",
      "amount": "100.50",
      "memo": "Order #ORD-999",
      "status": "active",
      "expiresAt": "2026-05-25T10:00:00.000Z",
      "createdAt": "2026-05-24T10:00:00.000Z"
    }
  ],
  "meta": { "total": 1, "limit": 20, "offset": 0 }
}

curl "https://api.paychainly.com/api/integration/payment-links?limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

GET/api/integration/payment-links/:id

Get Payment Link

Retrieves a single payment link by numeric ID. Use this to check the current status (active / expired / paid) of a link after creation.

Headers

X-Api-KeyYOUR_API_KEYrequired

Path Parameters

ParameterTypeRequiredDescription

idintegerrequiredNumeric ID of the payment link

Responses

{
  "success": true,
  "data": {
    "id": 1,
    "slug": "pl_abc123xyz",
    "payUrl": "https://paychainly.com/pay/pl_abc123xyz",
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "network": "BNB",
    "amount": "100.50",
    "memo": "Order #ORD-999",
    "status": "active",
    "expiresAt": "2026-05-25T10:00:00.000Z",
    "createdAt": "2026-05-24T10:00:00.000Z"
  }
}

curl "https://api.paychainly.com/api/integration/payment-links/1" \
  -H "X-Api-Key: YOUR_API_KEY"

GET/api/integration/payment-links/by-slug/:slug

Get Payment Link by Slug

Retrieve full details of a payment link by its slug — the identifier used in the payUrl. Returns the same structure as Get Payment Link.

Headers

X-Api-KeyYOUR_API_KEYrequired

Path Parameters

ParameterTypeRequiredDescription

slugstringrequiredThe payment link slug (e.g. "pl_d139f11rs1d4") — found in the payUrl or generate response.

Responses

{
  "success": true,
  "data": {
    "id": 1,
    "slug": "pl_abc123xyz",
    "payUrl": "https://paychainly.com/pay/pl_abc123xyz",
    "status": "active",
    "amount": "100.50",
    "memo": "Order #ORD-999",
    "expiresAt": "2026-05-25T10:00:00.000Z",
    "createdAt": "2026-05-24T10:00:00.000Z"
  }
}

curl "https://api.paychainly.com/api/integration/payment-links/by-slug/pl_abc123xyz" \
  -H "X-Api-Key: YOUR_API_KEY"

GET/api/integration/payment-links/by-address/:address

Get Payment Links by Address

Returns all payment links that are bound to a specific deposit wallet address. A single address can have multiple payment links created over time — this endpoint returns all of them ordered by creation date descending.

Headers

X-Api-KeyYOUR_API_KEYrequired

Path Parameters

ParameterTypeRequiredDescription

addressstringrequiredFull 0x-prefixed deposit wallet address

Responses

{
  "success": true,
  "data": [
    {
      "id": 1,
      "slug": "pl_abc123xyz",
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "network": "BNB",
      "amount": "100.50",
      "memo": "Order #ORD-999",
      "status": "active",
      "expiresAt": "2026-05-25T10:00:00.000Z",
      "createdAt": "2026-05-24T10:00:00.000Z"
    }
  ],
  "meta": { "total": 1 }
}

ADDR="0x1234567890abcdef1234567890abcdef12345678"

curl "https://api.paychainly.com/api/integration/payment-links/by-address/${ADDR}" \
  -H "X-Api-Key: YOUR_API_KEY"

POST/api/integration/payment-links/for-address/:address

Create Payment Link for Address

Create a shareable payment link tied to an existing deposit address. The address already has token and network set — just provide optional amount and memo.

Headers

Content-Typeapplication/jsonrequired

X-Api-KeyYOUR_API_KEYrequired

Path Parameters

ParameterTypeRequiredDescription

addressstringrequiredExisting deposit wallet address (0x...)

Body Parametersapplication/json

ParameterTypeRequiredDescription

amountstringoptionalFixed payment amount e.g. "50.00". Leave empty for open-amount links.

memostringoptionalMemo shown on the payment page

notestringoptionalInternal note (not shown to payer)

expiresAtstringoptionalISO 8601 expiry datetime e.g. "2026-12-31T23:59:59Z"

expiryHoursnumberoptionalExpiry in hours from now (alternative to expiresAt)

Responses

{
  "success": true,
  "data": {
    "id": 5,
    "slug": "pl_abc123",
    "payUrl": "https://paychainly.com/pay/pl_abc123",
    "status": "active",
    "amount": "50.000000000000000000",
    "memo": "Payment for order #123",
    "uniqueId": "order-123",
    "address": {
      "id": 6,
      "address": "0x6d46407fe46eb8067971feddf52e6b4288b7e075",
      "network": "BNB",
      "status": "active"
    },
    "createdAt": "2026-06-01T10:00:00.000Z"
  }
}

curl -X POST https://api.paychainly.com/api/integration/payment-links/for-address/0x6d46407fe46eb8067971feddf52e6b4288b7e075 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "amount": "50.00",
    "memo": "Payment for order #123"
  }'

Transactions

GET/api/integration/transactions

List Transactions

Returns a paginated list of all USDT transfers detected for your deposit addresses. Filter by status, date range, or a specific address. Use this to reconcile payments on your side.

Headers

X-Api-KeyYOUR_API_KEYrequired

Query Parameters

ParameterTypeRequiredDescription

limitnumberoptionalMax results per page. Default: 20

offsetnumberoptionalResults to skip. Default: 0

statusstringoptionalFilter by status: pending, confirmed, swept

modestringoptionalproduction or sandbox

addressstringoptionalFilter by a specific deposit wallet address

dateFromstring (ISO 8601)optionalStart of date range (createdAt ≥ dateFrom)

dateTostring (ISO 8601)optionalEnd of date range (createdAt ≤ dateTo)

Responses

{
  "success": true,
  "data": [
    {
      "id": 101,
      "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "amount": "100.500000",
      "status": "confirmed",
      "mode": "production",
      "blockNumber": 38000000,
      "webhookSent": true,
      "createdAt": "2026-05-24T10:05:00.000Z"
    }
  ],
  "meta": { "total": 1, "limit": 20, "offset": 0 }
}

# All transactions
curl "https://api.paychainly.com/api/integration/transactions?limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

# Filter confirmed payments in May 2026
curl "https://api.paychainly.com/api/integration/transactions?status=confirmed&dateFrom=2026-05-01&dateTo=2026-05-31" \
  -H "X-Api-Key: YOUR_API_KEY"

GET/api/integration/transactions/by-address/:address

List Transactions by Address

Returns all USDT transactions received by a specific deposit wallet address, paginated and ordered by block number descending. Supports optional status and date-range filters. Useful for showing payment history for a single customer wallet.

Headers

X-Api-KeyYOUR_API_KEYrequired

Path Parameters

ParameterTypeRequiredDescription

addressstringrequiredFull 0x-prefixed deposit wallet address

Query Parameters

ParameterTypeRequiredDescription

limitnumberoptionalMax results per page. Default: 20

offsetnumberoptionalResults to skip. Default: 0

statusstringoptionalFilter by status: pending, confirmed, swept

dateFromstring (ISO 8601)optionalStart of date range (createdAt ≥ dateFrom)

dateTostring (ISO 8601)optionalEnd of date range (createdAt ≤ dateTo)

Responses

{
  "success": true,
  "data": [
    {
      "id": 101,
      "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "amount": "100.500000",
      "status": "confirmed",
      "mode": "production",
      "blockNumber": 38000000,
      "webhookSent": true,
      "createdAt": "2026-05-24T10:05:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "address": "0x1234567890abcdef1234567890abcdef12345678"
  }
}

ADDR="0x1234567890abcdef1234567890abcdef12345678"

# All transactions for this address
curl "https://api.paychainly.com/api/integration/transactions/by-address/${ADDR}?limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

# Only confirmed, filtered by date
curl "https://api.paychainly.com/api/integration/transactions/by-address/${ADDR}?status=confirmed&dateFrom=2026-05-01" \
  -H "X-Api-Key: YOUR_API_KEY"

GET/api/integration/transactions/:id

Get Transaction

Retrieves a single transaction by numeric ID or full txHash. Useful when your webhook receives a txHash and you want to fetch the full record. Both formats are accepted.

Headers

X-Api-KeyYOUR_API_KEYrequired

Path Parameters

ParameterTypeRequiredDescription

idinteger | stringrequiredNumeric transaction ID (e.g. 101) or full txHash (0x...)

Responses

{
  "success": true,
  "data": {
    "id": 101,
    "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "amount": "100.500000",
    "status": "confirmed",
    "mode": "production",
    "blockNumber": 38000000,
    "webhookSent": true,
    "createdAt": "2026-05-24T10:05:00.000Z"
  }
}

# By numeric ID
curl "https://api.paychainly.com/api/integration/transactions/101" \
  -H "X-Api-Key: YOUR_API_KEY"

# By txHash (from webhook payload)
curl "https://api.paychainly.com/api/integration/transactions/0xabcdef..." \
  -H "X-Api-Key: YOUR_API_KEY"

Invoices

GET/api/integration/invoice/:txId

Download Invoice PDF (Universal)

Download the PDF invoice for a transaction. Accepts either a numeric transaction ID or an on-chain transaction hash — the server detects which format was passed automatically. This is the recommended endpoint.

Headers

X-Api-KeyYOUR_API_KEYrequired

Path Parameters

ParameterTypeRequiredDescription

txIdstring | numberrequiredEither the numeric transaction ID (e.g. "42") or the on-chain tx hash (e.g. "0xabc123...")

Responses

// Returns a PDF binary stream
// Content-Type: application/pdf
// Content-Disposition: attachment; filename="INV-42.pdf"

# By numeric ID:
curl https://api.paychainly.com/api/integration/invoice/42 \
  -H "X-Api-Key: YOUR_API_KEY" \
  --output invoice-42.pdf

# By on-chain hash:
curl https://api.paychainly.com/api/integration/invoice/0xabc123... \
  -H "X-Api-Key: YOUR_API_KEY" \
  --output invoice.pdf

GET/api/integration/invoice/by-id/:id

Download Invoice PDF by ID

Generate and download a PDF invoice for a completed transaction using its numeric ID. Returns a binary PDF stream using your Invoice Settings.

Headers

X-Api-KeyYOUR_API_KEYrequired

Path Parameters

ParameterTypeRequiredDescription

idintegerrequiredNumeric transaction ID (e.g. 8).

Responses

Content-Type: application/pdf
Content-Disposition: attachment; filename="invoice-8.pdf"

<binary PDF data>

curl "https://api.paychainly.com/api/integration/invoice/by-id/8" \
  -H "X-Api-Key: YOUR_API_KEY" \
  --output invoice-8.pdf

GET/api/integration/invoice/by-hash/:txHash

Download Invoice PDF by Tx Hash

Generate and download a PDF invoice for a completed transaction using the on-chain transaction hash. Returns a binary PDF stream using your Invoice Settings.

Headers

X-Api-KeyYOUR_API_KEYrequired

Path Parameters

ParameterTypeRequiredDescription

txHashstringrequiredOn-chain transaction hash (e.g. "0xabc123…").

Responses

Content-Type: application/pdf
Content-Disposition: attachment; filename="invoice.pdf"

<binary PDF data>

HASH="0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab"
curl "https://api.paychainly.com/api/integration/invoice/by-hash/${HASH}" \
  -H "X-Api-Key: YOUR_API_KEY" \
  --output invoice.pdf

Withdrawals

POST/api/integration/withdrawals

Create Withdrawal

Initiate a USDT withdrawal from your Paychainly balance to an external wallet. Always generate a unique UUID for idempotencyKey and store it before calling — submit the same key on retry to prevent duplicate withdrawals.

Headers

Content-Typeapplication/jsonrequired

X-Api-KeyYOUR_API_KEYrequired

Body Parametersapplication/json

ParameterTypeRequiredDescription

idempotencyKeystring (UUID)requiredUnique UUID per withdrawal request. Re-submit the same key on retry — returns original result, never a duplicate.

networkstringrequiredNetwork slug e.g. "BNB" for BSC

toAddressstringrequiredDestination EVM wallet address (0x...)

amountstringrequiredAmount to withdraw as decimal string e.g. "100.00"

feeMode"deduct" | "add"required"deduct" — fee taken from withdrawal amount. "add" — fee charged on top of withdrawal.

notestringoptionalInternal note for this withdrawal — visible only to you, not shown to recipient

metadataobjectoptionalCustom JSON payload e.g. { "orderId": "123", "userId": "456" }

Responses

{
  "success": true,
  "data": {
    "id": 1,
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
    "network": "BNB",
    "toAddress": "0xRecipientAddress",
    "amount": "100.00",
    "feeMode": "deduct",
    "status": "pending",
    "txHash": null,
    "createdAt": "2026-06-01T10:00:00.000Z"
  }
}

curl -X POST https://api.paychainly.com/api/integration/withdrawals \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
    "network": "BNB",
    "toAddress": "0xRecipientWalletAddress",
    "amount": "100.00",
    "feeMode": "deduct",
    "note": "Monthly payout",
    "metadata": { "orderId": "order-456" }
  }'

GET/api/integration/withdrawals

List Withdrawals

List all withdrawal requests for your account with pagination.

Headers

X-Api-KeyYOUR_API_KEYrequired

Query Parameters

ParameterTypeRequiredDescription

limitnumberoptionalMax records to return (default 20, max 100) Default: 20

offsetnumberoptionalRecords to skip for pagination Default: 0

Responses

{
  "success": true,
  "data": [
    {
      "id": 1,
      "network": "BNB",
      "toAddress": "0xRecipientAddress",
      "amount": "100.00",
      "feeMode": "deduct",
      "status": "completed",
      "txHash": "0xabc123...",
      "createdAt": "2026-06-01T10:00:00.000Z"
    }
  ],
  "total": 1
}

curl https://api.paychainly.com/api/integration/withdrawals?limit=20 \
  -H "X-Api-Key: YOUR_API_KEY"

GET/api/integration/withdrawals/:id

Get Withdrawal

Get a withdrawal request by its numeric ID.

Headers

X-Api-KeyYOUR_API_KEYrequired

Path Parameters

ParameterTypeRequiredDescription

idnumberrequiredWithdrawal numeric ID

Responses

{
  "success": true,
  "data": {
    "id": 1,
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
    "network": "BNB",
    "toAddress": "0xRecipientAddress",
    "amount": "100.00",
    "feeMode": "deduct",
    "status": "completed",
    "txHash": "0xabc123...",
    "createdAt": "2026-06-01T10:00:00.000Z",
    "updatedAt": "2026-06-01T10:01:00.000Z"
  }
}

curl https://api.paychainly.com/api/integration/withdrawals/1 \
  -H "X-Api-Key: YOUR_API_KEY"

POST/api/integration/withdrawals/:id/cancel

Cancel Withdrawal

Cancel a pending withdrawal before it is processed. Only withdrawals with status "pending" can be cancelled.

Headers

X-Api-KeyYOUR_API_KEYrequired

Path Parameters

ParameterTypeRequiredDescription

idnumberrequiredWithdrawal numeric ID to cancel

Responses

{
  "success": true,
  "data": {
    "id": 1,
    "status": "cancelled",
    "updatedAt": "2026-06-01T10:02:00.000Z"
  }
}

curl -X POST https://api.paychainly.com/api/integration/withdrawals/1/cancel \
  -H "X-Api-Key: YOUR_API_KEY"

GET/api/integration/withdrawals/by-address/:address

Get Withdrawals by Address

Get all withdrawal requests that were sent to a specific destination wallet address.

Headers

X-Api-KeyYOUR_API_KEYrequired

Path Parameters

ParameterTypeRequiredDescription

addressstringrequiredDestination wallet address to filter by (0x...)

Query Parameters

ParameterTypeRequiredDescription

pagenumberoptionalPage number (default 1) Default: 1

limitnumberoptionalRecords per page (default 20) Default: 20

statusstringoptionalFilter by status: "pending", "processing", "completed", "failed", "cancelled"

Responses

{
  "success": true,
  "data": [
    {
      "id": 1,
      "toAddress": "0xRecipientAddress",
      "network": "BNB",
      "amount": "100.00",
      "status": "completed",
      "txHash": "0xabc123...",
      "createdAt": "2026-06-01T10:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

curl "https://api.paychainly.com/api/integration/withdrawals/by-address/0xRecipientAddress?page=1&limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

Sandbox

POST/api/sandbox/credit

Credit Test Funds

Credit test USDT to a sandbox deposit address to simulate a payment. Only works in sandbox mode — no real funds involved. Use this to test your integration end-to-end without sending real crypto.

Headers

Content-Typeapplication/jsonrequired

X-Api-KeyYOUR_API_KEYrequired

Body Parametersapplication/json

ParameterTypeRequiredDescription

addressstringrequiredSandbox deposit address to credit (0x...)

amountstringrequiredAmount of test USDT to credit e.g. "100"

Responses

{
  "success": true,
  "data": {
    "address": "0xYourSandboxDepositAddress",
    "amount": "100",
    "txHash": "0xsimulated_tx_hash",
    "status": "simulated"
  }
}

curl -X POST https://api.paychainly.com/api/sandbox/credit \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "address": "0xYourSandboxDepositAddress",
    "amount": "100"
  }'

Error Codes

All error responses follow the same envelope. The code field is machine-readable and stable — use it in your error handling logic.

StatusCode

401

API_KEY_REQUIREDNo API key was provided in the request

401

INVALID_API_KEYThe API key is invalid, expired, or revoked

403

FORBIDDENThe key does not have permission for this resource

404

NOT_FOUNDThe requested resource does not exist

422

VALIDATION_ERROROne or more request fields failed validation

500

INTERNAL_ERRORUnexpected server-side error

Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or missing API key"
  }
}