PayStablecoin API

English

繁体中文

English

繁体中文

Appearance

API Reference ​

Base URL ​

All API requests should be made to the following base URL:

Production Environment:

https://api.paystablecoin.global

Complete endpoint example:

https://api.paystablecoin.global/api/v1/merchants/{merchantId}/orders

API ENVIRONMENT

A Sandbox environment is available for development and testing:

https://api.sandbox.paystablecoin.global

Use the Production environment when you are ready to go live:

https://api.paystablecoin.global

Order API ​

The Order API allows merchants to create and query payment orders. Orders support both fiat (USD) and stablecoin (USDT) pricing, and can be configured to restrict available payment methods per transaction.

1. Create Order ​

Function Description ​

Enables merchants to create payment orders, supporting both fiat currency and stablecoin pricing.

Endpoint Information ​

  • Method: POST
  • Path: /api/v1/merchants/{merchantId}/orders
  • Content-Type: application/json
  • Authentication: Base64(HMAC-SHA256(timestamp + "\n" + method + "\n" + path + "\n" + SHA256(body), API_SECRET))

Request Headers ​

HeaderTypeRequiredDescriptionExample
X-Api-KeyStringYesMerchant API keyPSTG6ELOB2YXKO4ZHRQ6NKTSBY
X-TimestampLongYesRequest timestamp (milliseconds)1738112345000
X-SignatureStringYesRequest signaturebase64-hmac-sha256
Content-TypeStringYesFixed valueapplication/json

Path Parameters ​

ParameterTypeRequiredDescriptionExample
merchantIdStringYesMerchant ID (assigned by platform)1000

Request Body Parameters ​

Required Parameters ​

ParameterTypeDescriptionExample
merchantOrderIdStringMerchant order ID (16-64 chars, alphanumeric + - _)your-order-123456789
orderAmountObjectOrder amount (see structure below ↓){"value":"99.99","currency":"USD"}
expiresAtStringOrder expiration time (UTC, ISO 8601)2025-10-01T12:00:00Z
returnUrlStringCustomer browser redirect URL after payment (max 2048 chars)https://merchant.com/success

OrderAmount Object Structure:

FieldTypeRequiredDescriptionExample
valueStringYesAmount value (supports up to 18 decimal places)99.99
currencyStringYesCurrency code (3-16 uppercase alphanumeric)USD / USDT

Notes:

  • Fiat pricing: {"value": "99.99", "currency": "USD"} - Converted to equivalent USDT at payment time
  • Stablecoin pricing: {"value": "100.00", "currency": "USDT"} - Direct USDT payment

Optional Parameters - Payment Configuration ​

ParameterTypeDescriptionExample
paymentMethodConfigObjectPayment method configuration (see structure below ↓)See below
callbackUrlStringServer-to-server webhook URL for order status updates (HTTPS, max 2048 chars)https://merchant.com/webhook

PaymentMethodConfig Object Structure:

FieldTypeRequiredDescriptionExample
allowedPaymentMethodTypesArrayNoAllowed payment types: ON_CHAIN_TRANSFER (wallet), EXCHANGE_TRANSFER (exchange). Empty/null = no restriction["EXCHANGE_TRANSFER"]
allowedPaymentMethodsArrayNoSpecific payment methods (applies only to EXCHANGE_TRANSFER): BINANCE, KUCOIN. Empty/null = no restriction["BINANCE", "KUCOIN"]

Configuration Priority:

  1. If allowedPaymentMethods is specified, only these payment methods are shown
  2. If allowedPaymentMethodTypes is specified, only these types are shown
  3. If both are unspecified (null or empty), all available payment methods are shown

IMPORTANT

If you specify allowedPaymentMethods (e.g., ["BINANCE"]), you MUST also specify allowedPaymentMethodTypes that includes EXCHANGE_TRANSFER. Otherwise, the checkout may show unintended payment methods.

Recommended: Always specify both fields together when restricting to specific exchanges.

CONFIGURATION EXAMPLES

Example 1: Binance Pay Only

