Fees · Social Matter Payments API

GET /v1/fees

Every fee SMP charged this merchant outside a payment's own per-payment fee (return fee, monthly fee)

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`
`code`query · string	—
`netted`query · string	one of `true`, `false`

Responses

Status	Meaning
`200`	Fee assessments, newest first
`400`	Error — error shape and codes

Fields of each item of `data` (200)

Field Notes

idstring —

objectstring = "fee_assessment" —

codestring —

amount_centsinteger —

base_amount_centsinteger —

ruleobject

6 child fields

`source`enum	one of `schedule`, `override`
`basis`enum	one of `fixed`, `bps`, `bps_plus_fixed`
`bps`integer \| null	—
`fixed_cents`integer \| null	—
`min_cents`integer \| null	—
`max_cents`integer \| null	—

payment_idstring | null —

return_idstring | null —

refund_idstring | null —

periodstring | null YYYY-MM for a monthly fee

nettedboolean —

netted_from_payout_idstring | null —

assessed_atstring (date-time) —

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

Example

Fees charged outside a payment

GET /v1/fees

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

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": [
    {
      "id": "fa:return:ret_sbt_e9fa3956-1381-4f03-9a17-50e7ff8ed218",
      "object": "fee_assessment",
      "code": "return",
      "amount_cents": 1200,
      "base_amount_cents": 4200,
      "rule": {
        "source": "schedule",
        "basis": "fixed",
        "bps": null,
        "fixed_cents": 1200,
        "min_cents": null,
        "max_cents": null
      },
      "payment_id": "b17067cf-5562-4448-a039-3149a0ccd6cc",
      "return_id": "cf78dfa0-3095-4c6b-aab7-e7fd7a67d3c0",
      "refund_id": null,
      "period": null,
      "netted": false,
      "netted_from_payout_id": null,
      "assessed_at": "2026-10-28T00:27:38.650Z"
    },
    {
      "id": "fa:payout.instant:7b6d615c-b239-44a0-b13d-fc2507da24ab",
      "object": "fee_assessment",
      "code": "payout.instant",
      "amount_cents": 110,
      "base_amount_cents": 10964,
      "rule": {
        "source": "schedule",
        "basis": "bps",
        "bps": 100,
        "fixed_cents": null,
        "min_cents": 25,
        "max_cents": null
      },
      "payment_id": null,
      "return_id": null,
      "refund_id": null,
      "period": null,
      "netted": true,
      "netted_from_payout_id": "7b6d615c-b239-44a0-b13d-fc2507da24ab",
      "assessed_at": "2026-10-28T00:24:38.631Z"
    },
    … 4 more
  ],
  "pagination": {
    "total": 6,
    "limit": 25,
    "offset": 0,
    "has_more": false
  }
}

GET /v1/fees/schedule

The price in force for this merchant now, code by code (its own override, else SMP's default)

Secret key

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

Responses

Status	Meaning
`200`	Fee schedule in force

Fields of `data` (200)

Field Notes

objectstring = "fee_schedule" —

pricing_classenum one of standard, high_risk

as_ofstring (date-time) —

feesarray of object

8 child fields

`code`string	—
`active`boolean	—
`source`enum	one of `schedule`, `override`,
`basis`enum	one of `fixed`, `bps`, `bps_plus_fixed`
`bps`integer \| null	—
`fixed_cents`integer \| null	—
`min_cents`integer \| null	—
`max_cents`integer \| null	—

Example

The prices in force for this merchant

GET /v1/fees/schedule

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

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "fee_schedule",
    "pricing_class": "standard",
    "as_of": "2026-10-28T00:27:38.672Z",
    "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 /v1/statements/{month}

The month's statement — one line per movement of what SMP owes the merchant, every fee included

Secret key

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

Parameters

Field	Notes
`month` requiredpath · string	YYYY-MM (UTC)

Responses

Status	Meaning
`200`	Statement
`400`	Error — error shape and codes

Fields of `data` (200)

Field Notes

objectstring = "statement" —

monthstring —

period_startstring (date-time) —

period_endstring (date-time) —

opening_balance_centsinteger —

closing_balance_centsinteger —

feesobject

3 child fields

per_payment_centsinteger Per-payment fees taken at settlement this month

assessedarray of object

3 child fields

`code`string	—
`count`integer	—
`cents`integer	—

assessed_centsinteger —

bounce_protectionobject

Bounce Protection this month, apart from SMP's fees (its fees go to SMP's reserve)

2 child fields

`fees_cents`integer	—
`covers_cents`integer	Covers SMP's reserve paid for R01/R09 returns

linesarray of object

14 child fields

`at`string (date-time)	—
`type`enum	one of `payment_settled`, `payout_initiated`, `payout_reversed`, `return_debited`, `refund_issued`, `refund_reversed`, `fee_assessed`, `fee_collected`, `fee_collection_returned`, `invoice_received`, `protection_fee`, `protection_cover`, `adjustment`
`description`string	—
`credit_cents`integer	—
`debit_cents`integer	—
`balance_after_cents`integer	—
`payment_id`string \| null	—
`payout_id`string \| null	—
`return_id`string \| null	—
`refund_id`string \| null	—
`fee_assessment_id`string \| null	—
`fee_collection_id`string \| null	—
`invoice_id`string \| null	—
`fee_code`string \| null	—

fee_collectionsarray of object

Debits made from the merchant's own account this month

14 child fields

`id`string	—
`object`string = "fee_collection"	—
`status`enum	one of `pending`, `submitted`, `settled`, `returned`, `failed`
`amount_cents`integer	—
`entry_code`enum	one of `CCD`, `PPD`
`same_day`boolean	—
`attempt_kind`enum	A retry of a debit returned R01/R09 (same amount, RETRY PYMT), at most twice. one of `initial`, `reinitiated`
`reinitiates_collection_id`string \| null	—
`return_code`string \| null	—
`failure_reason`string \| null	—
`created_at`string (date-time)	—
`submitted_at`string \| null (date-time)	—
`settled_at`string \| null (date-time)	—
`returned_at`string \| null (date-time)	—

Example

This month's statement

GET /v1/statements/2026-10

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

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "statement",
    "month": "2026-10",
    "period_start": "2026-10-01T00:00:00.000Z",
    "period_end": "2026-11-01T00:00:00.000Z",
    "opening_balance_cents": 0,
    "closing_balance_cents": -5400,
    "fees": {
      "per_payment_cents": 176,
      "assessed": [
        {
          "code": "bank_verification",
          "count": 2,
          "cents": 200
        },
        {
          "code": "merchant.batch",
          "count": 1,
          "cents": 40
        },
        … 3 more
      ],
      "assessed_cents": 1570
    },
    "bounce_protection": {
      "fees_cents": 0,
      "covers_cents": 0
    },
    "lines": [
      {
        "at": "2026-10-28T00:22:35.486Z",
        "type": "fee_assessed",
        "description": "Fee bank_verification: 100 cents",
        "credit_cents": 0,
        "debit_cents": 100,
        "balance_after_cents": -100,
        "payment_id": null,
        "payout_id": null,
        "return_id": null,
        "refund_id": null,
        "fee_assessment_id": "fa:bank_verification:1357923a-53e2-4aa9-a547-a20155759d6c",
        "fee_collection_id": null,
        "invoice_id": null,
        "fee_code": "bank_verification"
      },
      {
        "at": "2026-10-28T00:22:35.532Z",
        "type": "fee_assessed",
        "description": "Fee bank_verification: 100 cents",
        "credit_cents": 0,
        "debit_cents": 100,
        "balance_after_cents": -200,
        "payment_id": null,
        "payout_id": null,
        "return_id": null,
        "refund_id": null,
        "fee_assessment_id": "fa:bank_verification:33746dac-4666-4b2a-9c31-6d3ce13afdc5",
        "fee_collection_id": null,
        "invoice_id": null,
        "fee_code": "bank_verification"
      },
      … 9 more
    ],
    "fee_collections": []
  }
}

GET /v1/fee-debit-authorization

The exact words authorizing SMP to debit the payout account for what payouts don't cover (CCD), and the one in force

Secret key

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

Responses

Status	Meaning
`200`	Terms
`422`	Error — error shape and codes

Fields of `data` (200)

Field Notes

objectstring = "fee_debit_terms" —

entry_codestring = "CCD" —

account_last4string —

account_holder_namestring —

authorization_textstring —

text_sha256string —

authorizationobject | null

15 child fields

`id`string	—
`object`string = "fee_debit_authorization"	—
`status`enum	one of `in_force`, `revoked`
`entry_code`enum	one of `CCD`, `PPD`
`authorization_text`string	—
`text_sha256`string	—
`account_last4`string	—
`account_type`enum	one of `checking`, `savings`
`account_holder_name`string	—
`signer_name`string	—
`signer_title`string \| null	—
`accepted_at`string (date-time)	—
`revoked_at`string \| null (date-time)	—
`revoked_reason`string \| null	—
`retain_until`string \| null (date-time)	Two years after it ended

Example

The words the signer accepts

GET /v1/fee-debit-authorization

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

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "fee_debit_terms",
    "entry_code": "CCD",
    "account_last4": "1100",
    "account_holder_name": "Lakeside Outfitters LLC",
    "authorization_text": "Lakeside Outfitters LLC authorizes Social Matter Payments LLC to initiate ACH debit entries (CCD) to the business bank account ending in 1100 for fees and other amounts Lakeside Outfitters LLC owes Social Matter Payments LLC under the merchant agreement that its payouts from Social Matter Payments LLC do not cover. The amount of each debit appears on Lakeside Outfitters LLC's statement before the debit is made. This authorization stays in effect until Social Matter Payments LLC receives written notice of revocation at work@socialmatters.pro in time to act on it. Revoking it does not cancel amounts already owed.",
    "text_sha256": "b73ed75b5cd7ee1be3502785b75c171e67eb75dd6fe31722636222934d519669",
    "authorization": null
  }
}

PUT /v1/fee-debit-authorization

The signer accepts those words; text_sha256 (from GET) proves which text was shown. Kept two years after it ends.

Secret key

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

Request body

Field	Notes
`accepted` requiredboolean = true	—
`signer_name` requiredstring	up to 200 characters
`signer_title`string	up to 200 characters
`text_sha256` requiredstring	pattern `^[0-9a-fA-F]{64}$`

Responses

Status	Meaning
`201`	The authorization in force
`400`	Error — error shape and codes
`409`	Error — error shape and codes
`422`	Error — error shape and codes

Fields of `data` (201)

The same fields as under getFeeDebitTerms · authorization.

Example

Accept them

PUT /v1/fee-debit-authorization

curl -X PUT https://sandbox.socialmatterspay.com/v1/fee-debit-authorization \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "accepted": true,
  "signer_name": "Casey Brooks",
  "signer_title": "Owner",
  "text_sha256": "b73ed75b5cd7ee1be3502785b75c171e67eb75dd6fe31722636222934d519669"
}'

Response · 201

HTTP 201
Cache-Control: no-store

{
  "data": {
    "id": "ada_fe764c4c-29ea-463c-ac43-8ff6d5d7535e",
    "object": "fee_debit_authorization",
    "status": "in_force",
    "entry_code": "CCD",
    "authorization_text": "Lakeside Outfitters LLC authorizes Social Matter Payments LLC to initiate ACH debit entries (CCD) to the business bank account ending in 1100 for fees and other amounts Lakeside Outfitters LLC owes Social Matter Payments LLC under the merchant agreement that its payouts from Social Matter Payments LLC do not cover. The amount of each debit appears on Lakeside Outfitters LLC's statement before the debit is made. This authorization stays in effect until Social Matter Payments LLC receives written notice of revocation at work@socialmatters.pro in time to act on it. Revoking it does not cancel amounts already owed.",
    "text_sha256": "b73ed75b5cd7ee1be3502785b75c171e67eb75dd6fe31722636222934d519669",
    "account_last4": "1100",
    "account_type": "checking",
    "account_holder_name": "Lakeside Outfitters LLC",
    "signer_name": "Casey Brooks",
    "signer_title": "Owner",
    "accepted_at": "2026-10-28T00:26:38.763Z",
    "revoked_at": null,
    "revoked_reason": null,
    "retain_until": null
  }
}

GET /v1/fee-collections

Debits SMP made from the merchant's own account, on its payout day, for what payouts did not cover

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`, `returned`, `failed`

