Pay Invoice

Pay an invoice using ssUSD stablecoin on the StateSet Commerce Network

Overview

This endpoint processes ssUSD (StateSet USD) stablecoin payments for invoices. Supports instant settlement, partial payments, and automated reconciliation.

Body

invoice_id · string · required

The unique identifier of the invoice to be paid

payment_method · object · required

Payment method details

Show properties

type · string · required

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

wallet_address · string · required

The payer’s wallet address

amount · object · required

Payment amount

Show properties

value · string · required

Amount to pay (can be partial payment)

denom · string · required

Denomination: “ssusd” or “usdc” (legacy)

chain · string

Blockchain for payment: “stateset” (default), “base”, “solana”, “cosmos”

payment_details · object

Additional payment details

Show properties

full_payment · boolean

Whether this is intended as full payment (true) or partial (false)

early_payment_discount · boolean

Apply early payment discount if eligible

reference · string

Payment reference number

metadata · object

Additional metadata

Show properties

memo · string

Payment memo

idempotency_key · string

Unique key to prevent duplicate payments

accounting_code · string

Accounting code for reconciliation

Response

success · boolean

Whether the payment was successful

transaction · object

Blockchain transaction details

Show properties

tx_hash · string

Transaction hash

block_height · number

Block height

timestamp · string

Transaction timestamp

gas_used · string

Gas consumed

payment · object

Payment details

Show properties

payment_id · string

Unique payment identifier

invoice_id · string

Invoice that was paid

amount_paid · object

Amount paid in this transaction

discount_applied · object

Any discounts applied

status · string

Payment status

invoice · object

Updated invoice details

Show properties

invoice_id · string

Invoice identifier

status · string

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

total_amount · object

Total invoice amount

amount_paid · object

Total amount paid to date

balance_due · object

Remaining balance

payments · array

List of all payments made

cURL

curl --location --request POST 'https://api.stateset.network/v1/invoice/pay' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "invoice_id": "inv_1234567890",
  "payment_method": {
    "type": "ssusd",
    "wallet_address": "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
    "amount": {
      "value": "5000.00",
      "denom": "ssusd"
    },
    "chain": "stateset"
  },
  "payment_details": {
    "full_payment": true,
    "early_payment_discount": true,
    "reference": "PMT-2024-001"
  },
  "metadata": {
    "memo": "Invoice payment for January services",
    "idempotency_key": "pay_inv_1234567890_001",
    "accounting_code": "REV-001"
  }
}'

Full Payment Response

{
  "success": true,
  "transaction": {
    "tx_hash": "E8F1B4C7D0A3E6F9C2B5E8F1D4C7A0B3E6F9C2B5",
    "block_height": 1234568,
    "timestamp": "2024-01-15T11:00:00Z",
    "gas_used": "80000"
  },
  "payment": {
    "payment_id": "pmt_abc123def456",
    "invoice_id": "inv_1234567890",
    "amount_paid": {
      "value": "4750.00",
      "denom": "ssusd",
      "usd_value": "4750.00"
    },
    "discount_applied": {
      "type": "early_payment",
      "amount": "250.00",
      "percentage": "5.0"
    },
    "status": "completed"
  },
  "invoice": {
    "invoice_id": "inv_1234567890",
    "status": "paid",
    "total_amount": {
      "value": "5000.00",
      "denom": "ssusd"
    },
    "amount_paid": {
      "value": "4750.00",
      "denom": "ssusd"
    },
    "balance_due": {
      "value": "0.00",
      "denom": "ssusd"
    },
    "payments": [
      {
        "payment_id": "pmt_abc123def456",
        "amount": "4750.00",
        "paid_at": "2024-01-15T11:00:00Z",
        "discount": "250.00"
      }
    ]
  }
}