Skip to main content

Payment Quick Start

Process Overview​

1. Overview​

Payment Order: Pay Protocol's payment order is a payment request generated by merchants in the platform system. Users can complete payment through payment links or designated wallet addresses, and the system will automatically confirm payment and callback to the merchant.

Process: 👉 Merchant calls createPaymentOrder → Get payment link/sub-contract address → User payment → Pay Protocol callback → Merchant confirmation.

Note: API calls require signatures

2. Prerequisites​

  • Create merchant account: Sandbox Registration

  • Get API Key / Secret: Get API Key / Secret

  • Need to configure callback URL (notifyUrl) and redirect URL (redirectionUrl)

  • Confirm the network to use:

    • Sandbox environment: https://api-sandbox.payprotocol.network/api/mer
    • Production environment: https://api.payprotocol.network/api/mer

3. API Signature Authentication​

All requests need to add the following to Header:

HeaderDescription
X-PAY-KEYMerchant API Key
X-PAY-TIMESTAMPCurrent Unix timestamp (in seconds, error ≤ 60 seconds)
X-PAY-SIGNSignature, see "Signature Generation Rules" below

🔹 Signature Generation Rules​

Reference official documentation: Signature Rules

  1. Concatenate String
signString = timestamp + method + requestPath + body
  • timestamp: Request Unix timestamp (seconds)
  • method: HTTP method, e.g., GET, POST
  • requestPath: API path without domain, e.g., /api/mer/payment/createPaymentOrder
  • body: JSON string for POST requests, empty string for GET requests
  1. Use HMAC-SHA256 Algorithm
HMAC_SHA256(apiSecret, signString)

  1. Base64 Encoding

    Base64 encode the hash from the previous step to get the final X-PAY-SIGN

🔹 Request Header Example (HTTPS)​

POST /api/mer/payment/createPaymentOrder
Host: api-sandbox.payprotocol.network
Content-Type: application/json
X-PAY-KEY: your_api_key
X-PAY-TIMESTAMP: 1723971200
X-PAY-SIGN: <generated_signature>

🔹 Important Notes​

  1. All POST requests must include Content-Type: application/json
  2. timestamp difference with server time cannot exceed 60 seconds to prevent replay attacks
  3. body must be valid JSON, otherwise signature verification will fail

4. Create Payment Order (createPaymentOrder)​

createPaymentOrder API Documentation

Request Body Parameters​

ParameterTypeRequiredDescription
chainIdint32YesInternal chain ID, can be obtained from query chain list interface
descriptionstringYesOrder description
outTradeNostringYesMerchant order number, must be unique
isLegalTenderintYesWhether quote currency is fiat, 0=No, 1=Yes
quoteCurrencySymbolstringYesQuote currency symbol, fiat uses international standard symbols (USD/CNY), crypto uses coin symbols (USDT/ETH/TRX)
quoteAmountstringYesQuote amount, positive number, can include decimals
notifyUrluriYesMerchant callback URL, must be publicly accessible HTTPS address
redirectionUrluriYesRedirect URL after user payment success

Request Example​

POST /api/mer/payment/createPaymentOrder
Host: api-sandbox.payprotocol.network
Content-Type: application/json
X-PAY-KEY: your_api_key
X-PAY-TIMESTAMP: 1723971200
X-PAY-SIGN: RlpTCwGT7lECP7achGM4oqT+Y5fXYjOqTRAJ9VPdY2U=

Request Body Example​

{
  "chainId": 136,
  "description": "Purchase membership service - Monthly Card",
  "outTradeNo": "ORDER20250818001",
  "isLegalTender": 0,
  "quoteCurrencySymbol": "USDT",
  "quoteAmount": "9.99",
  "notifyUrl": "https://merchant.com/api/pay-callback",
  "redirectionUrl": "https://merchant.com/pay-success"
}

Response Example​

{
  "code": 200,
  "msg": "Success",
  "data": {
    "userWalletAddress": "TX85iLNzPsKYpreiwFmhuKiq1J2ZP7umfG",
    "saltHash": "0x6895cea1a486b4ee4353964321151eae18e74e42409c9ddfab05b654c65aa80b",
    "outPaymentNo": "202508191519455758358",
    "paymentUrl": "/payment?apiSign=Ktb%2BYciiHTb4si7SAYesIuPbzjnwGBwMcJAyZJjy2s0%3D"
  }
}

Description:

  • paymentUrl → Direct redirect to payment page (recommended)
  • userWalletAddress → Users can transfer directly to this address
  • outPaymentNo → Pay Protocol payment order number (save for querying)
warning

💡 In the sandbox environment, you can claim test tokens to simulate payment transactions:

  1. Refer to the Get Test Tokens Tutorial.
  2. Based on the currently selected chain (Tron Nile or Ethereum Sepolia), open the corresponding official faucet website.
  3. Enter your test wallet address and claim test tokens (USDT, ETH, TRX, etc.).
  4. Use the claimed test tokens to make payments through the generated paymentUrl to complete the payment process testing.

Note: All testnet tokens are only available for sandbox testing environments and have no real value.

Note: Testnet and mainnet are completely independent blockchain networks. Do not send mainnet assets to testnet addresses, or vice versa.

5. Payment Callback (paymentCallback)​

Pay Protocol will asynchronously POST to notifyUrl, merchants need to:

  1. Verify sign signature validity
  2. Update order status
  3. Return HTTP 200 for confirmation

Callback Example​

paymentCallback API Documentation

{
  "orgId": 2313,
  "outTradeNo": "ORDER20250818001",
  "outPaymentNo": "202508191519455758358",
  "description": "A sample order",
  "paymentStatus": 0,
  "paymentType": 1,
  "isLegalTender": 0,
  "chainId": 136,
  "quoteCurrencySymbol": "USDT",
  "quoteAmount": "9.99",
  "expectedAmount": "999746",
  "settlementCurrencySymbol": "USDT",
  "settlementAmount": "9900000",
  "fromAddress": "TDPxB717Jowzj5qh7jAqBi88HTRYPmZ5tE",
  "userWalletAddress": "TX85iLNzPsKYpreiwFmhuKiq1J2ZP7umfG",
  "transferHash": "928b3243c230f490f336bbb83b7089a7fd3d01cc5fd051b1d72a6e227a4a5064",
  "blockTime": 1712122830,
  "createTime": "2025-08-19 15:19:45"
}

6. Query Order (queryPaymentOrder)​

GET /api/mer/payment/detail?outTradeNo=ORDER20250818001
Host: api-sandbox.payprotocol.network

queryPaymentOrder API Documentation Parameter description: outTradeNo is required, which is the merchant order number used to query order status.

✅ Congratulations! You have completed the complete payment process:

Last updated on