Pay Order

Pay for an order using ssUSD on the StateSet Commerce Network

Overview

This endpoint processes ssUSD (StateSet USD) stablecoin payments for orders on the StateSet Commerce Network. The payment is executed through smart contracts, ensuring secure and transparent transactions with instant settlement.

Body

order_id · string · required

The unique identifier of the order to be paid

payment_method · object · required

Payment method details for stablecoin payment

Show properties

type · string · required

Payment method type. Supported values: “ssusd”, “usdc” (legacy)

wallet_address · string · required

The customer’s wallet address from which stablecoins will be debited

amount · object · required

The payment amount details

Show properties

value · string · required

The amount in stablecoin units (e.g., “100.50”)

denom · string · required

The denomination. Supported values: “ssusd”, “usdc” (legacy)

chain · string

The blockchain for payment. Options: “stateset” (default), “base”, “solana”, “cosmos”

split_payments · array

Optional array for splitting payments between multiple recipients

Show properties

recipient · string · required

Recipient wallet address

amount · string · required

Amount to send to this recipient

type · string

Recipient type: “merchant”, “platform_fee”, “affiliate”

metadata · object

Additional metadata for the payment

Show properties

memo · string

Optional memo or note for the payment

reference_number · string

External reference number for reconciliation

idempotency_key · string

Unique key to prevent duplicate payments

Response

success · boolean

Indicates whether the payment was successful

transaction · object

Transaction details

Show properties

tx_hash · string

The blockchain transaction hash

block_height · number

The block height where the transaction was included

timestamp · string

ISO 8601 timestamp of the transaction

gas_used · string

The amount of gas used for the transaction

chain · string

The blockchain where the transaction occurred

payment · object

Payment details

Show properties

payment_id · string

Unique identifier for the payment

order_id · string

The order ID that was paid

amount · object

The amount paid

Show properties

value · string

The stablecoin amount

denom · string

The denomination used (ssusd or usdc)

usd_value · string

USD equivalent value

status · string

Payment status: “completed”, “pending”, “failed”

splits · array

Payment split details if applicable

order · object

Updated order details

Show properties

order_id · string

The order identifier

status · string

New order status after payment

payment_status · string

Payment status: “paid”, “partially_paid”, “unpaid”

paid_at · string

ISO 8601 timestamp of payment

cURL

curl --location --request POST 'https://api.stateset.network/v1/order/pay' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "order_id": "order_1234567890",
  "payment_method": {
    "type": "ssusd",
    "wallet_address": "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
    "amount": {
      "value": "150.00",
      "denom": "ssusd"
    },
    "chain": "stateset"
  },
  "split_payments": [
    {
      "recipient": "stateset1merchantaddress123",
      "amount": "135.00",
      "type": "merchant"
    },
    {
      "recipient": "stateset1platformfeeaddress456",
      "amount": "15.00",
      "type": "platform_fee"
    }
  ],
  "metadata": {
    "memo": "Payment for Order #1234567890",
    "reference_number": "INV-2024-001",
    "idempotency_key": "pay_order_1234567890_001"
  }
}'

Response

{
  "success": true,
  "transaction": {
    "tx_hash": "B5E7A2D9F3C8E1A4D6B9C3F7E2A5D8B1E4C7F9A2D5B8E1C4F7A9D2E5B8C1F4A7",
    "block_height": 1234567,
    "timestamp": "2024-01-15T10:30:05Z",
    "gas_used": "75000",
    "chain": "stateset"
  },
  "payment": {
    "payment_id": "pay_9h8g7f6e5d4c3b2a",
    "order_id": "order_1234567890",
    "amount": {
      "value": "150.00",
      "denom": "ssusd",
      "usd_value": "150.00"
    },
    "status": "completed",
    "splits": [
      {
        "recipient": "stateset1merchantaddress123",
        "amount": "135.00",
        "type": "merchant",
        "tx_hash": "C6F8B3E0A6D9F4B7E3A6E9D4B7F0C3E8"
      },
      {
        "recipient": "stateset1platformfeeaddress456",
        "amount": "15.00",
        "type": "platform_fee",
        "tx_hash": "D7G9C4F1B7E0A5C8F4B7F0E5C8G1D4F9"
      }
    ]
  },
  "order": {
    "order_id": "order_1234567890",
    "status": "processing",
    "payment_status": "paid",
    "paid_at": "2024-01-15T10:30:05Z"
  }
}

Error Codes

Code	Description
INSUFFICIENT_FUNDS	The wallet does not have enough USDC to complete the payment
ORDER_NOT_FOUND	The specified order ID does not exist
ORDER_ALREADY_PAID	The order has already been paid
INVALID_WALLET_ADDRESS	The provided wallet address is invalid
PAYMENT_EXPIRED	The payment window for this order has expired
NETWORK_ERROR	There was an error communicating with the blockchain
SMART_CONTRACT_ERROR	The smart contract execution failed

Notes

• All payments are processed on the StateSet Commerce Network blockchain
• USDC amounts must be specified as strings to avoid floating-point precision issues
• The payment is atomic - either the entire payment succeeds or it fails completely
• Gas fees are paid in STATE tokens, not USDC
• Payments are final and cannot be reversed through the API (refunds must be processed separately)