DRAFTThe sandbox is not live yet. Every example here was returned by the platform's code in a test run on 2026-10-28, priced with example fees: no fee amount in them is an SMP price. Paths and fields can change before launch. Live keys are issued only after our bank program is approved.Sandbox not live yet · examples from a test run on 2026-10-28 · example fees

Reference · 7 operations

Payments

Create, read, void and refund payments. Every create is decided by the risk checks before anything is sent to the bank.

Sandboxhttps://sandbox.socialmatterspay.com
Livehttps://api.socialmatterspay.com
GET /v1/payments

List payments
Secret key

Host https://api.socialmatterspay.com · https://sandbox.socialmatterspay.com

Parameters

FieldNotes
limitquery · integer1 to 100. default 25
offsetquery · integerdefault 0
statusquery · stringone of pending_authorization, authorized, submitted, settled, released, paid_out, declined, returned, voided, refunded
created_afterquery · stringdate-time
created_beforequery · stringdate-time
payer_idquery · string—
external_order_idquery · string—
site_idquery · stringOne site's payments (a site's key always lists only its own)

Responses

StatusMeaning
200A page of payments; pagination.total counts exactly what the filters select

Fields of each item of data (200)

FieldNotes
idstring—
objectstring = "payment"—
statusenumForward only. declined, returned, voided and refunded are terminal. A payment SMP holds for review before any debit (a merchant whose return rates are at the critical level, above $200) is answered 201 and stays pending_authorization until SMP approves it (payment.authorized follows) or declines it (payment.declined). one of pending_authorization, authorized, submitted, settled, released, paid_out, declined, returned, voided, refunded
amount_centsinteger—
fee_centsinteger—
net_centsinteger—
refunded_centsinteger—
currencystring = "USD"—
entry_codestring—
payer_idstring—
bank_account_idstring—
statement_descriptorstring—
external_order_idstring | null—
metadataobject | nullYour own keys and values, as you sent them; null when there are none. A payment a checkout session made also carries checkout_session_id, and one a debit schedule made carries debit_schedule_id and debit_sequence. at most 20 keys
risk_scoreinteger | null—
decline_reasonenumA fixed code on a declined payment; the risk engine's reasons (the payer's balance, history, identity) are never sent. one of insufficient_funds, balance_unavailable, merchant_limit_exceeded, merchant_return_rate_limit, velocity_limit, bank_rejected, risk_declined,
decline_messagestring | nullThe fixed sentence for decline_reason
bank_referencestring | null—
payout_idstring | null—
return_idstring | null—
override_idstring | nullThe payer override that let it through
site_idstring | nullThe merchant's site the payment belongs to
release_afterstring | null (date-time)—
created_atstring (date-time)—
submitted_atstring | null (date-time)—
settled_atstring | null (date-time)—
released_atstring | null (date-time)—
paid_out_atstring | null (date-time)—

Lists also return pagination: total, limit, offset, has_more.

Example

List payments

GET /v1/payments
curl https://sandbox.socialmatterspay.com/v1/payments?limit=2 \
  -H 'Authorization: Bearer sk_sandbox_…'
Response · 200
HTTP 200
Cache-Control: no-store