json
{
  "allowedPaymentMethodTypes": ["EXCHANGE_TRANSFER"],
  "allowedPaymentMethods": ["BINANCE"]
}

Example 2: On-Chain Payments Only

json
{
  "allowedPaymentMethodTypes": ["ON_CHAIN_TRANSFER"]
}

Example 3: Binance + Kucoin

json
{
  "allowedPaymentMethodTypes": ["EXCHANGE_TRANSFER"],
  "allowedPaymentMethods": ["BINANCE", "KUCOIN"]
}

Example 4: No Restrictions (Default)

json
{
  "paymentMethodConfig": null
}

or omit the field entirely.

Example 5: Mixed - Binance + On-Chain

json
{
  "allowedPaymentMethodTypes": ["ON_CHAIN_TRANSFER", "EXCHANGE_TRANSFER"],
  "allowedPaymentMethods": ["BINANCE"]
}

This allows all on-chain payment methods plus Binance Pay.

Understanding callbackUrl vs returnUrl:

These two URL parameters serve different purposes in the payment flow:

  • callbackUrl (Server-to-Server Webhook)

    • Purpose: Receives real-time payment status notifications from PayStablecoin servers
    • When triggered: Automatically called when order status changes
    • Usage: Your backend server processes these notifications to update order status
    • Optional but recommended for reliable payment confirmation

  • returnUrl (Browser Redirect)

    • Purpose: Redirects the customer's browser back to your website after payment
    • When triggered: After customer completes or cancels payment on the checkout page
    • Usage: Display order confirmation or thank you page to the customer
    • Required for good user experience

BEST PRACTICE

Always use both URLs:

  • callbackUrl for reliable backend order processing (even if user closes browser)
  • returnUrl for smooth user experience (customer sees confirmation page)

Optional Parameters - Customer Information ​

ParameterTypeDescriptionExample
customerObjectCustomer information for risk control (see structure below ↓)See below
customerIpStringCustomer IP address (IPv4/IPv6)203.0.113.10
userAgentStringCustomer User-Agent (0-512 characters)Mozilla/5.0...

Customer Object Structure:

FieldTypeRequiredDescriptionExample
customerIdStringNoCustomer ID (from merchant system)u1001
emailStringNoEmail address (for notifications)user@example.com
nameStringNoCustomer nameJohn Doe
phoneStringNoPhone number1234567890

Optional Parameters - Order Details ​

ParameterTypeDescriptionExample
descriptionStringOrder description (0-512 characters)Monthly membership recharge
itemsArrayLine item details (see structure below ↓)See below
metadataStringMerchant custom metadata (JSON format, max 4096 chars){"customerId":"u1001"}

LineItem Object Structure:

FieldTypeRequiredDescriptionExample
nameStringYesItem nameDiamond Pack x10
quantityIntegerYesQuantity (must be > 0)1
amountObjectYesUnit price (same as OrderAmount structure){"value":"99.99","currency":"USD"}
descriptionStringNoItem descriptionIn-game virtual currency
imageUrlStringNoItem image URLhttps://example.com/img.jpg

Optional Parameters - Platform Merchants Only ​

ParameterTypeDescriptionExample
subMerchantsArraySub-merchant information list (see structure below ↓)See below

SubMerchant Object Structure:

FieldTypeRequiredDescriptionExample
subMerchantIdStringYesSub-merchant ID (1-32 characters)SUB_001
nameStringYesSub-merchant name (1-256 characters)Apple Store
amountStringYesSplit amount (must be > 0.01)500.00
mccStringNoMerchant Category Code (4 digits, ISO 18245)5732
settlementRatioStringNoSettlement ratio (0-1, e.g., 0.95 = 95%)0.95

IMPORTANT

The sum of all sub-merchant amounts must equal the total order amount.

Complete Request Example ​

CURL Example:

