Idempotency · Social Matter Payments API

The rule

Every request that moves money needs an Idempotency-Key header: POST /v1/payments, POST /v1/payments/{id}/refund and POST /v1/payouts/trigger. So does each call that makes something a retry must not make twice: POST /v1/invoices, POST /v1/debit-schedules, POST /v1/payer-imports and POST /v1/checkout-sessions. A key is 1 to 255 printable characters with no spaces.

The same key with the same body returns the same object: the first answer was 201, a repeat is 200, and the bank is called once.
The same key with a different body answers 409 idempotency_conflict and changes nothing.
Keys belong to your merchant account and to one kind of request: a payment key and a refund key never collide.
A key stays attached to the payment, refund or payout it created, so it keeps returning that object.

Use something you already have exactly once per attempt at money moving, such as your order number for a payment. When a request times out or your server restarts mid-call, send it again with the same key.

Both cases, from the sandbox

Retry with the same Idempotency-Key and body

POST /v1/payments

curl -X POST https://sandbox.socialmatterspay.com/v1/payments \
  -H 'Idempotency-Key: order_10482' \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "bank_account_id": "1357923a-53e2-4aa9-a547-a20155759d6c",
  "amount_cents": 8400,
  "payer_id": "6427de75-801c-4ac6-95fa-870665d10af3",
  "entry_code": "WEB",
  "external_order_id": "order_10482",
  "payer_ip": "203.0.113.7",
  "payer_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6) AppleWebKit/605.1.15 Safari/605.1.15",
  "metadata": {
    "cart_id": "c_7731"
  },
  "authorization_text_sha256": "85916f0096d185117093d29466e05b4a3a9baca8e4fc5b4bcfd467f691f035dc"
}'

The response · 200

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "3c8029c9-00de-481f-aff2-4e80839dea08",
    "object": "payment",
    "status": "submitted",
    "amount_cents": 8400,
    "fee_cents": 109,
    "net_cents": 8291,
    "refunded_cents": 0,
    "currency": "USD",
    "entry_code": "WEB",
    "payer_id": "6427de75-801c-4ac6-95fa-870665d10af3",
    "bank_account_id": "1357923a-53e2-4aa9-a547-a20155759d6c",
    "statement_descriptor": "NORTHWIND",
    "external_order_id": "order_10482",
    "metadata": {
      "cart_id": "c_7731"
    },
    "risk_score": 65,
    "decline_reason": null,
    "decline_message": null,
    "bank_reference": "sbt_98eecba8-0048-4a1d-83c0-385f4ac6b04a",
    "payout_id": null,
    "return_id": null,
    "override_id": null,
    "site_id": null,
    "release_after": null,
    "created_at": "2026-10-28T00:22:35.514Z",
    "submitted_at": "2026-10-28T00:22:35.514Z",
    "settled_at": null,
    "released_at": null,
    "paid_out_at": null
  }
}

Same Idempotency-Key, different body

POST /v1/payments

curl -X POST https://sandbox.socialmatterspay.com/v1/payments \
  -H 'Idempotency-Key: order_10482' \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "bank_account_id": "1357923a-53e2-4aa9-a547-a20155759d6c",
  "amount_cents": 9100,
  "payer_id": "6427de75-801c-4ac6-95fa-870665d10af3",
  "entry_code": "WEB",
  "external_order_id": "order_10482",
  "payer_ip": "203.0.113.7",
  "payer_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6) AppleWebKit/605.1.15 Safari/605.1.15",
  "metadata": {
    "cart_id": "c_7731"
  },
  "authorization_text_sha256": "876b3c6aacf1542fc6e905c20d46eb26aff6962d0dbd615d1798f172a609ea44"
}'

The response · 409

Response · 409

HTTP 409
Cache-Control: no-store

{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was used with a different request body"
}