curl --location --request POST 'https://api.stateset.com/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"
}
}'
const axios = require('axios');
async function payInvoiceWithSSUSD(invoiceId, amount, walletAddress, isFullPayment = true) {
try {
const response = await axios.post(
'https://api.stateset.com/v1/invoice/pay',
{
invoice_id: invoiceId,
payment_method: {
type: 'ssusd',
wallet_address: walletAddress,
amount: {
value: amount,
denom: 'ssusd'
},
chain: 'stateset'
},
payment_details: {
full_payment: isFullPayment,
early_payment_discount: true,
reference: `PMT-${Date.now()}`
},
metadata: {
memo: `Payment for invoice ${invoiceId}`,
idempotency_key: `pay_inv_${invoiceId}_${Date.now()}`
}
},
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
}
);
console.log('Invoice payment successful:', response.data);
// Check if invoice is fully paid
if (response.data.invoice.status === 'paid') {
console.log('Invoice fully paid!');
} else if (response.data.invoice.status === 'partially_paid') {
console.log(`Partial payment applied. Balance due: ${response.data.invoice.balance_due.value} ${response.data.invoice.balance_due.denom}`);
}
return response.data;
} catch (error) {
console.error('Invoice payment failed:', error.response?.data || error.message);
throw error;
}
}
// Example: Partial payment
async function makePartialPayment(invoiceId, partialAmount, walletAddress) {
return payInvoiceWithSSUSD(invoiceId, partialAmount, walletAddress, false);
}
import requests
from datetime import datetime
def pay_invoice_with_ssusd(invoice_id, amount, wallet_address, full_payment=True):
"""Pay an invoice using ssUSD stablecoin"""
url = "https://api.stateset.com/v1/invoice/pay"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
payload = {
"invoice_id": invoice_id,
"payment_method": {
"type": "ssusd",
"wallet_address": wallet_address,
"amount": {
"value": str(amount),
"denom": "ssusd"
},
"chain": "stateset"
},
"payment_details": {
"full_payment": full_payment,
"early_payment_discount": True,
"reference": f"PMT-{datetime.now().strftime('%Y%m%d%H%M%S')}"
},
"metadata": {
"memo": f"Payment for invoice {invoice_id}",
"idempotency_key": f"pay_inv_{invoice_id}_{int(datetime.now().timestamp())}"
}
}
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']}")
# Check payment status
invoice_status = result['invoice']['status']
if invoice_status == 'paid':
print("Invoice fully paid!")
elif invoice_status == 'partially_paid':
balance = result['invoice']['balance_due']
print(f"Partial payment applied. Balance due: {balance['value']} {balance['denom']}")
return result
except requests.exceptions.RequestException as e:
print(f"Invoice payment failed: {e}")
if hasattr(e, 'response') and e.response:
print(f"Error details: {e.response.json()}")
raise
# Example: Apply early payment discount
def pay_invoice_with_discount(invoice_id, wallet_address):
"""Pay invoice in full to get early payment discount"""
# First, get invoice details to see discount terms
# Then pay the discounted amount
return pay_invoice_with_ssusd(
invoice_id=invoice_id,
amount="4750.00", # Example: 5% discount on $5000
wallet_address=wallet_address,
full_payment=True
)
{
"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"
}
]
}
}
{
"success": true,
"transaction": {
"tx_hash": "F9G2C5D8E1B4F7A0D3F6G9C2E5B8F1D4",
"block_height": 1234569,
"timestamp": "2024-01-15T11:05:00Z",
"gas_used": "75000"
},
"payment": {
"payment_id": "pmt_xyz789uvw012",
"invoice_id": "inv_1234567890",
"amount_paid": {
"value": "2000.00",
"denom": "ssusd",
"usd_value": "2000.00"
},
"discount_applied": null,
"status": "completed"
},
"invoice": {
"invoice_id": "inv_1234567890",
"status": "partially_paid",
"total_amount": {
"value": "5000.00",
"denom": "ssusd"
},
"amount_paid": {
"value": "2000.00",
"denom": "ssusd"
},
"balance_due": {
"value": "3000.00",
"denom": "ssusd"
},
"payments": [
{
"payment_id": "pmt_xyz789uvw012",
"amount": "2000.00",
"paid_at": "2024-01-15T11:05:00Z",
"discount": "0.00"
}
]
}
}
Pay Invoice
Pay an invoice using ssUSD stablecoin on the StateSet Commerce Network
POST
/
v1
/
invoice
/
pay
curl --location --request POST 'https://api.stateset.com/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"
}
}'
const axios = require('axios');
async function payInvoiceWithSSUSD(invoiceId, amount, walletAddress, isFullPayment = true) {
try {
const response = await axios.post(
'https://api.stateset.com/v1/invoice/pay',
{
invoice_id: invoiceId,
payment_method: {
type: 'ssusd',
wallet_address: walletAddress,
amount: {
value: amount,
denom: 'ssusd'
},
chain: 'stateset'
},
payment_details: {
full_payment: isFullPayment,
early_payment_discount: true,
reference: `PMT-${Date.now()}`
},
metadata: {
memo: `Payment for invoice ${invoiceId}`,
idempotency_key: `pay_inv_${invoiceId}_${Date.now()}`
}
},
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
}
);
console.log('Invoice payment successful:', response.data);
// Check if invoice is fully paid
if (response.data.invoice.status === 'paid') {
console.log('Invoice fully paid!');
} else if (response.data.invoice.status === 'partially_paid') {
console.log(`Partial payment applied. Balance due: ${response.data.invoice.balance_due.value} ${response.data.invoice.balance_due.denom}`);
}
return response.data;
} catch (error) {
console.error('Invoice payment failed:', error.response?.data || error.message);
throw error;
}
}
// Example: Partial payment
async function makePartialPayment(invoiceId, partialAmount, walletAddress) {
return payInvoiceWithSSUSD(invoiceId, partialAmount, walletAddress, false);
}
import requests
from datetime import datetime
def pay_invoice_with_ssusd(invoice_id, amount, wallet_address, full_payment=True):
"""Pay an invoice using ssUSD stablecoin"""
url = "https://api.stateset.com/v1/invoice/pay"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
payload = {
"invoice_id": invoice_id,
"payment_method": {
"type": "ssusd",
"wallet_address": wallet_address,
"amount": {
"value": str(amount),
"denom": "ssusd"
},
"chain": "stateset"
},
"payment_details": {
"full_payment": full_payment,
"early_payment_discount": True,
"reference": f"PMT-{datetime.now().strftime('%Y%m%d%H%M%S')}"
},
"metadata": {
"memo": f"Payment for invoice {invoice_id}",
"idempotency_key": f"pay_inv_{invoice_id}_{int(datetime.now().timestamp())}"
}
}
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']}")
# Check payment status
invoice_status = result['invoice']['status']
if invoice_status == 'paid':
print("Invoice fully paid!")
elif invoice_status == 'partially_paid':
balance = result['invoice']['balance_due']
print(f"Partial payment applied. Balance due: {balance['value']} {balance['denom']}")
return result
except requests.exceptions.RequestException as e:
print(f"Invoice payment failed: {e}")
if hasattr(e, 'response') and e.response:
print(f"Error details: {e.response.json()}")
raise
# Example: Apply early payment discount
def pay_invoice_with_discount(invoice_id, wallet_address):
"""Pay invoice in full to get early payment discount"""
# First, get invoice details to see discount terms
# Then pay the discounted amount
return pay_invoice_with_ssusd(
invoice_id=invoice_id,
amount="4750.00", # Example: 5% discount on $5000
wallet_address=wallet_address,
full_payment=True
)
{
"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"
}
]
}
}
{
"success": true,
"transaction": {
"tx_hash": "F9G2C5D8E1B4F7A0D3F6G9C2E5B8F1D4",
"block_height": 1234569,
"timestamp": "2024-01-15T11:05:00Z",
"gas_used": "75000"
},
"payment": {
"payment_id": "pmt_xyz789uvw012",
"invoice_id": "inv_1234567890",
"amount_paid": {
"value": "2000.00",
"denom": "ssusd",
"usd_value": "2000.00"
},
"discount_applied": null,
"status": "completed"
},
"invoice": {
"invoice_id": "inv_1234567890",
"status": "partially_paid",
"total_amount": {
"value": "5000.00",
"denom": "ssusd"
},
"amount_paid": {
"value": "2000.00",
"denom": "ssusd"
},
"balance_due": {
"value": "3000.00",
"denom": "ssusd"
},
"payments": [
{
"payment_id": "pmt_xyz789uvw012",
"amount": "2000.00",
"paid_at": "2024-01-15T11:05:00Z",
"discount": "0.00"
}
]
}
}
Legacy contract: confirm deployment before use. This page does not establish a
provisioned public service. Check the dated host report and obtain
a supported host and API version. New integrations should begin with the
API directory or local commerce walkthrough.
Overview
This endpoint processes ssUSD (StateSet USD) stablecoin payments for invoices. Supports instant settlement, partial payments, and automated reconciliation.Body
string
required
The unique identifier of the invoice to be paid
object
required
Payment method details
Show properties
Show properties
string
required
Payment type. Supported values: “ssusd”, “usdc” (legacy)
string
required
The payer’s wallet address
object
required
string
Blockchain for payment: “stateset” (default), “base”, “solana”, “cosmos”
object
object
Response
boolean
Whether the payment was successful
object
object
object
Errors
Succeeds with201. Failures return 400, 401, 403, 422 or 429 with an error body, per the platform status-code contract.
curl --location --request POST 'https://api.stateset.com/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"
}
}'
const axios = require('axios');
async function payInvoiceWithSSUSD(invoiceId, amount, walletAddress, isFullPayment = true) {
try {
const response = await axios.post(
'https://api.stateset.com/v1/invoice/pay',
{
invoice_id: invoiceId,
payment_method: {
type: 'ssusd',
wallet_address: walletAddress,
amount: {
value: amount,
denom: 'ssusd'
},
chain: 'stateset'
},
payment_details: {
full_payment: isFullPayment,
early_payment_discount: true,
reference: `PMT-${Date.now()}`
},
metadata: {
memo: `Payment for invoice ${invoiceId}`,
idempotency_key: `pay_inv_${invoiceId}_${Date.now()}`
}
},
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
}
);
console.log('Invoice payment successful:', response.data);
// Check if invoice is fully paid
if (response.data.invoice.status === 'paid') {
console.log('Invoice fully paid!');
} else if (response.data.invoice.status === 'partially_paid') {
console.log(`Partial payment applied. Balance due: ${response.data.invoice.balance_due.value} ${response.data.invoice.balance_due.denom}`);
}
return response.data;
} catch (error) {
console.error('Invoice payment failed:', error.response?.data || error.message);
throw error;
}
}
// Example: Partial payment
async function makePartialPayment(invoiceId, partialAmount, walletAddress) {
return payInvoiceWithSSUSD(invoiceId, partialAmount, walletAddress, false);
}
import requests
from datetime import datetime
def pay_invoice_with_ssusd(invoice_id, amount, wallet_address, full_payment=True):
"""Pay an invoice using ssUSD stablecoin"""
url = "https://api.stateset.com/v1/invoice/pay"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
payload = {
"invoice_id": invoice_id,
"payment_method": {
"type": "ssusd",
"wallet_address": wallet_address,
"amount": {
"value": str(amount),
"denom": "ssusd"
},
"chain": "stateset"
},
"payment_details": {
"full_payment": full_payment,
"early_payment_discount": True,
"reference": f"PMT-{datetime.now().strftime('%Y%m%d%H%M%S')}"
},
"metadata": {
"memo": f"Payment for invoice {invoice_id}",
"idempotency_key": f"pay_inv_{invoice_id}_{int(datetime.now().timestamp())}"
}
}
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']}")
# Check payment status
invoice_status = result['invoice']['status']
if invoice_status == 'paid':
print("Invoice fully paid!")
elif invoice_status == 'partially_paid':
balance = result['invoice']['balance_due']
print(f"Partial payment applied. Balance due: {balance['value']} {balance['denom']}")
return result
except requests.exceptions.RequestException as e:
print(f"Invoice payment failed: {e}")
if hasattr(e, 'response') and e.response:
print(f"Error details: {e.response.json()}")
raise
# Example: Apply early payment discount
def pay_invoice_with_discount(invoice_id, wallet_address):
"""Pay invoice in full to get early payment discount"""
# First, get invoice details to see discount terms
# Then pay the discounted amount
return pay_invoice_with_ssusd(
invoice_id=invoice_id,
amount="4750.00", # Example: 5% discount on $5000
wallet_address=wallet_address,
full_payment=True
)
{
"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"
}
]
}
}
{
"success": true,
"transaction": {
"tx_hash": "F9G2C5D8E1B4F7A0D3F6G9C2E5B8F1D4",
"block_height": 1234569,
"timestamp": "2024-01-15T11:05:00Z",
"gas_used": "75000"
},
"payment": {
"payment_id": "pmt_xyz789uvw012",
"invoice_id": "inv_1234567890",
"amount_paid": {
"value": "2000.00",
"denom": "ssusd",
"usd_value": "2000.00"
},
"discount_applied": null,
"status": "completed"
},
"invoice": {
"invoice_id": "inv_1234567890",
"status": "partially_paid",
"total_amount": {
"value": "5000.00",
"denom": "ssusd"
},
"amount_paid": {
"value": "2000.00",
"denom": "ssusd"
},
"balance_due": {
"value": "3000.00",
"denom": "ssusd"
},
"payments": [
{
"payment_id": "pmt_xyz789uvw012",
"amount": "2000.00",
"paid_at": "2024-01-15T11:05:00Z",
"discount": "0.00"
}
]
}
}
Last modified on September 21, 2026