bash
curl -X POST https://api.paystablecoin.global/api/v1/merchants/1000/orders \
  -H "X-Api-Key: PSTG6ELOB2YXKO4ZHRQ6NKTSBY" \
  -H "X-Timestamp: 1738112345000" \
  -H "X-Signature: <base64-hmac-sha256>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantOrderId": "your-order-123456789",
    "orderAmount": {
      "value": "99.99",
      "currency": "USD"
    },
    "expiresAt": "2025-10-01T12:00:00Z",
    "paymentMethodConfig": {
      "allowedPaymentMethodTypes": ["ON_CHAIN_TRANSFER", "EXCHANGE_TRANSFER"],
      "allowedPaymentMethods": ["BINANCE"]
    },
    "description": "Monthly membership recharge",
    "customer": {
      "customerId": "u1001",
      "email": "user@example.com",
      "name": "John Doe"
    },
    "items": [
      {
        "name": "Diamond Pack x10",
        "quantity": 1,
        "amount": {
          "value": "99.99",
          "currency": "USD"
        },
        "description": "In-game virtual currency"
      }
    ],
    "customerIp": "203.0.113.10",
    "userAgent": "Mozilla/5.0...",
    "callbackUrl": "https://merchant.com/webhook",
    "returnUrl": "https://merchant.com/success",
    "metadata": "{\"customerId\":\"u1001\",\"source\":\"web\"}"
  }'

Response ​

All responses return HTTP Code 200, with business results expressed through status + code + message.

Response Field Descriptions ​

AcquiringOrderView (Order View) ​

FieldTypeDescriptionExample
orderIdStringPlatform order IDord_8fcb2a2e5b
merchantIdStringMerchant IDM0001
merchantOrderIdStringMerchant order IDyour-order-123456789
statusStringOrder statusINIT / PROCESSING / SUCCEEDED / FAILED / CLOSED
checkoutUrlStringCheckout page URLhttps://checkout.paystablecoin.global/...
createdAtStringCreation time (UTC, ISO 8601)2025-09-28T12:00:00Z
expiresAtStringExpiration time (UTC)2025-10-01T12:00:00Z
paidAtStringPayment time (UTC, returned only after payment)2025-09-29T10:30:00Z
orderAmountObjectOrder amountSee OrderAmount definition
cryptoPaidAmountObjectActual stablecoin payment amountSee OrderAmount definition
cryptoPaymentDetailObjectCryptocurrency payment detailsSee CryptoPaymentDetail definition
standardResponseCodeStringStandard response code00000
standardResponseMessageStringResponse code descriptionSuccess

CryptoPaymentDetail (Cryptocurrency Payment Details - Returned Only After Successful Payment) ​

FieldTypeDescriptionExample
txHashStringTransaction hash0x1234...abcd
networkStringBlockchain networkTRON / ETHEREUM
fromAddressStringPayer addressTXYz...4567
toAddressStringPayee addressTQRs...8901
confirmationsIntegerNumber of confirmations21
blockNumberLongBlock height12345678

Response Examples ​

Success Response (status=INIT):

json
{
  "code": "00000",
  "message": "Success",
  "data": {
    "orderId": "ord_8fcb2a2e5b",
    "merchantId": "M0001",
    "merchantOrderId": "your-order-123456789",
    "status": "INIT",
    "checkoutUrl": "https://checkout.paystablecoin.global/ord_8fcb2a2e5b",
    "createdAt": "2025-09-28T12:00:00Z",
    "expiresAt": "2025-10-01T12:00:00Z",
    "orderAmount": {
      "value": "99.99",
      "currency": "USD"
    },
    "cryptoPaidAmount": null,
    "cryptoPaymentDetail": null,
    "standardResponseCode": "00000",
    "standardResponseMessage": "Success"
  }
}

Failure Response (status=FAILED):

json
{
  "code": "10001",
  "message": "Invalid parameter: orderAmount.currency must be ISO 4217",
  "data": {
    "orderId": null,
    "merchantId": "M0001",
    "merchantOrderId": "your-order-123456789",
    "status": "FAILED",
    "standardResponseCode": "10001",
    "standardResponseMessage": "Invalid parameter"
  }
}

2. Query Order ​

Function Description ​

Enables merchants to query detailed information about a single order, supporting queries by either merchant order ID or platform order ID.