Responses

Status	Meaning
`200`	Fee collections, newest first
`400`	Error — error shape and codes

Fields of each item of `data` (200)

The same fields as under getStatement · fee_collections.

Example

Debits from your own account

GET /v1/fee-collections

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

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": [
    {
      "id": "fc_d7dfee96-ee3a-4a4b-96f5-bb17919f1b76",
      "object": "fee_collection",
      "status": "submitted",
      "amount_cents": 3198,
      "entry_code": "CCD",
      "same_day": true,
      "attempt_kind": "initial",
      "reinitiates_collection_id": null,
      "return_code": null,
      "failure_reason": null,
      "created_at": "2026-11-03T15:00:00.778Z",
      "submitted_at": "2026-11-03T15:00:00.778Z",
      "settled_at": null,
      "returned_at": null
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 25,
    "offset": 0,
    "has_more": false
  }
}

GET /v1/fee-collections/{id}

Get a fee collection

Secret key

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

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`200`	Fee collection
`404`	Error — error shape and codes

Fields of `data` (200)

The same fields as under getStatement · fee_collections.

Example

One debit

GET /v1/fee-collections/fc_d7dfee96-ee3a-4a4b-96f5-bb17919f1b76

curl https://sandbox.socialmatterspay.com/v1/fee-collections/fc_d7dfee96-ee3a-4a4b-96f5-bb17919f1b76 \
  -H 'Authorization: Bearer sk_sandbox_…'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "fc_d7dfee96-ee3a-4a4b-96f5-bb17919f1b76",
    "object": "fee_collection",
    "status": "submitted",
    "amount_cents": 3198,
    "entry_code": "CCD",
    "same_day": true,
    "attempt_kind": "initial",
    "reinitiates_collection_id": null,
    "return_code": null,
    "failure_reason": null,
    "created_at": "2026-11-03T15:00:00.778Z",
    "submitted_at": "2026-11-03T15:00:00.778Z",
    "settled_at": null,
    "returned_at": null
  }
}

Every fee SMP charged this merchant outside a payment's own per-payment fee (return fee, monthly fee)

Parameters

Responses

Fields of each item of data (200)

The price in force for this merchant now, code by code (its own override, else SMP's default)

Responses

Fields of data (200)

The month's statement — one line per movement of what SMP owes the merchant, every fee included

Parameters

Responses

Fields of data (200)

The exact words authorizing SMP to debit the payout account for what payouts don't cover (CCD), and the one in force

Responses

Fields of data (200)

The signer accepts those words; text_sha256 (from GET) proves which text was shown. Kept two years after it ends.

Request body

Responses

Fields of data (201)

Debits SMP made from the merchant's own account, on its payout day, for what payouts did not cover

Parameters

Responses

Fields of each item of data (200)

Get a fee collection

Parameters

Responses

Fields 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` (201)

Fields of each item of `data` (200)

Fields of `data` (200)