Dashboard: money · Social Matter Payments API

GET /portal/api/balances

Balances from the ledger, to the cent

Dashboard session

Host https://app.socialmatterspay.com

Responses

Status	Meaning
`200`	OK
`401`	Error — error shape and codes

Fields of `data` (200)

Field	Notes
`object`string = "balance"	—
`available_cents`integer	What a payout would send now, never below zero
`merchant_balance_cents`integer	What SMP owes the merchant; negative when returns exceed it
`held_cents`integer	Settled payments not yet released (every payment is released on settlement unless SMP staff set a release delay)
`reserve_held_cents`integer	Held back by reserves SMP staff added; 0 when there are none
`pending_cents`integer	Net of payments submitted and not yet settled

Example

Dashboard balances

GET /portal/api/balances

curl https://app.socialmatterspay.com/portal/api/balances \
  -H 'Authorization: Bearer portal_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "balance",
    "available_cents": 0,
    "merchant_balance_cents": -5400,
    "held_cents": 0,
    "reserve_held_cents": 0,
    "pending_cents": 0
  }
}

GET /portal/api/payments

Payments, newest first

Dashboard session

Host https://app.socialmatterspay.com

Parameters

Field	Notes
`status`query · string	—
`limit`query · integer	—
`offset`query · integer	—

Responses

Status	Meaning
`200`	OK
`401`	Error — error shape and codes

Fields of each item of `data` (200)

Field	Notes
`id`string	—
`amount_cents`integer	—
`fee_cents`integer	—
`net_cents`integer	Amount less the fee
`refunded_cents`integer	—
`status`enum	Forward 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`
`entry_code`enum	one of `WEB`, `PPD`, `CCD`, `TEL`
`statement_descriptor`string	—
`external_order_id`string \| null	The order reference you sent with the payment
`created_at`string (date-time)	—
`settled_at`string \| null (date-time)	—
`released_at`string \| null (date-time)	—
`paid_out_at`string \| null (date-time)	—
`decline_reason`enum	A fixed code on a declined payment; null on any other. The risk engine's own reasons are never sent. one of `insufficient_funds`, `balance_unavailable`, `merchant_limit_exceeded`, `merchant_return_rate_limit`, `velocity_limit`, `bank_rejected`, `risk_declined`,
`payer_name`string \| null	—
`payer_email`string	—
`bank_last_four`string	Last four digits of the payer's account
`decline_message`string \| null	The fixed sentence for decline_reason; null when the payment was not declined

Example

Dashboard payments

GET /portal/api/payments

curl https://app.socialmatterspay.com/portal/api/payments?limit=2 \
  -H 'Authorization: Bearer portal_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": [
    {
      "id": "b17067cf-5562-4448-a039-3149a0ccd6cc",
      "amount_cents": 4200,
      "fee_cents": 67,
      "net_cents": 4133,
      "refunded_cents": 0,
      "status": "returned",
      "entry_code": "WEB",
      "statement_descriptor": "NORTHWIND",
      "external_order_id": "order_10485",
      "created_at": "2026-10-28T00:23:37.602Z",
      "settled_at": "2026-10-28T00:24:37.605Z",
      "released_at": "2026-10-28T00:24:38.610Z",
      "paid_out_at": "2026-10-28T00:25:38.633Z",
      "decline_reason": null,
      "payer_name": "Ana Lopez",
      "payer_email": "ana.lopez@example.com",
      "bank_last_four": "9606",
      "decline_message": null
    },
    {
      "id": "9089e75d-cad0-4ed0-9cdb-166fad3ecfd9",
      "amount_cents": 2500,
      "fee_cents": 50,
      "net_cents": 2450,
      "refunded_cents": 0,
      "status": "voided",
      "entry_code": "WEB",
      "statement_descriptor": "NORTHWIND",
      "external_order_id": "order_10484",
      "created_at": "2026-10-28T00:22:35.545Z",
      "settled_at": null,
      "released_at": null,
      "paid_out_at": null,
      "decline_reason": null,
      "payer_name": "Ana Lopez",
      "payer_email": "ana.lopez@example.com",
      "bank_last_four": "9606",
      "decline_message": null
    }
  ],
  "total": 4,
  "limit": 2,
  "offset": 0
}

GET /portal/api/payouts

Payouts, newest first

Dashboard session

Host https://app.socialmatterspay.com

Responses

Status	Meaning
`200`	OK
`401`	Error — error shape and codes

Fields of each item of `data` (200)

Field	Notes
`id`string	—
`amount_cents`integer	The payable balance the payout paid out
`fee_cents`integer	The payout fee (Pay me now)
`net_cents`integer	What was sent to the bank: amount_cents less fee_cents
`returns_netted_cents`integer	Returns this payout carried
`fees_netted_cents`integer	Assessed fees this payout carried
`fees_included`integer	How many fees the payout carried
`method`enum	one of `ach_credit`, `fednow`, `rtp`
`trigger`enum	one of `manual`, `scheduled`
`status`enum	one of `pending`, `submitted`, `settled`, `failed`, `cancelled`
`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	—

