Account · Social Matter Payments API

GET /v1/account

The merchant this key belongs to, its limits, and the ACH company payers' banks see

Secret key

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

ach_company is the company name and ID every debit carries, null until SMP's sponsor bank assigns them. A business payer whose bank blocks debits from companies it doesn't recognise approves that ID with their bank before paying.

Responses

Status	Meaning
`200`	The account
`401`	Error — error shape and codes

Fields of `data` (200)

Field Notes

objectstring = "account" —

merchant_idstring —

namestring —

statusstring —

environmentstring —

statement_descriptorstring As payers' statements show it

limitsobject

3 child fields

`per_transaction_cents`integer	—
`daily_cents`integer	—
`monthly_cents`integer	—

ach_companyobject | null

The ACH company name and ID on every debit; null until the sponsor bank assigns them

2 child fields

`name`string	up to 16 characters
`id`string	pattern `^[A-Za-z0-9]{10}$`

limits_in_forceobject

What a payment is checked against now: the per-payment and daily limits halved (rounded down) while the return rate is critical or worse, or a small merchant is on step 2 or 3; the monthly limit is never halved

3 child fields

`per_transaction_cents`integer	—
`daily_cents`integer	—
`monthly_cents`integer	—

limits_halved_becauseobject | null

Why the limits are halved; null when they are not

3 child fields

`kind`string = "return_step"	—
`level`enum	one of `critical`, `breach`
`step`enum	one of `2`, `3`

Example

The account this key belongs to

GET /v1/account

curl https://sandbox.socialmatterspay.com/v1/account \
  -H 'Authorization: Bearer sk_sandbox_…'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "account",
    "merchant_id": "a5fc4446-e0a0-4260-ac10-e06060393364",
    "name": "Northwind Supply",
    "status": "active",
    "environment": "sandbox",
    "statement_descriptor": "SMS*NORTHWIND",
    "limits": {
      "per_transaction_cents": 300000,
      "daily_cents": 5000000,
      "monthly_cents": 50000000
    },
    "limits_in_force": {
      "per_transaction_cents": 300000,
      "daily_cents": 5000000,
      "monthly_cents": 50000000
    },
    "limits_halved_because": null,
    "ach_company": null
  }
}

GET /v1/account/payday-aware-debits

Whether payday-aware timing is on for this account's debit schedules

Secret key

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

Responses

Status	Meaning
`200`	The payday-aware debits switch (`PaydayAwareDebits`)
`404`	Error — error shape and codes

Fields of `data` (200)

Field Notes

objectstring = "payday_aware_debits" —

enabledboolean —

applies_tostring = "debit_schedules" —

max_window_daysobject

3 child fields

`weekly`integer = 3	—
`biweekly`integer = 7	—
`monthly`integer = 10	—

Example

Payday-aware timing (off by default)

GET /v1/account/payday-aware-debits

curl https://sandbox.socialmatterspay.com/v1/account/payday-aware-debits \
  -H 'Authorization: Bearer sk_sandbox_…'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "payday_aware_debits",
    "enabled": false,
    "applies_to": "debit_schedules",
    "max_window_days": {
      "weekly": 3,
      "biweekly": 7,
      "monthly": 10
    }
  }
}

PUT /v1/account/payday-aware-debits

Turn payday-aware timing on or off (off by default)

Secret key

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

On, a debit schedule may carry a payday window (payday_window_days), which goes into the words the payer agrees to; each debit then lands the business day after the payer's payday when one falls inside that window, read from the payer's own bank balance history. Off, every debit goes on its scheduled date. It never touches a one-time payment, a checkout session, an invoice, or Social Matter Payments' fee debits of your own account. Turning it off keeps already-agreed windows unused; turning it on gives windows only to schedules whose payers agreed to one.

Request body

Field	Notes
`enabled` requiredboolean	—

Responses

Status	Meaning
`200`	The payday-aware debits switch (`PaydayAwareDebits`)
`400`	Error — error shape and codes

Fields of `data` (200)

Field Notes

objectstring = "payday_aware_debits" —

enabledboolean —

applies_tostring = "debit_schedules" —

max_window_daysobject

3 child fields

`weekly`integer = 3	—
`biweekly`integer = 7	—
`monthly`integer = 10	—

Example

Turn it on

PUT /v1/account/payday-aware-debits