{
  "data": [
    {
      "id": "9089e75d-cad0-4ed0-9cdb-166fad3ecfd9",
      "object": "payment",
      "status": "voided",
      "amount_cents": 2500,
      "fee_cents": 50,
      "net_cents": 2450,
      "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_10484",
      "metadata": null,
      "risk_score": 65,
      "decline_reason": null,
      "decline_message": null,
      "bank_reference": "sbt_b2ea95cb-8176-4bf1-b37b-18e113847039",
      "payout_id": null,
      "return_id": null,
      "override_id": null,
      "site_id": null,
      "release_after": null,
      "created_at": "2026-10-28T00:22:35.545Z",
      "submitted_at": "2026-10-28T00:22:35.545Z",
      "settled_at": null,
      "released_at": null,
      "paid_out_at": null
    },
    {
      "id": "482e84e1-2393-4048-bde9-465edf0a38d1",
      "object": "payment",
      "status": "declined",
      "amount_cents": 8400,
      "fee_cents": 109,
      "net_cents": 8291,
      "refunded_cents": 0,
      "currency": "USD",
      "entry_code": "WEB",
      "payer_id": "500d25bc-a844-4e3c-a460-04e971508a0b",
      "bank_account_id": "33746dac-4666-4b2a-9c31-6d3ce13afdc5",
      "statement_descriptor": "NORTHWIND",
      "external_order_id": "order_10483",
      "metadata": null,
      "risk_score": 0,
      "decline_reason": "insufficient_funds",
      "decline_message": "The bank account does not have enough available to cover this payment.",
      "bank_reference": null,
      "payout_id": null,
      "return_id": null,
      "override_id": null,
      "site_id": null,
      "release_after": null,
      "created_at": "2026-10-28T00:22:35.538Z",
      "submitted_at": null,
      "settled_at": null,
      "released_at": null,
      "paid_out_at": null
    }
  ],
  "pagination": {
    "total": 3,
    "limit": 2,
    "offset": 0,
    "has_more": true
  }
}
POST /v1/payments

Authorize, then debit the payer's bank account
Secret key Idempotency-Key required

Host https://api.socialmatterspay.com · https://sandbox.socialmatterspay.com

Risk is decided before any bank call: per-payment, daily and monthly limits, payer and merchant velocity (3 payments per payer per hour, 5 per day, $5,000 per payer per day, 30 per merchant per minute), the payer's live balance where a source exists, and the merchant's return rates. A declined payment is returned with status declined and is never sent to the bank. A payer override (POST /v1/payers/{id}/override) can let a payer past the soft checks, never a limit. A bank account that can no longer be debited (the payer revoked access, or a tokenized number's consent ended) is refused with 422 relink_required before anything is stored: ask the payer to link their bank again. The same Idempotency-Key with the same body returns the same payment (200); with a different body it is a 409.

Nacha WEB and TEL: before the payer agrees, show them the words from POST /v1/payments/authorization-text word for word, then send authorization_text_sha256 — the SHA-256 of exactly what was shown. A WEB or TEL payment without it is refused with 422 authorization_required; one whose hash doesn't match the words the engine generates for this merchant, amount and account is refused with 422 authorization_mismatch. Both refusals happen before anything is stored or sent to the bank. PPD and CCD may send the hash; if sent, it must match. The words and the hash are kept with the payment's authorization record for two years.

Parameters

FieldNotes
Idempotency-Key requiredheader · string1–255 characters. printable characters, no spaces; see Idempotency

Request body

FieldNotes
bank_account_id requiredstring—
amount_cents requiredinteger1 to 99999999
payer_idstringOptional; must own bank_account_id
entry_codeenumone of WEB, PPD, CCD, TEL. default "WEB"
statement_descriptorstringAppears as SMS*<descriptor>. pattern ^[A-Za-z0-9 .&-]{1,12}$
external_order_idstringup to 255 characters
metadataobjectat most 20 keys
payer_ipstringRequired for WEB — the payer's IP at checkout
payer_user_agentstringRequired for WEB — the payer's browser at checkout
authorized_atstring (date-time)—
authorization_text_sha256stringRequired for WEB and TEL. SHA-256 (lowercase hex) of the authorization words from POST /v1/payments/authorization-text exactly as shown to the payer before they agreed. . pattern ^[0-9a-f]{64}$
site_idstringThe site the payment belongs to (a site's key sets its own). Its descriptor applies unless one is given here.

Responses

StatusMeaning
200Payment (Payment)
201Payment (Payment)
400Error — error shape and codes
403Error — error shape and codes
404Error — error shape and codes
409Error — error shape and codes
422Error — error shape and codes
502Error — error shape and codes

Fields of data (200)

The same fields as under listPayments.

Examples (5)

Create a payment

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"
}'
Response · 201
HTTP 201
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
  }
}

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"
}'
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"
}'
Response · 409
HTTP 409
Cache-Control: no-store

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

Declined before any debit (balance below the amount)