Example

Dashboard payouts

GET /portal/api/payouts

curl https://app.socialmatterspay.com/portal/api/payouts \
  -H 'Authorization: Bearer portal_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": [
    {
      "id": "7b6d615c-b239-44a0-b13d-fc2507da24ab",
      "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",
      "status": "settled",
      "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
    }
  ]
}

GET /portal/api/returns

Returns, newest first

Dashboard session

Host https://app.socialmatterspay.com

Responses

Status	Meaning
`200`	OK
`401`	Error — error shape and codes

Fields of each item of `data` (200)

Field	Notes
`id`string	—
`payment_id`string	—
`amount_cents`integer	—
`return_code`string	—
`return_reason`string	—
`category`enum	one of `nsf`, `admin`, `unauthorized`
`netted`enum	1 once a payout took the return out. one of `0`, `1`
`netted_from_payout_id`string \| null	—
`has_evidence`enum	1 when an evidence packet exists for the return. one of `0`, `1`
`returned_at`string (date-time)	—
`created_at`string (date-time)	—
`external_order_id`string \| null	—
`statement_descriptor`string	—
`return_fee_cents`integer	The return fee charged for it; 0 when none

Example

Dashboard returns

GET /portal/api/returns

curl https://app.socialmatterspay.com/portal/api/returns \
  -H 'Authorization: Bearer portal_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": [
    {
      "id": "cf78dfa0-3095-4c6b-aab7-e7fd7a67d3c0",
      "payment_id": "b17067cf-5562-4448-a039-3149a0ccd6cc",
      "amount_cents": 4200,
      "return_code": "R01",
      "return_reason": "Insufficient Funds",
      "category": "nsf",
      "netted": 0,
      "netted_from_payout_id": null,
      "has_evidence": 0,
      "returned_at": "2026-10-28T00:24:38.640Z",
      "created_at": "2026-10-28T00:27:38.650Z",
      "external_order_id": "order_10485",
      "statement_descriptor": "NORTHWIND",
      "return_fee_cents": 1200
    }
  ]
}

GET /portal/api/overview

Payments balance, the next payout with every payment, return, refund and fee in it, and the payment line

Dashboard session

Host https://app.socialmatterspay.com

Responses

Status	Meaning
`200`	OK
`401`	Error — error shape and codes

Fields of `data` (200)

Field Notes

objectstring = "overview" —

as_ofstring (date-time) The engine's time for this merchant (the sandbox clock offset applies in the sandbox)

closureobject | null

Only on a closed account; null otherwise

9 child fields

`object`string = "account_closure"	—
`source`enum	engine: SMP's engine answered; rule: the 90-day rule applied to the ledger because it did not. one of `engine`, `rule`
`hold_days`integer	Days the balance is held after the last debit settled
`closed_at`string \| null (date-time)	—
`last_debit_settled_at`string \| null (date-time)	—
`release_on`string \| null (date)	The day the held balance is paid out; null until no debit is still on its way
`held_cents`integer	—
`payout_id`string \| null	The final payout, once made
`debits_in_flight`integer	Debits still on their way; counted only when source is rule

balanceobject

6 child fields

`available_cents`integer	What a payout would send now, never below zero
`payable_cents`integer	The balance less held_cents and reserve_held_cents; negative when the merchant owes SMP
`merchant_balance_cents`integer	What SMP owes the merchant; negative when returns exceed it
`held_cents`integer	Settled payments not yet released (every payment is released on settlement unless SMP staff set a release delay)
`reserve_held_cents`integer	Held back by reserves SMP staff added; 0 when there are none
`pending_cents`integer	Net of payments submitted and not yet settled

next_payoutobject

18 child fields

amount_centsinteger Never below zero

scheduled_forstring | null (date-time) The next scheduled payout run; null on the Hold schedule

