Payouts · Social Matter Payments API

PUT /admin/v1/merchants/{id}/payout-schedule

SMP staff — set when a merchant is paid (the same call as PATCH)

SMP staff token

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

daily (every Fed business day), weekly or biweekly on a weekday, monthly on the 1st, or hold (paid only when the merchant asks, with no fee). A payout day on a weekend or a Fed holiday goes out on the next Fed business day. Effective from the next daily payout run; the before and after are in the audit log. PUT is the same call.

Parameters

Field	Notes
`id` requiredpath · string	—

Request body

Field	Notes
`payout_schedule` requiredenum	one of `daily`, `weekly`, `biweekly`, `monthly`, `hold`
`payout_weekday`integer	Weekly and biweekly only; Tuesday (2) when left out. 1 to 5
`reason` requiredstring	up to 2000 characters
`changed_by`string	The SMP staff member making the change. up to 200 characters
`set_by`string	Accepted in place of changed_by. up to 200 characters

Responses

Status	Meaning
`200`	The schedule now in force
`400`	Error — error shape and codes
`401`	Error — error shape and codes
`404`	Error — error shape and codes

Fields of `data` (200)

Field	Notes
`object`string = "payout_schedule"	—
`merchant_id`string	—
`payout_schedule`string	—
`payout_weekday`integer	—
`payout_day`string	—
`next_payout_date`string \| null (date)	—

Example

Put a merchant on the Hold schedule (SMP staff)

PUT /admin/v1/merchants/a5fc4446-e0a0-4260-ac10-e06060393364/payout-schedule

curl -X PUT https://sandbox.socialmatterspay.com/admin/v1/merchants/a5fc4446-e0a0-4260-ac10-e06060393364/payout-schedule \
  -H 'Authorization: Bearer smp_staff_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "payout_schedule": "hold",
  "reason": "The merchant asked to be paid only on request",
  "changed_by": "operations"
}'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "payout_schedule",
    "merchant_id": "a5fc4446-e0a0-4260-ac10-e06060393364",
    "payout_schedule": "hold",
    "payout_weekday": 2,
    "payout_day": "only when you ask (no fee)",
    "next_payout_date": null
  }
}

PATCH /admin/v1/merchants/{id}/payout-schedule

SMP staff — set when a merchant is paid, with the reason on record

SMP staff token

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

Parameters

Field	Notes
`id` requiredpath · string	—

Request body

Field	Notes
`payout_schedule` requiredenum	one of `daily`, `weekly`, `biweekly`, `monthly`, `hold`
`payout_weekday`integer	Weekly and biweekly only; Tuesday (2) when left out. 1 to 5
`reason` requiredstring	up to 2000 characters
`changed_by`string	The SMP staff member making the change. up to 200 characters
`set_by`string	Accepted in place of changed_by. up to 200 characters

Responses

Status	Meaning
`200`	The schedule now in force
`400`	Error — error shape and codes
`401`	Error — error shape and codes
`404`	Error — error shape and codes

Fields of `data` (200)

Field	Notes
`object`string = "payout_schedule"	—
`merchant_id`string	—
`payout_schedule`string	—
`payout_weekday`integer	—
`payout_day`string	—
`next_payout_date`string \| null (date)	—

Example

Set a merchant's payout schedule (SMP staff)

PATCH /admin/v1/merchants/a5fc4446-e0a0-4260-ac10-e06060393364/payout-schedule

curl -X PATCH https://sandbox.socialmatterspay.com/admin/v1/merchants/a5fc4446-e0a0-4260-ac10-e06060393364/payout-schedule \
  -H 'Authorization: Bearer smp_staff_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "payout_schedule": "weekly",
  "payout_weekday": 4,
  "reason": "The merchant asked for Thursday payouts",
  "changed_by": "operations"
}'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "payout_schedule",
    "merchant_id": "a5fc4446-e0a0-4260-ac10-e06060393364",
    "payout_schedule": "weekly",
    "payout_weekday": 4,
    "payout_day": "Thursday (UTC)",
    "next_payout_date": "2026-11-05"
  }
}

GET /admin/v1/merchants/{id}/early-payouts

SMP staff — whether "Pay me now" is on for a merchant, its fee, and every change with who made it