curl -X PUT https://sandbox.socialmatterspay.com/v1/account/payday-aware-debits \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "enabled": true
}'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "payday_aware_debits",
    "enabled": true,
    "applies_to": "debit_schedules",
    "max_window_days": {
      "weekly": 3,
      "biweekly": 7,
      "monthly": 10
    }
  }
}

GET /v1/limits

Every limit a payment is checked against, what today and this month have used, and what is left

Secret key

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

On the engine's clock (the sandbox clock in the sandbox). Used amounts count payments created since the start of the UTC day or month, declined and voided ones excluded, exactly as the payment check counts them, so a payment of max_payment_cents passes the merchant limits and one cent more does not. A payment above without_balance_read_cents also needs a live balance read from the payer's bank. SMP staff change the merchant limits with the reason on record (PATCH /v1/merchants/{id}/limits); no limit is held anywhere else.

Responses

Status	Meaning
`200`	The limits in force
`401`	Error — error shape and codes

Fields of `data` (200)

Field Notes

objectstring = "limits" —

merchant_idstring —

as_ofstring (date-time) —

per_transaction_centsinteger —

dailyobject

4 child fields

`limit_cents`integer	—
`used_cents`integer	—
`remaining_cents`integer	at least 0
`resets_at`string (date-time)	—

monthlyobject

4 child fields

`limit_cents`integer	—
`used_cents`integer	—
`remaining_cents`integer	at least 0
`resets_at`string (date-time)	—

max_payment_centsinteger The largest payment the merchant limits allow now; 0 while paused. at least 0

without_balance_read_centsinteger Above this a payment needs a live balance read

payer_velocityobject

4 child fields

`per_hour`integer	—
`per_day`integer	—
`daily_cents`integer	—
`window`string	—

merchant_per_minuteinteger —

unauthorized_returnsobject

4 child fields

`rate`number	—
`pause_at_rate`number	SMP pauses the merchant's payments here
`nacha_ceiling_rate`number	—
`paused`boolean	—

in_forceobject

The limits a payment is checked against now; max_payment_cents and what is left today and this month are measured against these

5 child fields

per_transaction_centsinteger —

daily_centsinteger —

monthly_centsinteger —

halvedboolean —

halved_becauseobject | null

Why the limits are halved; null when they are not

3 child fields

`kind`string = "return_step"	—
`level`enum	one of `critical`, `breach`
`step`enum	one of `2`, `3`

Example

Every limit and what is left

GET /v1/limits

curl https://sandbox.socialmatterspay.com/v1/limits \
  -H 'Authorization: Bearer sk_sandbox_…'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "limits",
    "merchant_id": "a5fc4446-e0a0-4260-ac10-e06060393364",
    "as_of": "2026-11-04T03:00:01.855Z",
    "per_transaction_cents": 300000,
    "daily": {
      "limit_cents": 5000000,
      "used_cents": 4900,
      "remaining_cents": 4995100,
      "resets_at": "2026-11-05T00:00:00.000Z"
    },
    "monthly": {
      "limit_cents": 50000000,
      "used_cents": 4900,
      "remaining_cents": 49995100,
      "resets_at": "2026-12-01T00:00:00.000Z"
    },
    "max_payment_cents": 300000,
    "in_force": {
      "per_transaction_cents": 300000,
      "daily_cents": 5000000,
      "monthly_cents": 50000000,
      "halved": false,
      "halved_because": null
    },
    "without_balance_read_cents": 50000,
    "payer_velocity": {
      "per_hour": 3,
      "per_day": 5,
      "daily_cents": 500000,
      "window": "rolling, from each payment attempt"
    },
    "merchant_per_minute": 30,
    "unauthorized_returns": {
      "rate": 0,
      "pause_at_rate": 0.003,
      "nacha_ceiling_rate": 0.005,
      "paused": false
    }
  }
}

The merchant this key belongs to, its limits, and the ACH company payers' banks see

Responses

Fields of data (200)

Whether payday-aware timing is on for this account's debit schedules

Responses

Fields of data (200)

Turn payday-aware timing on or off (off by default)

Request body

Responses

Fields of data (200)

Every limit a payment is checked against, what today and this month have used, and what is left

Responses

Fields of data (200)

Fields of `data` (200)

Fields of `data` (200)

Fields of `data` (200)

Fields of `data` (200)