Hosted Payments Integration Guide

Overview

The Hosted Payments API is the simplest way to accept crypto payments. You create an order through the API, then redirect your customer to PSC's hosted payment page. PSC handles the entire payment experience — method selection, authentication, and confirmation.

Best for:

• Merchants who want fast integration with minimal frontend work
• Accepting both exchange-based payments (Binance Pay, KuCoin Pay) and on-chain transfers
• Pricing in fiat (USD) with automatic conversion to stablecoin at payment time

---

How It Works

Merchant Server               PSC API              Customer Browser
      |                          |                        |
      |--- POST /orders -------->|                        |
      |<-- checkoutUrl ----------|                        |
      |                          |                        |
      |------------ redirect to checkoutUrl ------------>|
      |                          |<-- selects method -----|
      |                          |<-- completes payment --|
      |                          |                        |
      |<-- POST webhook ---------|                        |
      |--- HTTP 200 ------------>|                        |
      |                          |                        |
      |<----------- redirect to returnUrl ----------------|

---

Step 1: Create a Payment Order

Call POST /api/v1/merchants/{merchantId}/orders with your order details.

curl -X POST https://api.paystablecoin.global/api/v1/merchants/1000/orders \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Timestamp: 1738112345000" \
  -H "X-Signature: <calculated-signature>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantOrderId": "ORDER_20260128_001",
    "orderAmount": { "value": "99.99", "currency": "USD" },
    "expiresAt": "2026-01-28T13:00:00Z",
    "returnUrl": "https://your-store.com/order/success",
    "callbackUrl": "https://your-server.com/webhook/payment"
  }'

Key parameters:

Parameter	Purpose
orderAmount.currency	USD for fiat pricing (auto-converted to USDT at payment time), or USDT for direct stablecoin
returnUrl	Where the customer is redirected after completing or cancelling payment
callbackUrl	Your server endpoint that receives async payment status updates
expiresAt	Recommended: 30 minutes from now
paymentMethodConfig	Optional — restrict to specific payment methods (see below)

Response:

{
  "code": "00000",
  "data": {
    "orderId": "PSC_ORDER_123",
    "checkoutUrl": "https://pay.paystablecoin.global/checkout/PSC_ORDER_123",
    "status": "PENDING"
  }
}

---

Step 2: Redirect the Customer

Redirect the customer's browser to the checkoutUrl from the response. PSC's hosted page handles everything:

• Payment method selection (Binance Pay, KuCoin Pay, on-chain wallet)
• Exchange authentication
• Payment confirmation and receipt

You do not need to build any payment UI.

---

Step 3: Receive the Webhook

When the order status changes (paid, failed, expired), PSC sends a POST to your callbackUrl.

Respond with HTTP 200 immediately. Any other response or timeout triggers a retry.

See Webhook Notifications for the full payload structure, signature verification, and retry schedule.

---

Step 4: Handle the Return URL

After payment, PSC redirects the customer to your returnUrl. Use this page to show a confirmation message.

WARNING

Do not rely on the returnUrl to confirm payment. A customer can close the browser before the redirect completes. Always verify payment status through the webhook or by querying the order directly.

---

Restricting Payment Methods

By default, all payment methods available to your account are shown. Use paymentMethodConfig to restrict:

Binance Pay only:

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

On-chain transfers only:

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

Binance Pay + on-chain (mixed):

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

See API Reference for the full paymentMethodConfig specification.

---

Key Checklist

• [ ] Generate a unique merchantOrderId per order (used for idempotency)
• [ ] Set expiresAt to ~30 minutes from creation
• [ ] Always include callbackUrl — do not rely on returnUrl for payment confirmation
• [ ] Verify webhook signature before processing any business logic
• [ ] Handle idempotency: the same merchantOrderId submitted twice returns the existing order

---

Related Documentation

• API Reference — Full endpoint and field specification
• Refund API — Initiate and query refunds for completed orders
• Webhook Notifications — Payment event notifications, retry schedule, and signature verification
• Signature Algorithm — How to calculate the request signature