Create Payment

Process a payment for an order or invoice

POST /v1/payments

cURL

curl --location --request POST 'https://api.stateset.com/v1/payments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "amount": 15000,
    "currency": "USD",
    "payment_method": {
        "type": "card",
        "card": {
            "token": "tok_1234567890abcdef"
        }
    },
    "order_id": "order_123456",
    "customer_id": "cust_abc123",
    "description": "Payment for Order #123456",
    "capture": true
}'

Response

{
  "id": "pay_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "object": "payment",
  "amount": 15000,
  "currency": "USD",
  "status": "succeeded",
  "captured": true,
  "created_at": "2024-01-19T15:30:00Z",
  "payment_method": {
    "type": "card",
    "card": {
      "last4": "4242",
      "brand": "visa",
      "exp_month": 12,
      "exp_year": 2025,
      "fingerprint": "Xt5EWLLDS7FJjR1c"
    }
  },
  "order_id": "order_123456",
  "customer_id": "cust_abc123",
  "description": "Payment for Order #123456",
  "receipt_url": "https://receipts.stateset.com/pay_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "processor_response": {
    "approved": true,
    "authorization_code": "123456",
    "avs_result": "Y",
    "cvv_result": "M",
    "network_transaction_id": "123456789"
  }
}

This endpoint processes payments through various payment methods and gateways. It supports credit cards, ACH, wire transfers, and digital wallets.

Authentication

This endpoint requires a valid API key with payments:write permissions.

Authorization: Bearer YOUR_API_KEY

Request Body

amount · integer · required

Payment amount in cents (e.g., 1000 for $10.00)

currency · string · required

ISO 4217 currency code (e.g., “USD”, “EUR”)

payment_method · object · required

Payment method details

Show Payment method properties

type · string · required

Payment type: “card”, “ach”, “wire”, “paypal”, “crypto”

card · object

Credit/debit card details (for type: “card”)

Show Card properties

number · string

Card number (will be tokenized)

exp_month · integer

Expiration month (1-12)

exp_year · integer

Expiration year (4 digits)

cvc · string

Card verification code

token · string

Pre-tokenized card token (alternative to raw card data)

ach · object

ACH bank transfer details (for type: “ach”)

Show ACH properties

account_number · string

Bank account number

routing_number · string

Bank routing number

account_type · string

Account type: “checking” or “savings”

order_id · string

Associated order ID

invoice_id · string

Associated invoice ID

customer_id · string · required

Customer ID making the payment

description · string

Payment description

statement_descriptor · string

Text to appear on customer’s statement (max 22 chars)

capture · boolean

Whether to immediately capture the payment (default: true)

billing_address · object

Billing address for verification

Show Address properties

line1 · string

Street address

line2 · string

Apartment/Suite number

city · string

City

state · string

State/Province code

postal_code · string

Postal/ZIP code

country · string

ISO 3166-1 alpha-2 country code

metadata · object

Additional custom fields

Response

Returns the created payment with processing status.

cURL

curl --location --request POST 'https://api.stateset.com/v1/payments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "amount": 15000,
    "currency": "USD",
    "payment_method": {
        "type": "card",
        "card": {
            "token": "tok_1234567890abcdef"
        }
    },
    "order_id": "order_123456",
    "customer_id": "cust_abc123",
    "description": "Payment for Order #123456",
    "capture": true
}'

Response

{
  "id": "pay_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "object": "payment",
  "amount": 15000,
  "currency": "USD",
  "status": "succeeded",
  "captured": true,
  "created_at": "2024-01-19T15:30:00Z",
  "payment_method": {
    "type": "card",
    "card": {
      "last4": "4242",
      "brand": "visa",
      "exp_month": 12,
      "exp_year": 2025,
      "fingerprint": "Xt5EWLLDS7FJjR1c"
    }
  },
  "order_id": "order_123456",
  "customer_id": "cust_abc123",
  "description": "Payment for Order #123456",
  "receipt_url": "https://receipts.stateset.com/pay_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "processor_response": {
    "approved": true,
    "authorization_code": "123456",
    "avs_result": "Y",
    "cvv_result": "M",
    "network_transaction_id": "123456789"
  }
}