scheduleenum one of daily, weekly, biweekly, monthly, hold,

schedule_wordsstring | null The schedule in words

blocked_reasonenum Why no payout would go out now; null when one would. one of account_closed, on_hold, not_active, no_payout_account, nothing_to_pay,

holdsarray of object

Payout holds in force

3 child fields

`type`enum	one of `reconciliation`, `risk`, `manual`, `global`
`reason`string	—
`created_at`string (date-time)	—

payout_accountobject

3 child fields

`on_file`boolean	—
`type`enum	one of `checking`, `savings`,
`holder_name`string \| null	—

paymentsarray of object

Released payments the next payout would carry

7 child fields

`id`string	—
`amount_cents`integer	—
`fee_cents`integer	—
`net_cents`integer	—
`refunded_cents`integer	—
`external_order_id`string \| null	—
`released_at`string \| null (date-time)	—

payments_net_centsinteger Their net less refunds

returnsarray of object

Returns not yet taken out of a payout

7 child fields

`id`string	—
`payment_id`string	—
`amount_cents`integer	—
`return_code`string	The ACH return code, such as R01
`return_reason`string	—
`returned_at`string (date-time)	—
`external_order_id`string \| null	The order reference you sent with the payment; null when there was none

returns_centsinteger —

feesarray of object

Fees not yet taken out of a payout

10 child fields

`id`string	—
`code`string	The fee code, such as return or merchant.monthly
`amount_cents`integer	—
`payment_id`string \| null	The payment the fee was charged on, when it was charged on one
`return_id`string \| null	The return the fee was charged on, when it was charged on one
`period`string \| null	YYYY-MM, on a monthly fee
`assessed_at`string (date-time)	—
`external_order_id`string \| null	The charged payment's order reference; null when the fee is not on a payment or the payment had none
`invoice_id`string \| null	The invoice whose money the fee was charged on; null when it was not charged on an invoice
`invoice_external_id`string \| null	That invoice's external_id

fees_centsinteger —

refundsarray of object

Payments refunded since the last payout

3 child fields

`payment_id`string	—
`external_order_id`string \| null	—
`cents`integer	The refund's effect on the balance

refunds_centsinteger —

ledgerarray of object

Other balance movements since the last payout

11 child fields

`id`string	—
`type`enum	Money into or out of the balance that no payment, return, refund or fee line shows. one of `invoice_received`, `fee_collected`, `fee_collection_returned`, `payout_reversed`, `protection_fee`, `protection_cover`, `adjustment`
`cents`integer	Credit minus debit on the merchant balance: positive adds to the balance, negative takes from it
`invoice_id`string \| null	—
`payout_id`string \| null	—
`fee_collection_id`string \| null	—
`payment_id`string \| null	—
`created_at`string (date-time)	—
`invoice_customer`string \| null	The invoice's customer name, on an invoice line
`invoice_external_id`string \| null	—
`external_order_id`string \| null	The related payment's order reference

ledger_centsinteger —

adjustments_centsinteger The payable balance less everything listed above; 0 when the next payout is exactly those lines

lineobject

Payments by station, and this month's paid out, declined and returned

7 child fields

authorizedobject

3 child fields

`count`integer	—
`amount_cents`integer	—
`net_cents`integer	Net of fees and refunds

submittedobject

3 child fields

`count`integer	—
`amount_cents`integer	—
`net_cents`integer	Net of fees and refunds

settledobject

3 child fields

`count`integer	—
`amount_cents`integer	—
`net_cents`integer	Net of fees and refunds

releasedobject

3 child fields

`count`integer	—
`amount_cents`integer	—
`net_cents`integer	Net of fees and refunds

paid_out_this_monthobject

3 child fields

`count`integer	—
`amount_cents`integer	—
`net_cents`integer	Net of fees and refunds

declined_this_monthobject

2 child fields

`count`integer	—
`amount_cents`integer	—

returned_this_monthobject

2 child fields

`count`integer	—
`amount_cents`integer	—

Example

The home screen

GET /portal/api/overview

