Create Payment

🛠️ 1. Preparation: Get Currency Config

DogPay supports multiple blockchains and cryptocurrencies. Before creating an order, you need to know the unique configuration ID (currencyConfigId) for the target currency on a specific chain.

You can call the Get Currency Config endpoint to retrieve the supported list. For example, getting the USDT config on Ethereum:

// Response snippet example
{
  "id": "config_eth_usdt_001",
  "pay_channel": "pay_002",
  "currency": "USDT",
  "chain": "Ethereum",
  "status": "active"
}

Note: Please save the id you want to use, as it will be passed as the currencyConfigId when creating the order.

🚀 2. Initiate Create Order Request

Once you have the configuration ID, you can call the Create Pay Order endpoint to create an order.

⚠️
Developer Notes

Minimum Amount: To prevent micro-amounts (dust amounts) from being filtered by the network, the order amount (orderAmount) must be greater than or equal to 0.02. For example, if you pass 0.01 during a top-up test, the order will be blocked by the system.

Channel Version: Due to system upgrades, please prioritize setting the payChannel parameter to a fixed value of pay_002. The old channel (pay_001) is no longer being updated.

Example Request

curl -X POST "[https://sandbox-api-v2.dogpay.com/open-api/v1/pay](https://sandbox-api-v2.dogpay.com/open-api/v1/pay)" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "orderAmount": "0.02",
           "payChannel": "pay_002",
           "currencyConfigId": "config_eth_usdt_001",
           "goodsName": "Premium Subscription",
           "callId": "order_req_1712345678",
           "successUrl": "[https://your-merchant-site.com/payment/success](https://your-merchant-site.com/payment/success)",
           "failureUrl": "[https://your-merchant-site.com/payment/failed](https://your-merchant-site.com/payment/failed)"
         }'

Core Parameters Overview

Parameter	Required	Description
`orderAmount`	Yes	The order amount (in your configured fiat or stablecoin). Must be $\ge$ 0.02.
`payChannel`	No	The payment channel. Preferentially use `pay_002`.
`currencyConfigId`	Yes	The combined configuration ID for the chain and currency (obtained in Step 1).
`goodsName`	Yes	The product name or short description that will be displayed on the checkout page.
`callId`	Yes	A unique request ID generated by your business system, used to ensure request Idempotency.
`successUrl`	No	The URL to which the frontend will redirect after the user successfully completes the payment.
`failureUrl`	No	The URL to which the frontend will redirect if the payment fails or is actively cancelled.

🔗 3. Handle Response & Display Checkout

If the request is successful, DogPay will return the complete response data containing the payUrl (hosted checkout link). The checkout link is returned in data.transaction.payUrl.

Example Response

{
  "code": 0,
  "message": "",
  "data": {
    "transaction": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "idNo": "2100000000000000001",
      "transactionAt": "2026-01-01T00:00:00.000Z",
      "completedAt": null,
      "payType": null,
      "payer": null,
      "payChannel": "pay_002",
      "status": "pending",
      "amount": "10.00000000",
      "usdAmount": "10.00000000",
      "usdFeeAmount": "0.10000000",
      "currency": "USDT",
      "pay_currency": null,
      "payCurrency": null,
      "transactionId": null,
      "accountId": "00000000-0000-0000-0000-000000000000",
      "fee": "0.10000000",
      "usdRate": "1.00000000",
      "processStatus": "pending",
      "settleStatus": "unsettled",
      "type": "pay",
      "originPayOrderId": null,
      "callId": "demo_call_id_0001",
      "balanceId": null,
      "cursorId": null,
      "successUrl": null,
      "failureUrl": null,
      "extraData": {
        "goodsName": "test",
        "payType": "WEB",
        "lang": "zh"
      },
      "payChannelCurrencyId": "00000000-0000-0000-0000-000000000000",
      "waitAmountOnChain": null,
      "doneAmountOnChain": null,
      "address": null,
      "receiveAddress": null,
      "expireTime": 1790654075007,
      "payUrl": "https://pay.dogpay.com/?idno=550e8400-e29b-41d4-a716-446655440000&lang=zh",
      "customerNotes": null
    },
    "payInfo": {
      "payUrl": "https://pay.dogpay.com/?idno=550e8400-e29b-41d4-a716-446655440000&lang=zh",
      "expireTime": 1790654075007
    }
  },
  "timestamp": 1790567675011,
  "requestId": "req_demo_001"
}

Next Steps

Extract data.transaction.payUrl from the response. This is a hosted checkout link under the pay.dogpay.com domain. Display it to the user in your frontend application (this can be done via direct redirect, embedded iframe, or generating a QR code).
After the user completes the payment at the checkout, please ensure you listen to the relevant Webhook events to accurately update the order status in your system.