SMP staff token

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

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`200`	The merchant's early payouts
`401`	Error — error shape and codes
`404`	Error — error shape and codes

Fields of `data` (200)

Field Notes

objectstring = "merchant_early_payouts" —

merchant_idstring —

enabledboolean —

feeobject | null

The payout.instant rule in force for the merchant; null when no such rule is active

6 child fields

`code`string = "payout.instant"	—
`basis`enum	one of `fixed`, `bps`, `bps_plus_fixed`
`bps`integer \| null	Basis points of the payout; null on a fixed rule
`fixed_cents`integer \| null	null on a bps-only rule
`min_cents`integer \| null	—
`max_cents`integer \| null	—

historyarray of object

4 child fields

`enabled`boolean	—
`decided_by`string	—
`reason`string	—
`at`string (date-time)	—

changedboolean —

Example

"Pay me now" for a merchant, with every change (SMP staff)

GET /admin/v1/merchants/a5fc4446-e0a0-4260-ac10-e06060393364/early-payouts

curl https://sandbox.socialmatterspay.com/admin/v1/merchants/a5fc4446-e0a0-4260-ac10-e06060393364/early-payouts \
  -H 'Authorization: Bearer smp_staff_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "merchant_early_payouts",
    "merchant_id": "a5fc4446-e0a0-4260-ac10-e06060393364",
    "enabled": true,
    "fee": {
      "code": "payout.instant",
      "basis": "bps",
      "bps": 100,
      "fixed_cents": null,
      "min_cents": 25,
      "max_cents": null
    },
    "history": [
      {
        "enabled": true,
        "decided_by": "risk-ops",
        "reason": "A steady payment history",
        "at": "2026-10-28T00:24:38.626Z"
      }
    ]
  }
}

PUT /admin/v1/merchants/{id}/early-payouts

SMP staff — turn "Pay me now" on or off for one merchant

SMP staff token

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

Only SMP staff switch it, per merchant. The switch and its record (who, why, when) are written together; the database refuses any other change of the switch. 201 when it changed, 200 when it already was so.

Parameters

Field	Notes
`id` requiredpath · string	—

Request body

Field	Notes
`enabled` requiredboolean	—
`reason` requiredstring	up to 500 characters
`decided_by` requiredstring	up to 200 characters

Responses

Status	Meaning
`200`	Already so; nothing changed
`201`	Changed
`400`	Error — error shape and codes
`401`	Error — error shape and codes
`404`	Error — error shape and codes

Fields of `data` (200)

The same fields as under adminGetMerchantEarlyPayouts.

Example

Turn "Pay me now" on for a merchant (SMP staff)

PUT /admin/v1/merchants/a5fc4446-e0a0-4260-ac10-e06060393364/early-payouts

curl -X PUT https://sandbox.socialmatterspay.com/admin/v1/merchants/a5fc4446-e0a0-4260-ac10-e06060393364/early-payouts \
  -H 'Authorization: Bearer smp_staff_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "enabled": true,
  "reason": "A steady payment history",
  "decided_by": "risk-ops"
}'

Response · 201

HTTP 201
Cache-Control: no-store

{
  "data": {
    "object": "merchant_early_payouts",
    "merchant_id": "a5fc4446-e0a0-4260-ac10-e06060393364",
    "enabled": true,
    "fee": {
      "code": "payout.instant",
      "basis": "bps",
      "bps": 100,
      "fixed_cents": null,
      "min_cents": 25,
      "max_cents": null
    },
    "history": [
      {
        "enabled": true,
        "decided_by": "risk-ops",
        "reason": "A steady payment history",
        "at": "2026-10-28T00:24:38.626Z"
      }
    ],
    "changed": true
  }
}

GET /v1/payouts

List payouts

Secret key

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

Parameters

Field	Notes
`limit`query · integer	1 to 100. default `25`
`offset`query · integer	default `0`
`status`query · string	one of `pending`, `submitted`, `settled`, `failed`, `cancelled`

Responses

Status	Meaning
`200`	A page of payouts

Fields of each item of `data` (200)