curl https://app.socialmatterspay.com/portal/api/overview \
  -H 'Authorization: Bearer portal_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "overview",
    "as_of": "2026-11-04T03:01:24.718Z",
    "closure": null,
    "balance": {
      "available_cents": 16401,
      "payable_cents": 16401,
      "merchant_balance_cents": 16401,
      "held_cents": 0,
      "reserve_held_cents": 0,
      "pending_cents": 0
    },
    "next_payout": {
      "amount_cents": 16401,
      "scheduled_for": null,
      "schedule": "hold",
      "schedule_words": "only when you ask (no fee)",
      "blocked_reason": null,
      "holds": [],
      "payout_account": {
        "on_file": true,
        "type": "checking",
        "holder_name": "Northwind Supply LLC"
      },
      "payments": [
        {
          "id": "1cb29cc3-79f4-48b2-bcf7-fec8686e5a0b",
          "amount_cents": 4900,
          "fee_cents": 74,
          "net_cents": 4826,
          "refunded_cents": 0,
          "external_order_id": null,
          "released_at": "2026-11-04T03:01:03.656Z"
        },
        {
          "id": "2ddeb4d3-4a97-44f7-90c4-c6ff4121e2b0",
          "amount_cents": 12000,
          "fee_cents": 145,
          "net_cents": 11855,
          "refunded_cents": 0,
          "external_order_id": "order_10611",
          "released_at": "2026-11-04T03:01:03.656Z"
        }
      ],
      "payments_net_cents": 16681,
      "returns": [],
      "returns_cents": 0,
      "fees": [
        {
          "id": "fa:batch:a5fc4446-e0a0-4260-ac10-e06060393364:2026-11-04",
          "code": "merchant.batch",
          "amount_cents": 40,
          "payment_id": null,
          "return_id": null,
          "period": "2026-11-04",
          "assessed_at": "2026-11-04T03:01:03.656Z",
          "external_order_id": null,
          "invoice_id": null,
          "invoice_external_id": null
        }
      ],
      "fees_cents": 40,
      "refunds": [],
      "refunds_cents": 0,
      "ledger": [
        {
          "id": "06e70058-b036-45ac-9e2b-7ff75d4b9173",
          "type": "protection_fee",
          "cents": -240,
          "invoice_id": null,
          "payout_id": null,
          "fee_collection_id": null,
          "payment_id": "2ddeb4d3-4a97-44f7-90c4-c6ff4121e2b0",
          "created_at": "2026-11-04T03:01:03.656Z",
          "invoice_customer": null,
          "invoice_external_id": null,
          "external_order_id": "order_10611"
        }
      ],
      "ledger_cents": -240,
      "adjustments_cents": 0
    },
    "line": {
      "authorized": {
        "count": 0,
        "amount_cents": 0,
        "net_cents": 0
      },
      "submitted": {
        "count": 0,
        "amount_cents": 0,
        "net_cents": 0
      },
      "settled": {
        "count": 0,
        "amount_cents": 0,
        "net_cents": 0
      },
      "released": {
        "count": 2,
        "amount_cents": 16900,
        "net_cents": 16681
      },
      "paid_out_this_month": {
        "count": 1,
        "amount_cents": 6400,
        "net_cents": 6311
      },
      "declined_this_month": {
        "count": 0,
        "amount_cents": 0
      },
      "returned_this_month": {
        "count": 0,
        "amount_cents": 0
      }
    }
  }
}

GET /portal/api/payments/{id}

One payment: status history, the authorization record, refunds, return, fees and payout

Dashboard session

Host https://app.socialmatterspay.com

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`200`	OK
`401`	Error — error shape and codes
`404`	Error — error shape and codes

Fields of `data` (200)

Field Notes

objectstring = "payment_detail" —

idstring —

amount_centsinteger —

fee_centsinteger —

net_centsinteger —

refunded_centsinteger —

currencystring = "USD" —

directionenum one of debit, credit

entry_codeenum one of WEB, PPD, CCD, TEL

statusenum Forward 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

risk_scoreinteger | null —

statement_descriptorstring —

idempotency_keystring —

metadataobject | null Your own keys and values, as sent with the payment; null when there are none. at most 20 keys

external_order_idstring | null —

decline_reasonenum A fixed code on a declined payment; null on any other. The risk engine's own reasons are never sent. one of insufficient_funds, balance_unavailable, merchant_limit_exceeded, merchant_return_rate_limit, velocity_limit, bank_rejected, risk_declined,

bank_referencestring | null —

release_afterstring | null (date-time) When a settled payment may be released

payout_idstring | null The payout that carried the payment

authorization_idstring —

submitted_atstring | null (date-time) —

settled_atstring | null (date-time) —

released_atstring | null (date-time) —

paid_out_atstring | null (date-time) —

created_atstring (date-time) —

updated_atstring (date-time) —

decline_messagestring | null The fixed sentence for decline_reason

