curl --location --request POST 'https://api.stateset.com/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"
}
}'
const axios = require('axios');
async function payOrderWithSSUSD(orderId, amount, walletAddress) {
try {
const response = await axios.post(
'https://api.stateset.com/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.com/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;
}
}
import requests
def pay_order_with_ssusd(order_id, amount, wallet_address):
"""Pay for an order using ssUSD stablecoin"""
url = "https://api.stateset.com/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.com/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
{
"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"
}
}
Pay Order
Pay for an order using ssUSD on the StateSet Commerce Network
POST
/
v1
/
order
/
pay
curl --location --request POST 'https://api.stateset.com/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"
}
}'
const axios = require('axios');
async function payOrderWithSSUSD(orderId, amount, walletAddress) {
try {
const response = await axios.post(
'https://api.stateset.com/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.com/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;
}
}
import requests
def pay_order_with_ssusd(order_id, amount, wallet_address):
"""Pay for an order using ssUSD stablecoin"""
url = "https://api.stateset.com/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.com/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
{
"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"
}
}
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
string
required
The unique identifier of the order to be paid
object
required
Payment method details for stablecoin payment
Show properties
Show properties
string
required
Payment method type. Supported values: “ssusd”, “usdc” (legacy)
string
required
The customer’s wallet address from which stablecoins will be debited
object
required
string
The blockchain for payment. Options: “stateset” (default), “base”, “solana”, “cosmos”
array
object
Response
boolean
Indicates whether the payment was successful
object
object
Payment details
Show properties
Show properties
string
Unique identifier for the payment
string
The order ID that was paid
object
string
Payment status: “completed”, “pending”, “failed”
array
Payment split details if applicable
object
curl --location --request POST 'https://api.stateset.com/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"
}
}'
const axios = require('axios');
async function payOrderWithSSUSD(orderId, amount, walletAddress) {
try {
const response = await axios.post(
'https://api.stateset.com/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.com/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;
}
}
import requests
def pay_order_with_ssusd(order_id, amount, wallet_address):
"""Pay for an order using ssUSD stablecoin"""
url = "https://api.stateset.com/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.com/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
{
"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)
⌘I