Field	Notes
`id`string	—
`object`string = "payout"	—
`status`enum	one of `pending`, `submitted`, `settled`, `failed`, `cancelled`
`amount_cents`integer	—
`fee_cents`integer	—
`net_cents`integer	—
`returns_netted_cents`integer	—
`fees_netted_cents`integer	Fees assessed since the last payout (return fee, monthly fee) that this payout carried
`fees_included`integer	—
`method`enum	one of `ach_credit`, `fednow`, `rtp`
`trigger`enum	one of `manual`, `scheduled`
`payments_included`integer	—
`returns_included`integer	—
`period_start`string (date-time)	—
`period_end`string (date-time)	—
`initiated_at`string (date-time)	—
`settled_at`string \| null (date-time)	—
`failed_reason`string \| null	—

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

Example

List payouts

GET /v1/payouts

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

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": [
    {
      "id": "7b6d615c-b239-44a0-b13d-fc2507da24ab",
      "object": "payout",
      "status": "settled",
      "amount_cents": 10964,
      "fee_cents": 110,
      "net_cents": 10854,
      "returns_netted_cents": 0,
      "fees_netted_cents": 370,
      "fees_included": 5,
      "method": "ach_credit",
      "trigger": "manual",
      "payments_included": 2,
      "returns_included": 0,
      "period_start": "2026-10-28T00:22:34.395Z",
      "period_end": "2026-10-28T00:24:38.631Z",
      "initiated_at": "2026-10-28T00:24:38.631Z",
      "settled_at": "2026-10-28T00:25:38.633Z",
      "failed_reason": null
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 25,
    "offset": 0,
    "has_more": false
  }
}

GET /v1/payouts/settings

The payout schedule and the next payout day, whether "Pay me now" is on, its fee, and what one would send now

Secret key

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

SMP staff set both, per merchant: the schedule (PATCH /admin/v1/merchants/{id}/payout-schedule) and early payouts ("Pay me now", POST /v1/payouts/trigger; PUT /admin/v1/merchants/{id}/early-payouts). The merchant reads them here and can change neither.

Responses

Status	Meaning
`200`	Payout settings

Fields of `data` (200)

Field Notes

objectstring = "payout_settings" —

payout_scheduleenum hold: paid only when the merchant asks (POST /v1/payouts/trigger), with no fee. one of daily, weekly, biweekly, monthly, hold

payout_weekdayinteger Weekly and biweekly: 1 = Monday … 5 = Friday; Tuesday (2) unless SMP staff set another. 1 to 5

payout_daystring The schedule in words ("only when you ask (no fee)" on hold). A payout day that falls on a weekend or a Fed holiday goes out on the next Fed business day.

next_payout_datestring | null (date) The UTC day of the next scheduled payout run (14:00 UTC); null for a hold

early_payouts_enabledboolean Set only by SMP staff (PUT /admin/v1/merchants/{id}/early-payouts)

early_payout_feeobject | null

The payout.instant rule in force for this merchant; null on the Hold schedule, where a payout the merchant asks for carries no fee, or when no such rule is active

6 child fields

`code`string = "payout.instant"	—
`basis`enum	one of `fixed`, `bps`, `bps_plus_fixed`
`bps`integer \| null	Basis points of the payout; null on a fixed rule
`fixed_cents`integer \| null	null on a bps-only rule
`min_cents`integer \| null	—
`max_cents`integer \| null	—

early_payout_quoteobject

What an early payout would send now, with the same fee calculation the payout charges

3 child fields

`available_cents`integer	The payable balance (the merchant balance less funds still held)
`fee_cents`integer	—
`net_cents`integer	What would reach the merchant's bank

Example

Payout settings

GET /v1/payouts/settings

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

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "payout_settings",
    "payout_schedule": "weekly",
    "payout_weekday": 2,
    "payout_day": "Tuesday (UTC)",
    "next_payout_date": "2026-11-03",
    "early_payouts_enabled": false,
    "early_payout_fee": {
      "code": "payout.instant",
      "basis": "bps",
      "bps": 100,
      "fixed_cents": null,
      "min_cents": 25,
      "max_cents": null
    },
    "early_payout_quote": {
      "available_cents": 10964,
      "fee_cents": 110,
      "net_cents": 10854
    }
  }
}

POST /v1/payouts/trigger

An early payout of the payable balance now, less the early payout fee

Secret key Idempotency-Key required

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