payerobject

2 child fields

`name`string \| null	—
`email`string	—

bank_accountobject

4 child fields

`bank_name`string	—
`last_four`string	—
`account_type`enum	one of `checking`, `savings`
`link_method`enum	one of `plaid_instant`, `plaid_match`, `micro_deposit`, `manual`, `sandbox`

historyarray of object

Each status the payment reached, oldest first

3 child fields

`from_status`string \| null	—
`to_status`string	—
`created_at`string (date-time)	—

authorizationobject | null

The payer's authorization for the payment

13 child fields

`id`string	—
`authorization_text`string	The exact words the payer agreed to
`ip_address`string	The payer's IP address at consent
`user_agent`string \| null	—
`consent_timestamp`string (date-time)	—
`entry_code`enum	one of `WEB`, `PPD`, `CCD`, `TEL`
`frequency`enum	one of `one_time`, `recurring`, `variable`
`max_amount_cents`integer \| null	—
`schedule_description`string \| null	—
`expires_at`string (date-time)	—
`revoked_at`string \| null (date-time)	—
`revoked_reason`string \| null	—
`created_at`string (date-time)	—

refundsarray of object

Refunds of the payment, oldest first

7 child fields

`id`string	—
`amount_cents`integer	—
`reason`string \| null	—
`status`enum	one of `pending`, `submitted`, `settled`, `failed`
`created_at`string (date-time)	—
`settled_at`string \| null (date-time)	—
`failure_reason`string \| null	—

returnobject | null

The payment's return, or null when it was not returned

8 child fields

`id`string	—
`amount_cents`integer	—
`return_code`string	—
`return_reason`string	—
`category`enum	one of `nsf`, `admin`, `unauthorized`
`netted`enum	1 once a payout took the return out. one of `0`, `1`
`netted_from_payout_id`string \| null	—
`returned_at`string (date-time)	—

payoutobject | null

The payout that carried the payment, when there is one

5 child fields

`id`string	—
`status`enum	one of `pending`, `submitted`, `settled`, `failed`, `cancelled`
`amount_cents`integer	—
`initiated_at`string (date-time)	—
`settled_at`string \| null (date-time)	—

feesarray of object

Fees charged on the payment

6 child fields

`id`string	—
`code`string	—
`amount_cents`integer	—
`netted`enum	1 once a payout carried the fee. one of `0`, `1`
`netted_from_payout_id`string \| null	—
`assessed_at`string (date-time)	—

bounce_protectionobject

Present on every payment; covered, reason and the rest come from SMP's engine, so reason is null if it did not answer

6 child fields

enabledboolean Whether the merchant has Bounce Protection

coveredboolean —

reasonenum Why the payment is or is not covered; null when Bounce Protection is off or the engine did not answer. one of covered, not_enabled, payer_override, declined, not_decided,

cap_centsinteger | null Most a cover pays on this payment. Not on a merchant without Bounce Protection

coversarray of enum The return codes a cover pays. Not on a merchant without Bounce Protection. one of R01, R09

coverobject | null

The cover once a return opened one. Not on a merchant without Bounce Protection

3 child fields

`return_code`enum	one of `R01`, `R09`
`cover_cents`integer	—
`status`enum	one of `pending`, `completed`

Example

One payment

GET /portal/api/payments/3c8029c9-00de-481f-aff2-4e80839dea08