Endpoint Information ​

  • Method: GET
  • Path: /api/v1/merchants/{merchantId}/orders/{merchantOrderId}
  • Signature Note: GET requests have no Body, signature content is timestamp + "\n" + method + "\n" + path
  • Authentication: Same as Create Order endpoint

Request Headers ​

HeaderTypeRequiredDescriptionExample
X-Api-KeyStringYesMerchant API keyPSTG6ELOB2YXKO4ZHRQ6NKTSBY
X-TimestampLongYesRequest timestamp (milliseconds)1738112345000
X-SignatureStringYesRequest signature (no Body, sign path)base64-hmac-sha256
Content-TypeStringYesFixed valueapplication/json

Path Parameters ​

ParameterTypeRequiredDescriptionExample
merchantIdStringYesMerchant ID1000
merchantOrderIdStringYesMerchant order IDyour-order-123456789

Example Request:

bash
curl -X GET "https://api.paystablecoin.global/api/v1/merchants/1000/orders/your-order-123456789" \
  -H "X-Api-Key: PSTG6ELOB2YXKO4ZHRQ6NKTSBY" \
  -H "X-Timestamp: 1738112345000" \
  -H "X-Signature: <base64-hmac-sha256>" \
  -H "Content-Type: application/json"

Signature String: 1738112345000\nGET\n/api/v1/merchants/1000/orders/your-order-123456789

Response ​

All responses return HTTP Code 200, with business results expressed through status + code + message.

Response Field Descriptions ​

AcquiringOrderView (Order Details) ​

FieldTypeDescriptionExample
orderIdStringPlatform order IDord_8fcb2a2e5b
merchantIdStringMerchant IDM0001
merchantOrderIdStringMerchant order IDyour-order-123456789
statusStringOrder status (see status descriptions)INIT / SUCCEEDED / FAILED / CLOSED
checkoutUrlStringCheckout page URLhttps://checkout.exsatpay.com/...
createdAtStringOrder creation time (UTC, ISO 8601)2025-09-28T12:00:00Z
expiresAtStringOrder expiration time (UTC)2025-10-01T12:00:00Z
paidAtStringPayment success time (UTC, returned only after payment)2025-09-28T12:05:10Z
orderAmountObjectOrder amount (merchant pricing)See OrderAmount definition
cryptoPaidAmountObjectActual payment amount (cryptocurrency)See OrderAmount definition
cryptoPaymentDetailObjectOn-chain payment details (returned only after payment)See CryptoPaymentDetail definition
standardResponseCodeStringStandard response code00000
standardResponseMessageStringResponse code descriptionSuccess

CryptoPaymentDetail (On-Chain Payment Details - Returned Only After Successful Payment) ​

FieldTypeDescriptionExample
txHashStringTransaction hash (viewable on blockchain explorer)0xabcf2a2e5b8fcb...
networkStringBlockchain networkTRON / ETHEREUM / BSC
fromAddressStringPayer address (customer wallet address)TKeoD2qV8HR4sfm4b9a3e2g1jCD7fDCZuv
toAddressStringPayee address (platform receiving address)TPoD2qV8HR4sfm4b9a3e2g1jCD7fDAZaa
confirmationsIntegerNumber of block confirmations25
blockNumberLongBlock height of transaction45678901

Order Status Descriptions ​

StatusDescriptionIs Final?Possible Next States
INITOrder created, awaiting paymentNoPROCESSING / CLOSED
PROCESSINGPayment processing (on-chain transaction detected)NoSUCCEEDED / FAILED
SUCCEEDEDPayment successful (received and confirmed)Yes-
FAILEDPayment failed (insufficient amount/timeout/error)Yes-
CLOSEDOrder closed (merchant cancelled/auto-expired)Yes-

State Transition Diagram:

INIT ──┬──> PROCESSING ──┬──> SUCCEEDED (final)
       │                 └──> FAILED (final)
       └──> CLOSED (final, cancelled or expired)

Response Examples ​

Successful Query - Paid Order ​