Pays the merchant balance less funds still held. Returns and fees booked since the last payout are already in that balance, so they come off this payout. Off until SMP staff turn "Pay me now" on for the merchant (422 early_payouts_off); it carries the payout.instant fee in force for the merchant (GET /v1/fees/schedule), taken from what is sent (fee_cents, net_cents) and charged once the bank accepts the credit. Refused (422 payout_held) while any payout hold is active, including one placed by reconciliation. Payments become paid_out when the bank settles the credit.

Parameters

Field	Notes
`Idempotency-Key` requiredheader · string	1–255 characters. printable characters, no spaces; see Idempotency

Responses

Status	Meaning
`200`	Payout (`Payout`)
`201`	Payout (`Payout`)
`403`	Error — error shape and codes
`409`	Error — error shape and codes
`422`	Error — error shape and codes
`502`	Error — error shape and codes

Fields of `data` (200)

The same fields as under listPayouts.

Example

Pay out the available balance now

POST /v1/payouts/trigger

curl -X POST https://sandbox.socialmatterspay.com/v1/payouts/trigger \
  -H 'Idempotency-Key: payout_2026_10_25' \
  -H 'Authorization: Bearer sk_sandbox_…'

Response · 201

HTTP 201
Cache-Control: no-store

{
  "data": {
    "id": "7b6d615c-b239-44a0-b13d-fc2507da24ab",
    "object": "payout",
    "status": "submitted",
    "amount_cents": 10964,
    "fee_cents": 110,
    "net_cents": 10854,
    "returns_netted_cents": 0,
    "fees_netted_cents": 370,
    "fees_included": 5,
    "method": "ach_credit",
    "trigger": "manual",
    "payments_included": 2,
    "returns_included": 0,
    "period_start": "2026-10-28T00:22:34.395Z",
    "period_end": "2026-10-28T00:24:38.631Z",
    "initiated_at": "2026-10-28T00:24:38.631Z",
    "settled_at": null,
    "failed_reason": null
  }
}

GET /v1/payouts/{id}

Get a payout

Secret key

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

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`200`	Payout (`Payout`)
`404`	Error — error shape and codes

Fields of `data` (200)

The same fields as under listPayouts.

Example

Get a payout

GET /v1/payouts/7b6d615c-b239-44a0-b13d-fc2507da24ab

curl https://sandbox.socialmatterspay.com/v1/payouts/7b6d615c-b239-44a0-b13d-fc2507da24ab \
  -H 'Authorization: Bearer sk_sandbox_…'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "7b6d615c-b239-44a0-b13d-fc2507da24ab",
    "object": "payout",
    "status": "settled",
    "amount_cents": 10964,
    "fee_cents": 110,
    "net_cents": 10854,
    "returns_netted_cents": 0,
    "fees_netted_cents": 370,
    "fees_included": 5,
    "method": "ach_credit",
    "trigger": "manual",
    "payments_included": 2,
    "returns_included": 0,
    "period_start": "2026-10-28T00:22:34.395Z",
    "period_end": "2026-10-28T00:24:38.631Z",
    "initiated_at": "2026-10-28T00:24:38.631Z",
    "settled_at": "2026-10-28T00:25:38.633Z",
    "failed_reason": null
  }
}

SMP staff — set when a merchant is paid (the same call as PATCH)

Parameters

Request body

Responses

Fields of data (200)

SMP staff — set when a merchant is paid, with the reason on record

Parameters

Request body

Responses

Fields of data (200)

SMP staff — whether "Pay me now" is on for a merchant, its fee, and every change with who made it

Parameters

Responses

Fields of data (200)

SMP staff — turn "Pay me now" on or off for one merchant

Parameters

Request body

Responses

Fields of data (200)

List payouts

Parameters

Responses

Fields of each item of data (200)

The payout schedule and the next payout day, whether "Pay me now" is on, its fee, and what one would send now

Responses

Fields of data (200)

An early payout of the payable balance now, less the early payout fee

Parameters

Responses

Fields of data (200)

Get a payout

Parameters

Responses

Fields of data (200)

Fields of `data` (200)

Fields of `data` (200)

Fields of `data` (200)

Fields of `data` (200)

Fields of each item of `data` (200)

Fields of `data` (200)

Fields of `data` (200)

Fields of `data` (200)