curl https://app.socialmatterspay.com/portal/api/payments/3c8029c9-00de-481f-aff2-4e80839dea08 \
  -H 'Authorization: Bearer portal_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "payment_detail",
    "id": "3c8029c9-00de-481f-aff2-4e80839dea08",
    "amount_cents": 8400,
    "fee_cents": 109,
    "net_cents": 8291,
    "refunded_cents": 1200,
    "currency": "USD",
    "direction": "debit",
    "entry_code": "WEB",
    "status": "paid_out",
    "risk_score": 65,
    "statement_descriptor": "NORTHWIND",
    "idempotency_key": "order_10482",
    "external_order_id": "order_10482",
    "decline_reason": null,
    "bank_reference": "sbt_98eecba8-0048-4a1d-83c0-385f4ac6b04a",
    "release_after": "2026-10-28T00:23:35.518Z",
    "payout_id": "7b6d615c-b239-44a0-b13d-fc2507da24ab",
    "authorization_id": "4bcf8996-5dd0-4315-955d-e67fca982a49",
    "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": "2026-10-28T00:25:38.633Z",
    "created_at": "2026-10-28T00:22:35.514Z",
    "updated_at": "2026-10-28T00:27:38.645Z",
    "metadata": {
      "cart_id": "c_7731"
    },
    "decline_message": null,
    "payer": {
      "name": "Ana Lopez",
      "email": "ana.lopez@example.com"
    },
    "bank_account": {
      "bank_name": "Plaid Checking (sandbox)",
      "last_four": "2617",
      "account_type": "checking",
      "link_method": "sandbox"
    },
    "history": [
      {
        "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"
      },
      … 4 more
    ],
    "authorization": {
      "id": "4bcf8996-5dd0-4315-955d-e67fca982a49",
      "authorization_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.",
      "ip_address": "203.0.113.7",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6) AppleWebKit/605.1.15 Safari/605.1.15",
      "consent_timestamp": "2026-10-28T00:22:35.514Z",
      "entry_code": "WEB",
      "frequency": "one_time",
      "max_amount_cents": null,
      "schedule_description": null,
      "expires_at": "2028-10-27T12:22:35.514Z",
      "revoked_at": null,
      "revoked_reason": null,
      "created_at": "2026-10-28T00:22:35.514Z"
    },
    "refunds": [
      {
        "id": "aa7af452-4b99-49a1-9c61-630bccadbb36",
        "amount_cents": 1200,
        "reason": "One item out of stock",
        "status": "settled",
        "created_at": "2026-10-28T00:23:37.591Z",
        "settled_at": "2026-10-28T00:24:37.592Z",
        "failure_reason": null
      }
    ],
    "return": null,
    "payout": {
      "id": "7b6d615c-b239-44a0-b13d-fc2507da24ab",
      "status": "failed",
      "amount_cents": 10964,
      "initiated_at": "2026-10-28T00:24:38.631Z",
      "settled_at": "2026-10-28T00:25:38.633Z"
    },
    "fees": [
      {
        "id": "fa:refund:aa7af452-4b99-49a1-9c61-630bccadbb36",
        "code": "refund",
        "amount_cents": 20,
        "netted": 1,
        "netted_from_payout_id": "92de3979-92b8-4934-872a-98d79fc3e01e",
        "assessed_at": "2026-10-28T00:23:37.591Z"
      },
      {
        "id": "fa:notice_of_change:noc_bf9d9dc4-5daf-4f42-b721-1844e9f6d126",
        "code": "notice_of_change",
        "amount_cents": 60,
        "netted": 1,
        "netted_from_payout_id": "92de3979-92b8-4934-872a-98d79fc3e01e",
        "assessed_at": "2026-11-04T03:00:01.849Z"
      }
    ],
    "bounce_protection": {
      "enabled": true,
      "covered": false,
      "reason": "not_enabled",
      "cap_cents": 75000,
      "covers": [
        "R01",
        "R09"
      ],
      "cover": null
    }
  }
}

GET /portal/api/payouts/{id}

One payout with the payments, returns and fees it carried

Dashboard session

Host https://app.socialmatterspay.com

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`200`	OK
`401`	Error — error shape and codes
`404`	Error — error shape and codes

Fields of `data` (200)

Field Notes

objectstring = "payout_detail" —

idstring —

amount_centsinteger The payable balance the payout paid out

fee_centsinteger The payout fee (Pay me now)

net_centsinteger What was sent to the bank: amount_cents less fee_cents

returns_netted_centsinteger Returns this payout carried

fees_netted_centsinteger Assessed fees this payout carried

fees_includedinteger How many fees the payout carried

methodenum one of ach_credit, fednow, rtp

triggerenum one of manual, scheduled

statusenum one of pending, submitted, settled, failed, cancelled

payments_includedinteger —

returns_includedinteger —

period_startstring (date-time) —

period_endstring (date-time) —

initiated_atstring (date-time) —

settled_atstring | null (date-time) —

failed_reasonstring | null —

paymentsarray of object

Payments the payout carried

9 child fields