POST /v1/payments
curl -X POST https://sandbox.socialmatterspay.com/v1/payments \
  -H 'Idempotency-Key: order_10483' \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "bank_account_id": "33746dac-4666-4b2a-9c31-6d3ce13afdc5",
  "amount_cents": 8400,
  "payer_id": "500d25bc-a844-4e3c-a460-04e971508a0b",
  "entry_code": "WEB",
  "external_order_id": "order_10483",
  "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",
  "authorization_text_sha256": "85916f0096d185117093d29466e05b4a3a9baca8e4fc5b4bcfd467f691f035dc"
}'
Response · 201
HTTP 201
Cache-Control: no-store

{
  "data": {
    "id": "482e84e1-2393-4048-bde9-465edf0a38d1",
    "object": "payment",
    "status": "declined",
    "amount_cents": 8400,
    "fee_cents": 109,
    "net_cents": 8291,
    "refunded_cents": 0,
    "currency": "USD",
    "entry_code": "WEB",
    "payer_id": "500d25bc-a844-4e3c-a460-04e971508a0b",
    "bank_account_id": "33746dac-4666-4b2a-9c31-6d3ce13afdc5",
    "statement_descriptor": "NORTHWIND",
    "external_order_id": "order_10483",
    "metadata": null,
    "risk_score": 0,
    "decline_reason": "insufficient_funds",
    "decline_message": "The bank account does not have enough available to cover this payment.",
    "bank_reference": null,
    "payout_id": null,
    "return_id": null,
    "override_id": null,
    "site_id": null,
    "release_after": null,
    "created_at": "2026-10-28T00:22:35.538Z",
    "submitted_at": null,
    "settled_at": null,
    "released_at": null,
    "paid_out_at": null
  }
}

Held for SMP's review before any debit

POST /v1/payments
curl -X POST https://sandbox.socialmatterspay.com/v1/payments \
  -H 'Idempotency-Key: br_large_1' \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "bank_account_id": "d522acb4-6ec5-4de4-9340-823b804b52c2",
  "payer_id": "5c34e8d3-e684-4e7a-88e3-fd7fc776b76f",
  "amount_cents": 25000,
  "entry_code": "WEB",
  "payer_ip": "203.0.113.9",
  "payer_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6) AppleWebKit/605.1.15 Safari/605.1.15",
  "external_order_id": "br_large_1",
  "authorization_text_sha256": "c6831910343100ea15fd4bc7c8b4af71359084d1bd712e5af6d7948ab7eb0ab4"
}'
Response · 201
HTTP 201
Cache-Control: no-store

{
  "data": {
    "id": "d5a21798-650d-402e-86c0-7a910c0fbcbe",
    "object": "payment",
    "status": "pending_authorization",
    "amount_cents": 25000,
    "fee_cents": 275,
    "net_cents": 24725,
    "refunded_cents": 0,
    "currency": "USD",
    "entry_code": "WEB",
    "payer_id": "5c34e8d3-e684-4e7a-88e3-fd7fc776b76f",
    "bank_account_id": "d522acb4-6ec5-4de4-9340-823b804b52c2",
    "statement_descriptor": "BRAMBLE",
    "external_order_id": "br_large_1",
    "metadata": null,
    "risk_score": 65,
    "decline_reason": null,
    "decline_message": null,
    "bank_reference": null,
    "payout_id": null,
    "return_id": null,
    "override_id": null,
    "site_id": null,
    "release_after": null,
    "created_at": "2026-10-28T00:27:42.510Z",
    "submitted_at": null,
    "settled_at": null,
    "released_at": null,
    "paid_out_at": null
  }
}
POST /v1/payments/authorization-text

The exact authorization words to show the payer before a debit
Secret key

Host https://api.socialmatterspay.com · https://sandbox.socialmatterspay.com

Show text to the payer word for word — in readable type, next to the button they press to pay, never behind a link or collapsed — then send text_sha256 (or your own SHA-256 of exactly what you showed) as authorization_text_sha256 with POST /v1/payments. The words depend on the merchant's name, the amount, the account's last four digits and the ACH company, so fetch them again if any of those change. Also answers for an account still waiting on its micro-deposits, so the deposit form can show the words before the payer confirms.

