> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<ParamField body="order_id" type="string" required>
  The unique identifier of the order to be paid
</ParamField>

<ParamField body="payment_method" type="object" required>
  Payment method details for stablecoin payment

  <Expandable title="properties">
    <ParamField body="type" type="string" required>
      Payment method type. Supported values: "ssusd", "usdc" (legacy)
    </ParamField>

    <ParamField body="wallet_address" type="string" required>
      The customer's wallet address from which stablecoins will be debited
    </ParamField>

    <ParamField body="amount" type="object" required>
      The payment amount details

      <Expandable title="properties">
        <ParamField body="value" type="string" required>
          The amount in stablecoin units (e.g., "100.50")
        </ParamField>

        <ParamField body="denom" type="string" required>
          The denomination. Supported values: "ssusd", "usdc" (legacy)
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="chain" type="string">
      The blockchain for payment. Options: "stateset" (default), "base", "solana", "cosmos"
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="split_payments" type="array">
  Optional array for splitting payments between multiple recipients

  <Expandable title="properties">
    <ParamField body="recipient" type="string" required>
      Recipient wallet address
    </ParamField>

    <ParamField body="amount" type="string" required>
      Amount to send to this recipient
    </ParamField>

    <ParamField body="type" type="string">
      Recipient type: "merchant", "platform\_fee", "affiliate"
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="metadata" type="object">
  Additional metadata for the payment

  <Expandable title="properties">
    <ParamField body="memo" type="string">
      Optional memo or note for the payment
    </ParamField>

    <ParamField body="reference_number" type="string">
      External reference number for reconciliation
    </ParamField>

    <ParamField body="idempotency_key" type="string">
      Unique key to prevent duplicate payments
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Indicates whether the payment was successful
</ResponseField>

<ResponseField name="transaction" type="object">
  Transaction details

  <Expandable title="properties">
    <ResponseField name="tx_hash" type="string">
      The blockchain transaction hash
    </ResponseField>

    <ResponseField name="block_height" type="number">
      The block height where the transaction was included
    </ResponseField>

    <ResponseField name="timestamp" type="string">
      ISO 8601 timestamp of the transaction
    </ResponseField>

    <ResponseField name="gas_used" type="string">
      The amount of gas used for the transaction
    </ResponseField>

    <ResponseField name="chain" type="string">
      The blockchain where the transaction occurred
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="payment" type="object">
  Payment details

  <Expandable title="properties">
    <ResponseField name="payment_id" type="string">
      Unique identifier for the payment
    </ResponseField>

    <ResponseField name="order_id" type="string">
      The order ID that was paid
    </ResponseField>

    <ResponseField name="amount" type="object">
      The amount paid

      <Expandable title="properties">
        <ResponseField name="value" type="string">
          The stablecoin amount
        </ResponseField>

        <ResponseField name="denom" type="string">
          The denomination used (ssusd or usdc)
        </ResponseField>

        <ResponseField name="usd_value" type="string">
          USD equivalent value
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="status" type="string">
      Payment status: "completed", "pending", "failed"
    </ResponseField>

    <ResponseField name="splits" type="array">
      Payment split details if applicable
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="order" type="object">
  Updated order details

  <Expandable title="properties">
    <ResponseField name="order_id" type="string">
      The order identifier
    </ResponseField>

    <ResponseField name="status" type="string">
      New order status after payment
    </ResponseField>

    <ResponseField name="payment_status" type="string">
      Payment status: "paid", "partially\_paid", "unpaid"
    </ResponseField>

    <ResponseField name="paid_at" type="string">
      ISO 8601 timestamp of payment
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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"
    }
  }'
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  async function payOrderWithSSUSD(orderId, amount, walletAddress) {
    try {
      const response = await axios.post(
        'https://api.stateset.network/v1/order/pay',
        {
          order_id: orderId,
          payment_method: {
            type: 'ssusd',
            wallet_address: walletAddress,
            amount: {
              value: amount,
              denom: 'ssusd'
            },
            chain: 'stateset'
          },
          metadata: {
            memo: `Payment for Order #${orderId}`,
            idempotency_key: `pay_order_${orderId}_${Date.now()}`
          }
        },
        {
          headers: {
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
          }
        }
      );

      console.log('Payment successful:', response.data);
      return response.data;
    } catch (error) {
      console.error('Payment failed:', error.response?.data || error.message);
      throw error;
    }
  }

  // Example with payment splits
  async function payOrderWithSplits(orderId, totalAmount, customerWallet, splits) {
    try {
      const response = await axios.post(
        'https://api.stateset.network/v1/order/pay',
        {
          order_id: orderId,
          payment_method: {
            type: 'ssusd',
            wallet_address: customerWallet,
            amount: {
              value: totalAmount,
              denom: 'ssusd'
            }
          },
          split_payments: splits,
          metadata: {
            memo: `Split payment for Order #${orderId}`,
            idempotency_key: `pay_order_${orderId}_${Date.now()}`
          }
        },
        {
          headers: {
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
          }
        }
      );

      return response.data;
    } catch (error) {
      console.error('Split payment failed:', error.response?.data || error.message);
      throw error;
    }
  }
  ```

  ```python Python theme={null}
  import requests

  def pay_order_with_ssusd(order_id, amount, wallet_address):
      """Pay for an order using ssUSD stablecoin"""
      url = "https://api.stateset.network/v1/order/pay"
      
      headers = {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      }
      
      payload = {
          "order_id": order_id,
          "payment_method": {
              "type": "ssusd",
              "wallet_address": wallet_address,
              "amount": {
                  "value": str(amount),
                  "denom": "ssusd"
              },
              "chain": "stateset"
          },
          "metadata": {
              "memo": f"Payment for Order #{order_id}",
              "idempotency_key": f"pay_order_{order_id}_{int(time.time())}"
          }
      }
      
      try:
          response = requests.post(url, json=payload, headers=headers)
          response.raise_for_status()
          
          result = response.json()
          print(f"Payment successful! Transaction: {result['transaction']['tx_hash']}")
          return result
      except requests.exceptions.RequestException as e:
          print(f"Payment failed: {e}")
          if hasattr(e, 'response') and e.response:
              print(f"Error details: {e.response.json()}")
          raise

  # Example with payment splits
  def pay_order_with_splits(order_id, total_amount, customer_wallet, merchant_wallet, platform_fee_percent=10):
      """Pay for an order with automatic platform fee split"""
      
      platform_fee = total_amount * (platform_fee_percent / 100)
      merchant_amount = total_amount - platform_fee
      
      url = "https://api.stateset.network/v1/order/pay"
      
      headers = {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      }
      
      payload = {
          "order_id": order_id,
          "payment_method": {
              "type": "ssusd",
              "wallet_address": customer_wallet,
              "amount": {
                  "value": f"{total_amount:.2f}",
                  "denom": "ssusd"
              }
          },
          "split_payments": [
              {
                  "recipient": merchant_wallet,
                  "amount": f"{merchant_amount:.2f}",
                  "type": "merchant"
              },
              {
                  "recipient": "stateset1platformfeeaddress",
                  "amount": f"{platform_fee:.2f}",
                  "type": "platform_fee"
              }
          ],
          "metadata": {
              "memo": f"Split payment for Order #{order_id}",
              "idempotency_key": f"pay_order_{order_id}_{int(time.time())}"
          }
      }
      
      try:
          response = requests.post(url, json=payload, headers=headers)
          response.raise_for_status()
          return response.json()
      except requests.exceptions.RequestException as e:
          print(f"Split payment failed: {e}")
          raise
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

### 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)