`id`string	—
`amount_cents`integer	—
`fee_cents`integer	—
`net_cents`integer	—
`refunded_cents`integer	—
`status`enum	Forward 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`
`external_order_id`string \| null	—
`settled_at`string \| null (date-time)	—
`released_at`string \| null (date-time)	—

returnsarray of object

Returns the payout took out

7 child fields

`id`string	—
`payment_id`string	—
`amount_cents`integer	—
`return_code`string	The ACH return code, such as R01
`return_reason`string	—
`returned_at`string (date-time)	—
`external_order_id`string \| null	The order reference you sent with the payment; null when there was none

feesarray of object Fees the payout took out Its fields are listed under portalOverview · next_payout.fees.

ledgerarray of object Other balance movements inside the payout's period Its fields are listed under portalOverview · next_payout.ledger.

Example

One payout

GET /portal/api/payouts/7b6d615c-b239-44a0-b13d-fc2507da24ab

curl https://app.socialmatterspay.com/portal/api/payouts/7b6d615c-b239-44a0-b13d-fc2507da24ab \
  -H 'Authorization: Bearer portal_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "payout_detail",
    "id": "7b6d615c-b239-44a0-b13d-fc2507da24ab",
    "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",
    "status": "failed",
    "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": "returned: R03",
    "payments": [
      {
        "id": "3c8029c9-00de-481f-aff2-4e80839dea08",
        "amount_cents": 8400,
        "fee_cents": 109,
        "net_cents": 8291,
        "refunded_cents": 1200,
        "status": "paid_out",
        "external_order_id": "order_10482",
        "settled_at": "2026-10-28T00:23:35.518Z",
        "released_at": "2026-10-28T00:23:36.559Z"
      },
      {
        "id": "b17067cf-5562-4448-a039-3149a0ccd6cc",
        "amount_cents": 4200,
        "fee_cents": 67,
        "net_cents": 4133,
        "refunded_cents": 0,
        "status": "returned",
        "external_order_id": "order_10485",
        "settled_at": "2026-10-28T00:24:37.605Z",
        "released_at": "2026-10-28T00:24:38.610Z"
      }
    ],
    "returns": [],
    "fees": [],
    "ledger": []
  }
}

GET /portal/api/pricing

The fee rule in force for this merchant, fee by fee

Dashboard session

Host https://app.socialmatterspay.com

Responses

Status	Meaning
`200`	OK
`401`	Error — error shape and codes

Fields of `data` (200)

Field Notes

objectstring = "pricing" —

pricing_classenum Decides which per-payment fee applies. one of standard, high_risk

as_ofstring (date-time) —

feesarray of object

The per-payment fee for the merchant's pricing class, then every other merchant fee

8 child fields

`code`enum	one of `payment.standard`, `payment.high_risk`, `return`, `return.unauthorized`, `refund`, `payout.instant`, `payout.failed`, `notice_of_change`, `bank_verification`, `merchant.monthly`, `merchant.monthly_minimum`, `merchant.batch`
`active`boolean	Whether SMP charges this fee
`source`enum	override: a price set for this merchant; schedule: SMP's standard price. Null when no rule exists. one of `schedule`, `override`,
`basis`enum	one of `fixed`, `bps`, `bps_plus_fixed`,
`bps`integer \| null	Basis points of the amount; null on a fixed price
`fixed_cents`integer \| null	—
`min_cents`integer \| null	—
`max_cents`integer \| null	—

Example

The prices in force for this merchant

GET /portal/api/pricing

curl https://app.socialmatterspay.com/portal/api/pricing \
  -H 'Authorization: Bearer portal_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "pricing",
    "pricing_class": "standard",
    "as_of": "2026-11-04T03:01:24.731Z",
    "fees": [
      {
        "code": "payment.standard",
        "active": true,
        "source": "schedule",
        "basis": "bps_plus_fixed",
        "bps": 100,
        "fixed_cents": 25,
        "min_cents": null,
        "max_cents": 400
      },
      {
        "code": "return",
        "active": true,
        "source": "schedule",
        "basis": "fixed",
        "bps": null,
        "fixed_cents": 1200,
        "min_cents": null,
        "max_cents": null
      },
      … 9 more
    ]
  }
}

GET /portal/api/limits

The limits each payment is checked against: per payment, daily and monthly used and left, the no-balance cap, payer velocity (as GET /v1/limits answers the merchant)

Dashboard session

Host https://app.socialmatterspay.com

Responses

Status	Meaning
`200`	OK
`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

Limits and what is left of them

GET /portal/api/limits

curl https://app.socialmatterspay.com/portal/api/limits \
  -H 'Authorization: Bearer portal_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "limits",
    "merchant_id": "a5fc4446-e0a0-4260-ac10-e06060393364",
    "as_of": "2026-11-04T03:01:24.800Z",
    "per_transaction_cents": 300000,
    "daily": {
      "limit_cents": 5000000,
      "used_cents": 16900,
      "remaining_cents": 4983100,
      "resets_at": "2026-11-05T00:00:00.000Z"
    },
    "monthly": {
      "limit_cents": 50000000,
      "used_cents": 16900,
      "remaining_cents": 49983100,
      "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
    }
  }
}