json
{
  "code": "00000",
  "message": "Success",
  "data": {
    "orderId": "ord_8fcb2a2e5b",
    "merchantId": "M0001",
    "merchantOrderId": "your-order-123456789",
    "status": "SUCCEEDED",
    "checkoutUrl": "https://checkout.paystablecoin.global/ord_8fcb2a2e5b",
    "createdAt": "2025-09-28T12:00:00Z",
    "expiresAt": "2025-10-01T12:00:00Z",
    "paidAt": "2025-09-28T12:05:10Z",
    "orderAmount": {
      "value": "99.99",
      "currency": "USD"
    },
    "cryptoPaidAmount": {
      "value": "100.02",
      "currency": "USDT"
    },
    "cryptoPaymentDetail": {
      "txHash": "0xabcf2a2e5b8fcb2a2e5b8fcb2a2e5b8fcb2a2e5b8fcb2a2e5b8fcb2a2e5b8f",
      "network": "TRON",
      "fromAddress": "TKeoD2qV8HR4sfm4b9a3e2g1jCD7fDCZuv",
      "toAddress": "TPoD2qV8HR4sfm4b9a3e2g1jCD7fDAZaa",
      "confirmations": 25,
      "blockNumber": 45678901
    },
    "standardResponseCode": "00000",
    "standardResponseMessage": "Success"
  }
}

Successful Query - Pending Order ​

When order is awaiting payment, paidAt, cryptoPaidAmount, and cryptoPaymentDetail will be null:

json
{
  "code": "00000",
  "message": "Success",
  "data": {
    "orderId": "ord_9def3c5e7d",
    "merchantId": "M0001",
    "merchantOrderId": "pending-order-456",
    "status": "INIT",
    "checkoutUrl": "https://checkout.paystablecoin.global/ord_9def3c5e7d",
    "createdAt": "2025-09-29T10:00:00Z",
    "expiresAt": "2025-10-02T10:00:00Z",
    "paidAt": null,
    "orderAmount": {
      "value": "199.99",
      "currency": "USD"
    },
    "cryptoPaidAmount": null,
    "cryptoPaymentDetail": null,
    "standardResponseCode": "00000",
    "standardResponseMessage": "Success"
  }
}

Failed Query - Order Not Found ​

json
{
  "code": "40001",
  "message": "Order not found",
  "data": {
    "orderId": null,
    "merchantId": "M0001",
    "merchantOrderId": "your-order-not-exist",
    "status": "FAILED",
    "standardResponseCode": "40001",
    "standardResponseMessage": "Order not found"
  }
}

Important Notes ​

  1. Field Availability:

    • paidAt: Returned only when order payment is successful (status=SUCCEEDED)
    • cryptoPaidAmount: Returned only when order payment is successful
    • cryptoPaymentDetail: Returned only when order payment is successful, contains on-chain transaction details

  2. Amount Differences:

    • orderAmount: Pricing amount when merchant creates order (may be fiat or stablecoin)
    • cryptoPaidAmount: Actual cryptocurrency amount paid by customer (may differ slightly due to exchange rate conversion)
    • Example: Order amount 99.99 USD, actual payment 100.02 USDT (due to exchange rate fluctuation)

  3. Confirmation Count Explanation:

    • confirmations: Blockchain confirmation count, higher value = more secure
    • Different network confirmation requirements:
      • TRON: Typically requires 19 confirmations
      • ETHEREUM: Typically requires 12 confirmations
      • BSC: Typically requires 15 confirmations

  4. Query Frequency Recommendations:

    • After order creation, recommend querying status every 5-10 seconds
    • After order payment success, no need to continue querying
    • Using Webhook callbacks can reduce active query frequency and improve efficiency

Refund API ​

The Refund API allows merchants to initiate refunds for completed payments. Refunds are always processed for the full original order amount. After submission, a refund request goes through immediate validation, fund reservation, asynchronous processing, and result notification stages.

3. Create Refund ​

Endpoint Information ​

  • Method: POST
  • Path: /api/v1/merchants/{merchantId}/refunds
  • Content-Type: application/json
  • Authentication: Required

Request Headers ​