Request body

FieldNotes
bank_account_id requiredstring—
amount_cents requiredinteger1 to 99999999
entry_codeenumone of WEB, PPD, CCD, TEL. default "WEB"

Responses

StatusMeaning
200The words and their SHA-256
400Error — error shape and codes
403Error — error shape and codes
404Error — error shape and codes
422Error — error shape and codes

Fields of data (200)

FieldNotes
objectstring = "payment_authorization_text"—
textstringShow word for word before the payer agrees
text_sha256stringpattern ^[0-9a-f]{64}$
merchant_namestring—
amount_centsinteger—
amount_descriptionstring—
entry_codeenumone of WEB, PPD, CCD, TEL
frequencystring = "single"—
bank_accountobject
3 child fields
idstring—
bank_namestring—
last_fourstring—
ach_companyobject | null
2 child fields
namestring—
idstring—
Example

The words to show the payer

POST /v1/payments/authorization-text
curl -X POST https://sandbox.socialmatterspay.com/v1/payments/authorization-text \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "bank_account_id": "1357923a-53e2-4aa9-a547-a20155759d6c",
  "amount_cents": 8400,
  "entry_code": "WEB"
}'
Response · 200
HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "payment_authorization_text",
    "text": "By completing this payment, you authorize Northwind Supply to initiate a one-time electronic debit of $84.00 from your bank account ending in 9606. You may revoke this authorization at any time by contacting Northwind Supply, with the understanding that it may take up to 3 business days to process.",
    "text_sha256": "85916f0096d185117093d29466e05b4a3a9baca8e4fc5b4bcfd467f691f035dc",
    "merchant_name": "Northwind Supply",
    "amount_cents": 8400,
    "amount_description": "$84.00",
    "entry_code": "WEB",
    "frequency": "single",
    "bank_account": {
      "id": "1357923a-53e2-4aa9-a547-a20155759d6c",
      "bank_name": "Plaid Checking (sandbox)",
      "last_four": "9606"
    },
    "ach_company": null
  }
}
GET /v1/payments/{id}

Get a payment
Secret key

Host https://api.socialmatterspay.com · https://sandbox.socialmatterspay.com

Parameters

FieldNotes
id requiredpath · string—

Responses

StatusMeaning
200Payment (Payment)
404Error — error shape and codes

Fields of data (200)

The same fields as under listPayments.

Example

Get a payment

GET /v1/payments/3c8029c9-00de-481f-aff2-4e80839dea08
curl https://sandbox.socialmatterspay.com/v1/payments/3c8029c9-00de-481f-aff2-4e80839dea08 \
  -H 'Authorization: Bearer sk_sandbox_…'
Response · 200
HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "3c8029c9-00de-481f-aff2-4e80839dea08",
    "object": "payment",
    "status": "released",
    "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": "2026-10-28T00:23:35.518Z",
    "created_at": "2026-10-28T00:22:35.514Z",
    "submitted_at": "2026-10-28T00:22:35.514Z",
    "settled_at": "2026-10-28T00:23:35.518Z",
    "released_at": "2026-10-28T00:23:36.559Z",
    "paid_out_at": null
  }
}
GET /v1/payments/{id}/history

Every status the payment has reached, in order
Secret key

Host https://api.socialmatterspay.com · https://sandbox.socialmatterspay.com

Parameters

FieldNotes
id requiredpath · string—

Responses

StatusMeaning
200Status history
404Error — error shape and codes

Fields of each item of data (200)

FieldNotes
from_statusstring | null—
to_statusenumForward only. declined, returned, voided and refunded are terminal. A payment SMP holds for review before any debit (a merchant whose return rates are at the critical level, above $200) is answered 201 and stays pending_authorization until SMP approves it (payment.authorized follows) or declines it (payment.declined). one of pending_authorization, authorized, submitted, settled, released, paid_out, declined, returned, voided, refunded
created_atstring (date-time)—
Example

A payment's status changes