GET /portal/api/reserves

Reserves SMP staff added to this account (rolling or fixed, each with its reason and what it holds now) and the release delay, if any; reported: false until the engine answers

Dashboard session

Host https://app.socialmatterspay.com

Responses

Status	Meaning
`200`	OK
`401`	Error — error shape and codes

Fields of `data` (200)

Field Notes

objectstring = "reserves" —

reportedboolean false when SMP's engine did not answer: reserves is then empty and release_delay null, which says nothing about whether one exists

reservesarray of object

Reserves SMP staff added and that are still in force

8 child fields

`id`string	—
`type`enum	one of `rolling`, `fixed`
`percent_bps`integer	Rolling only: the share of each payment held, in basis points
`hold_days`integer	Rolling only: days each payment's share is held
`amount_cents`integer	Fixed only: the amount held
`reason`string	The reason SMP staff gave
`created_at`string \| null (date-time)	—
`held_cents`integer	What it holds right now

release_delayobject | null

The release delay SMP staff set; null when there is none

3 child fields

`hours`integer	Hours after settlement before a payment is released
`reason`string	—
`created_at`string \| null (date-time)	—

Example

Reserves on this account

GET /portal/api/reserves

curl https://app.socialmatterspay.com/portal/api/reserves \
  -H 'Authorization: Bearer portal_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "reserves",
    "reported": true,
    "reserves": [],
    "release_delay": null
  }
}

GET /portal/api/bounce-protection

Bounce Protection: whether it is on, its rate and its per-payment cap

Dashboard session

Host https://app.socialmatterspay.com

Responses

Status	Meaning
`200`	OK
`401`	Error — error shape and codes

Fields of `data` (200)

Field	Notes
`object`string = "bounce_protection"	—
`enabled`boolean	—
`rate_bps`integer \| null	The merchant's rate on the covered part of a payment. Only when enabled
`cap_cents`integer \| null	Most a cover pays on one payment. Only when enabled
`fee_basis`enum	What the rate is charged on: covered_amount, the payment up to the cap (the engine charges min(payment, cap)). Only when enabled. one of `covered_amount`,
`covers`array of enum	The return codes a cover pays. Only when enabled. one of `R01`, `R09`
`since`string \| null (date-time)	When the terms took effect. Only when enabled

Example

Bounce Protection terms SMP set for this account

GET /portal/api/bounce-protection

curl https://app.socialmatterspay.com/portal/api/bounce-protection \
  -H 'Authorization: Bearer portal_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "bounce_protection",
    "enabled": true,
    "rate_bps": 200,
    "cap_cents": 75000,
    "fee_basis": "covered_amount",
    "covers": [
      "R01",
      "R09"
    ],
    "since": "2026-11-04T03:00:02.619Z"
  }
}

Balances from the ledger, to the cent

Responses

Fields of data (200)

Payments, newest first

Parameters

Responses

Fields of each item of data (200)

Payouts, newest first

Responses

Fields of each item of data (200)

Returns, newest first

Responses

Fields of each item of data (200)

Payments balance, the next payout with every payment, return, refund and fee in it, and the payment line

Responses

Fields of data (200)

One payment: status history, the authorization record, refunds, return, fees and payout

Parameters

Responses

Fields of data (200)

One payout with the payments, returns and fees it carried

Parameters

Responses

Fields of data (200)

The fee rule in force for this merchant, fee by fee

Responses

Fields of data (200)

The limits each payment is checked against: per payment, daily and monthly used and left, the no-balance cap, payer velocity (as GET /v1/limits answers the merchant)

Responses

Fields of data (200)

Reserves SMP staff added to this account (rolling or fixed, each with its reason and what it holds now) and the release delay, if any; reported: false until the engine answers

Responses

Fields of data (200)

Bounce Protection: whether it is on, its rate and its per-payment cap

Responses

Fields of data (200)

Fields of `data` (200)

Fields of each item of `data` (200)

Fields of each item of `data` (200)

Fields of each item of `data` (200)

Fields of `data` (200)

Fields of `data` (200)

Fields of `data` (200)

Fields of `data` (200)

Fields of `data` (200)

Fields of `data` (200)

Fields of `data` (200)