HeaderTypeRequiredDescriptionExample
X-Api-KeyStringYesMerchant API keyPSTG6ELOB2YXKO4ZHRQ6NKTSBY
X-TimestampLongYesRequest timestamp (milliseconds, 13 digits)1738112345000
X-SignatureStringYesRequest signature (Base64-encoded). Algorithm: Base64(HMAC-SHA256(timestamp\nMETHOD\npath\nBase64(SHA256(body)), apiSecret))base64-hmac-sha256
Content-TypeStringYesFixed valueapplication/json

Path Parameters ​

ParameterTypeRequiredDescriptionExample
merchantIdStringYesMerchant ID (assigned by platform)1000

Request Body Parameters ​

FieldTypeRequiredDescriptionExample
merchantRefundOrderIdStringYesMerchant refund order ID (globally unique, used for idempotency)REFUND_20260128_001
acquiringOrderIdStringYesOriginal payment order ID (PSC order to refund)ORDER_20260128_001
refundReasonStringYesRefund reason (English, for review and traceability)Customer request full refund
notifyUrlStringNoRefund result notification URL. Uses merchant default config if omittedhttps://merchant.example.com/webhook/refund
extraDataStringNoExtra data in JSON format, returned as-is{"orderId":"MERCHANT_ORDER_123"}

Request Example ​

bash
curl -X POST https://api.paystablecoin.global/api/v1/merchants/1000/refunds \
  -H "X-Api-Key: PSTG6ELOB2YXKO4ZHRQ6NKTSBY" \
  -H "X-Timestamp: 1738112345000" \
  -H "X-Signature: <base64-hmac-sha256>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantRefundOrderId": "REFUND_20260128_001",
    "acquiringOrderId": "ORDER_20260128_001",
    "refundReason": "Customer request full refund",
    "notifyUrl": "https://merchant.example.com/webhook/refund",
    "extraData": "{\"orderId\":\"MERCHANT_ORDER_123\",\"userId\":\"USER_456\"}"
  }'

Response Fields ​

FieldTypeDescriptionExample
codeStringResponse code. 00000 indicates the refund application was accepted00000
messageStringResponse messageRefund application accepted
dataObjectRefund order data (see RefundOrderData below)-
requestIdStringRequest ID for tracingreq_abc123xyz
timestampLongResponse timestamp (milliseconds)1706428800000

RefundOrderData ​