GET /v1/payments/3c8029c9-00de-481f-aff2-4e80839dea08/history
curl https://sandbox.socialmatterspay.com/v1/payments/3c8029c9-00de-481f-aff2-4e80839dea08/history \
  -H 'Authorization: Bearer sk_sandbox_…'
Response · 200
HTTP 200
Cache-Control: no-store

{
  "data": [
    {
      "from_status": null,
      "to_status": "pending_authorization",
      "created_at": "2026-10-28T00:22:35.514Z"
    },
    {
      "from_status": "pending_authorization",
      "to_status": "authorized",
      "created_at": "2026-10-28T00:22:35.514Z"
    },
    … 3 more
  ]
}
POST /v1/payments/{id}/void

Void a payment before it settles
Secret key

Host https://api.socialmatterspay.com · https://sandbox.socialmatterspay.com

A submitted debit is cancelled at the bank if it has not settled (409 too_late_to_void if it has).

Parameters

FieldNotes
id requiredpath · string—

Responses

StatusMeaning
200Payment (Payment)
404Error — error shape and codes
409Error — error shape and codes
422Error — error shape and codes

Fields of data (200)

The same fields as under listPayments.

Example

Void before settlement

POST /v1/payments/9089e75d-cad0-4ed0-9cdb-166fad3ecfd9/void
curl -X POST https://sandbox.socialmatterspay.com/v1/payments/9089e75d-cad0-4ed0-9cdb-166fad3ecfd9/void \
  -H 'Authorization: Bearer sk_sandbox_…'
Response · 200
HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "9089e75d-cad0-4ed0-9cdb-166fad3ecfd9",
    "object": "payment",
    "status": "voided",
    "amount_cents": 2500,
    "fee_cents": 50,
    "net_cents": 2450,
    "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_10484",
    "metadata": null,
    "risk_score": 65,
    "decline_reason": null,
    "decline_message": null,
    "bank_reference": "sbt_b2ea95cb-8176-4bf1-b37b-18e113847039",
    "payout_id": null,
    "return_id": null,
    "override_id": null,
    "site_id": null,
    "release_after": null,
    "created_at": "2026-10-28T00:22:35.545Z",
    "submitted_at": "2026-10-28T00:22:35.545Z",
    "settled_at": null,
    "released_at": null,
    "paid_out_at": null
  }
}
POST /v1/payments/{id}/refund

Refund a settled payment, in full or in part
Secret key Idempotency-Key required

Host https://api.socialmatterspay.com · https://sandbox.socialmatterspay.com

Parameters

FieldNotes
id requiredpath · string—
Idempotency-Key requiredheader · string1–255 characters. printable characters, no spaces; see Idempotency

Request body

FieldNotes
amount_centsintegerDefaults to what remains refundable. at least 1
reasonstringup to 500 characters

Responses

StatusMeaning
200Refund (Refund)
201Refund (Refund)
404Error — error shape and codes
409Error — error shape and codes
422Error — error shape and codes
502Error — error shape and codes

Fields of data (200)

FieldNotes
idstring—
objectstring = "refund"—
payment_idstring—
amount_centsinteger—
reasonstring | null—
statusenumone of pending, submitted, settled, failed
failure_reasonstring | null—
created_atstring (date-time)—
settled_atstring | null (date-time)—
Example

Refund part of a payment

POST /v1/payments/3c8029c9-00de-481f-aff2-4e80839dea08/refund
curl -X POST https://sandbox.socialmatterspay.com/v1/payments/3c8029c9-00de-481f-aff2-4e80839dea08/refund \
  -H 'Idempotency-Key: refund_order_10482_1' \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount_cents": 1200,
  "reason": "One item out of stock"
}'
Response · 201
HTTP 201
Cache-Control: no-store

{
  "data": {
    "id": "aa7af452-4b99-49a1-9c61-630bccadbb36",
    "object": "refund",
    "payment_id": "3c8029c9-00de-481f-aff2-4e80839dea08",
    "amount_cents": 1200,
    "reason": "One item out of stock",
    "status": "submitted",
    "failure_reason": null,
    "created_at": "2026-10-28T00:23:37.591Z",
    "settled_at": null
  }
}