FieldTypeDescriptionExample
refundOrderIdStringPSC refund order ID (globally unique)REF_20260128120001
merchantRefundOrderIdStringMerchant refund order IDREFUND_20260128_001
acquiringOrderIdStringOriginal payment order IDORDER_20260128_001
merchantOrderIdStringMerchant's original order IDMERCHANT_ORDER_123
statusStringRefund status (see status table below)PENDING
refundAmountStringRefund amount (user's actual payment amount)100.50
refundCurrencyStringRefund currencyUSDT
merchantDeductAmountStringAmount deducted from merchant (net settlement amount)100.1985
paymentMethodStringOriginal payment methodBINANCE_PAY
createdTimeString (ISO 8601)Creation time2026-01-28T12:00:00Z
estimatedCompletionTimeString (ISO 8601)Estimated completion time2026-01-28T12:15:00Z
completedTimeString (ISO 8601)Completion time (SUCCEEDED only)2026-01-28T12:05:30Z
failedTimeString (ISO 8601)Failure time (FAILED only)2026-01-28T12:03:15Z
closedTimeString (ISO 8601)Closed time (CLOSED only)2026-01-28T14:30:00Z
errorCodeStringError code (FAILED only)EXCHANGE_BALANCE_INSUFFICIENT
errorMessageStringError message (FAILED only)Insufficient funds in Binance funding wallet
extraDataStringExtra data, returned as-is{"orderId":"MERCHANT_ORDER_123"}

Refund Status Values ​

StatusDescriptionIs Final?
INITRefund record createdNo
PENDINGApplication accepted, awaiting processingNo
PROCESSINGProcessing in progressNo
SUCCEEDEDRefund completed successfullyYes
FAILEDRefund failedYes
CLOSEDRefund closedYes

Response Examples ​

Success — refund accepted:

json
{
  "code": "00000",
  "message": "Refund application accepted",
  "data": {
    "refundOrderId": "REF_20260128120001",
    "merchantRefundOrderId": "REFUND_20260128_001",
    "acquiringOrderId": "ORDER_20260128_001",
    "merchantOrderId": "MERCHANT_ORDER_123",
    "status": "PENDING",
    "refundAmount": "100.50",
    "refundCurrency": "USDT",
    "merchantDeductAmount": "100.1985",
    "paymentMethod": "BINANCE_PAY",
    "createdTime": "2026-01-28T12:00:00Z",
    "estimatedCompletionTime": "2026-01-28T12:15:00Z"
  },
  "requestId": "req_abc123xyz",
  "timestamp": 1706428800000
}

Error — insufficient balance:

json
{
  "code": "INSUFFICIENT_BALANCE",
  "message": "Merchant balance insufficient for refund",
  "details": "Required: 100.00 USDT, Available: 50.00 USDT",
  "requestId": "req_abc123xyz",
  "timestamp": 1706428800000
}

Error — refund period expired:

json
{
  "code": "REFUND_PERIOD_EXPIRED",
  "message": "Order refund period has expired",
  "details": "Order paid at: 2025-12-15T10:00:00Z, Refund deadline: 2026-01-14T10:00:00Z (30 days)",
  "requestId": "req_abc123xyz",
  "timestamp": 1706428800000
}

HTTP Status Codes ​

HTTP StatusMeaningDescription
200OKRefund application accepted
400Bad RequestInvalid parameters or business validation failed
401UnauthorizedSignature verification failed
404Not FoundOrder not found
429Too Many RequestsRate limit exceeded

4. Query Refund ​

Endpoint Information ​

  • Method: GET
  • Path: /api/v1/merchants/{merchantId}/refunds
  • Authentication: Required
  • Signature Note: GET requests have no body. Query parameters are hashed separately as the fourth component. Algorithm: Base64(HMAC-SHA256(timestamp\nMETHOD\npath\nBase64(SHA256(queryString)), apiSecret))

TIP

At least one query parameter (refundOrderId, merchantRefundOrderId, or acquiringOrderId) must be provided.

Request Headers ​

HeaderTypeRequiredDescriptionExample
X-Api-KeyStringYesMerchant API keyPSTG6ELOB2YXKO4ZHRQ6NKTSBY
X-TimestampLongYesRequest timestamp (milliseconds)1738112345000
X-SignatureStringYesRequest signature (no body)base64-hmac-sha256

Path Parameters ​

ParameterTypeRequiredDescriptionExample
merchantIdStringYesMerchant ID1000

Query Parameters ​

ParameterTypeRequiredDescriptionExample
refundOrderIdStringNoPSC refund order ID (highest priority)REF_20260128120001
merchantRefundOrderIdStringNoMerchant refund order IDREFUND_20260128_001
acquiringOrderIdStringNoOriginal payment order ID (returns the first refund for that order)ORDER_20260128_001

Request Example ​

bash
curl -X GET "https://api.paystablecoin.global/api/v1/merchants/1000/refunds?refundOrderId=REF_20260128120001" \
  -H "X-Api-Key: PSTG6ELOB2YXKO4ZHRQ6NKTSBY" \
  -H "X-Timestamp: 1738112345000" \
  -H "X-Signature: <base64-hmac-sha256>"

Signature string: 1738112345000\nGET\n/api/v1/merchants/1000/refunds\nBase64(SHA256("refundOrderId=REF_20260128120001"))

Response ​

Returns the same code / message / data / requestId / timestamp envelope, with data being a single RefundOrderData object (see RefundOrderData above).

Response Examples ​

Succeeded refund:

json
{
  "code": "00000",
  "message": "Query successful",
  "data": {
    "refundOrderId": "REF_20260128120001",
    "merchantRefundOrderId": "REFUND_20260128_001",
    "acquiringOrderId": "ORDER_20260128_001",
    "merchantOrderId": "MERCHANT_ORDER_123",
    "status": "SUCCEEDED",
    "refundAmount": "100.50",
    "refundCurrency": "USDT",
    "merchantDeductAmount": "100.1985",
    "paymentMethod": "BINANCE_PAY",
    "createdTime": "2026-01-28T12:00:00Z",
    "completedTime": "2026-01-28T12:05:30Z",
    "extraData": "{\"orderId\":\"MERCHANT_ORDER_123\"}"
  },
  "requestId": "req_xyz789abc",
  "timestamp": 1706428835000
}

Failed refund:

json
{
  "code": "00000",
  "message": "Query successful",
  "data": {
    "refundOrderId": "REF_20260128120003",
    "merchantRefundOrderId": "REFUND_20260128_003",
    "acquiringOrderId": "ORDER_20260128_003",
    "status": "FAILED",
    "refundAmount": "75.00",
    "refundCurrency": "USDT",
    "paymentMethod": "BINANCE_PAY",
    "createdTime": "2026-01-28T12:02:00Z",
    "failedTime": "2026-01-28T12:03:15Z",
    "errorCode": "EXCHANGE_BALANCE_INSUFFICIENT",
    "errorMessage": "Insufficient funds in Binance funding wallet"
  },
  "requestId": "req_xyz789abc",
  "timestamp": 1706428835000
}

Not found:

json
{
  "code": "REFUND_NOT_FOUND",
  "message": "Refund order not found",
  "details": "merchantRefundOrderId: REFUND_NONEXISTENT",
  "requestId": "req_notfound123",
  "timestamp": 1706428900000
}

HTTP Status Codes ​

HTTP StatusMeaningDescription
200OKQuery successful
404Not FoundRefund order not found

5. Batch Query Refunds ​

Endpoint Information ​

  • Method: POST
  • Path: /api/v1/merchants/{merchantId}/refunds/batch-query
  • Content-Type: application/json
  • Authentication: Required

Use this endpoint for bulk reconciliation, report generation, or status sync. A single request supports up to 100 refund orders.

Request Headers ​

Same as Create Refund.

Path Parameters ​

ParameterTypeRequiredDescriptionExample
merchantIdStringYesMerchant ID1000

Request Body Parameters ​

FieldTypeRequiredDescriptionExample
merchantRefundOrderIdsArray<String>YesList of merchant refund order IDs (max 100)["REFUND_001", "REFUND_002"]

Request Example ​

bash
curl -X POST https://api.paystablecoin.global/api/v1/merchants/1000/refunds/batch-query \
  -H "X-Api-Key: PSTG6ELOB2YXKO4ZHRQ6NKTSBY" \
  -H "X-Timestamp: 1738112345000" \
  -H "X-Signature: <base64-hmac-sha256>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantRefundOrderIds": [
      "REFUND_20260128_001",
      "REFUND_20260128_002",
      "REFUND_20260128_003"
    ]
  }'

Response Fields ​

FieldTypeDescription
codeString00000 indicates success
messageStringResponse message
dataArrayList of RefundOrderData objects (same structure as single query)
requestIdStringRequest ID
timestampLongResponse timestamp (milliseconds)

Response Example ​

json
{
  "code": "00000",
  "message": "Batch query successful",
  "data": [
    {
      "refundOrderId": "REF_20260128120001",
      "merchantRefundOrderId": "REFUND_20260128_001",
      "status": "SUCCEEDED",
      "refundAmount": "100.50",
      "refundCurrency": "USDT"
    },
    {
      "refundOrderId": "REF_20260128120002",
      "merchantRefundOrderId": "REFUND_20260128_002",
      "status": "PROCESSING",
      "refundAmount": "50.00",
      "refundCurrency": "USDC"
    },
    {
      "refundOrderId": "REF_20260128120003",
      "merchantRefundOrderId": "REFUND_20260128_003",
      "status": "FAILED",
      "refundAmount": "75.00",
      "refundCurrency": "USDT",
      "errorCode": "EXCHANGE_BALANCE_INSUFFICIENT"
    }
  ],
  "requestId": "req_batch123",
  "timestamp": 1706428900000
}

Refund Webhook

Refund webhook notifications are documented in the Webhook Notifications page.

Released under the MIT License.

Copyright © 2025 PayStablecoin