Debit schedules · Social Matter Payments API

POST /v1/debit-schedules/authorization-text

The standing authorization's exact words, to show the payer before they agree

Secret key

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

Show text to the payer word for word, next to the button they press to agree, then send text_sha256 as authorization_text_sha256 with POST /v1/debit-schedules (required for WEB and TEL). The words name the amount, what it is for, the cadence, start date and number of debits, the payday window when there is one, the account and how to revoke. Fetch them again if any of those change.

Request body

Field	Notes
`bank_account_id` requiredstring	—
`amount_cents` requiredinteger	The same every time; at most the account's per-payment limit. 1 to 99999999
`interval` requiredenum	one of `weekly`, `biweekly`, `monthly`
`start_date` requiredstring (date)	The first scheduled date, today to a year ahead. Monthly keeps its day (the last day of shorter months).
`total_count`integer	Number of debits; leave out for until revoked. 1 to 520
`payday_window_days`integer	Days after each scheduled date the payer agrees a debit may move to, to land after payday (weekly up to 3, biweekly 7, monthly 10). Above 0 needs payday-aware debits on. 0 to 10. default `0`
`description` requiredstring	What the payer pays for; it goes into the authorization words. up to 100 characters
`entry_code`enum	one of `WEB`, `PPD`, `CCD`, `TEL`. default `"WEB"`

Responses

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

Fields of `data` (200)

Field Notes

objectstring = "debit_schedule_authorization_text" —

textstring —

text_sha256string —

merchant_namestring —

amount_centsinteger —

amount_descriptionstring —

frequencystring = "recurring" —

schedule_descriptionstring —

payday_window_daysinteger —

entry_codeenum one of WEB, PPD, CCD, TEL

bank_accountobject

3 child fields

`id`string	—
`bank_name`string	—
`last_four`string	—

ach_companyobject | null

The ACH company the payer's bank shows on the debit (Company Name and Company Identification); null when not configured

2 child fields

`name`string	up to 16 characters
`id`string	up to 10 characters

Example

The standing authorization to show the payer

POST /v1/debit-schedules/authorization-text

curl -X POST https://sandbox.socialmatterspay.com/v1/debit-schedules/authorization-text \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "bank_account_id": "0fb9dd42-2bd9-49c1-9c85-68872c5cee57",
  "amount_cents": 4900,
  "interval": "biweekly",
  "start_date": "2026-11-04",
  "total_count": 12,
  "payday_window_days": 3,
  "description": "Shop supplies plan"
}'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "debit_schedule_authorization_text",
    "text": "By agreeing, you authorize Northwind Supply to make recurring electronic debits from your bank account ending in 9606 for Shop supplies plan: $49.00 every two weeks on Wednesday, starting 2026-11-04, 12 times. If a scheduled date is not a business day, that debit is made the next business day. To land after your payday, a debit may instead be made on a later business day up to 3 days after its scheduled date, never before it. This authorization ends after the last debit, unless you revoke it sooner. You may revoke it at any time by contacting Northwind Supply, with the understanding that it may take up to 3 business days to process.",
    "text_sha256": "59b344d797487ea4d4830a8a5cb8a5a2d24ffa7a2aca0794228140152dc3c853",
    "merchant_name": "Northwind Supply",
    "amount_cents": 4900,
    "amount_description": "$49.00",
    "frequency": "recurring",
    "schedule_description": "every two weeks on Wednesday, starting 2026-11-04, 12 times",
    "payday_window_days": 3,
    "entry_code": "WEB",
    "bank_account": {
      "id": "0fb9dd42-2bd9-49c1-9c85-68872c5cee57",
      "bank_name": "Plaid Checking (sandbox)",
      "last_four": "9606"
    },
    "ach_company": null
  }
}

GET /v1/debit-schedules

List debit schedules, newest first, each with its next debit

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 `active`, `cancelled`, `completed`
`payer_id`query · string	—

Responses

Status	Meaning
`200`	A page of debit schedules (without their past debits)
`400`	Error — error shape and codes

Fields of each item of `data` (200)

Field Notes

idstring —

objectstring = "debit_schedule" —

statusenum one of active, cancelled, completed

amount_centsinteger —

currencystring = "USD" —

intervalenum one of weekly, biweekly, monthly

start_datestring (date) —

total_countinteger | null —

payday_window_daysinteger —

schedule_descriptionstring —

descriptionstring —

entry_codeenum one of WEB, PPD, CCD, TEL

payer_idstring —

bank_account_idstring —

authorization_idstring —

statement_descriptorstring | null —

external_idstring | null —

metadataobject | null Your own keys and values, as you sent them; null when there are none. Each debit's payment carries them, plus debit_schedule_id and debit_sequence. at most 18 keys

next_debitobject | null

One debit of a schedule. The payer's payday and balances are never shown, only when the debit goes.

8 child fields

`sequence`integer	—
`due_date`string (date)	The date the authorization names
`latest_date`string (date)	The last day it may be taken
`planned_date`string (date)	—
`timing`enum	one of `scheduled_date`, `after_payday`
`status`enum	one of `scheduled`, `submitted`, `declined`, `failed`, `missed`, `cancelled`
`payment_id`string \| null	—
`failure`string \| null	—

debitsarray of object Every debit so far and the next; not in lists Its fields are listed under listDebitSchedules · next_debit.

cancelled_atstring | null (date-time) —

cancel_reasonstring | null —

created_atstring (date-time) —

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

Example

List debit schedules

GET /v1/debit-schedules

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

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": [
    {
      "id": "ds_b2a7bd4a-cb37-4e32-a367-166bf081fea2",
      "object": "debit_schedule",
      "status": "active",
      "amount_cents": 4900,
      "currency": "USD",
      "interval": "biweekly",
      "start_date": "2026-11-04",
      "total_count": 12,
      "payday_window_days": 3,
      "schedule_description": "every two weeks on Wednesday, starting 2026-11-04, 12 times",
      "description": "Shop supplies plan",
      "entry_code": "WEB",
      "payer_id": "faac6000-d575-4826-af0a-cfa4e0f6bc9a",
      "bank_account_id": "0fb9dd42-2bd9-49c1-9c85-68872c5cee57",
      "authorization_id": "0c1ef864-b5cb-465e-88fc-2f68c61ba5f3",
      "statement_descriptor": null,
      "external_id": "plan_2201",
      "metadata": null,
      "next_debit": {
        "sequence": 1,
        "due_date": "2026-11-04",
        "latest_date": "2026-11-06",
        "planned_date": "2026-11-04",
        "timing": "scheduled_date",
        "status": "scheduled",
        "payment_id": null,
        "failure": null
      },
      "cancelled_at": null,
      "cancel_reason": null,
      "created_at": "2026-10-30T00:28:43.764Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 25,
    "offset": 0,
    "has_more": false
  }
}

POST /v1/debit-schedules

Set up a recurring debit under one standing authorization

Secret key Idempotency-Key required

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

Records the payer's standing authorization (the exact words, kept two years past its end) and plans the first debit. Each debit is a normal payment, authorized before debit like any other (risk, limits, velocity), with metadata.debit_schedule_id and metadata.debit_sequence; its webhooks are the payment's. Debits are taken from 14:00 to 22:00 UTC on their planned date, a few per merchant at a time; one that couldn't be taken by its latest_date is missed, never late. The same Idempotency-Key with the same body returns the same schedule (200); with a different body it is a 409.

Parameters

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

Request body

Field	Notes
`bank_account_id` requiredstring	—
`amount_cents` requiredinteger	The same every time; at most the account's per-payment limit. 1 to 99999999
`interval` requiredenum	one of `weekly`, `biweekly`, `monthly`
`start_date` requiredstring (date)	The first scheduled date, today to a year ahead. Monthly keeps its day (the last day of shorter months).
`total_count`integer	Number of debits; leave out for until revoked. 1 to 520
`payday_window_days`integer	Days after each scheduled date the payer agrees a debit may move to, to land after payday (weekly up to 3, biweekly 7, monthly 10). Above 0 needs payday-aware debits on. 0 to 10. default `0`
`description` requiredstring	What the payer pays for; it goes into the authorization words. up to 100 characters
`entry_code`enum	one of `WEB`, `PPD`, `CCD`, `TEL`. default `"WEB"`
`authorization_text_sha256`string	Required for WEB and TEL; the SHA-256 of the words shown. pattern `^[0-9a-f]{64}$`
`payer_ip`string	Required for WEB
`payer_user_agent`string	Required for WEB
`authorized_at`string (date-time)	—
`statement_descriptor`string	pattern `^[A-Za-z0-9 .&-]{1,12}$`
`external_id`string	up to 255 characters
`metadata`object	at most 18 keys

Responses

Status	Meaning
`200`	Debit schedule (`DebitSchedule`)
`201`	Debit schedule (`DebitSchedule`)
`400`	Error — error shape and codes
`403`	Error — error shape and codes
`404`	Error — error shape and codes
`409`	Error — error shape and codes
`422`	Error — error shape and codes

Fields of `data` (200)

The same fields as under listDebitSchedules.

Example

Set up the recurring debit

POST /v1/debit-schedules

curl -X POST https://sandbox.socialmatterspay.com/v1/debit-schedules \
  -H 'Idempotency-Key: plan_robin_hale' \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "bank_account_id": "0fb9dd42-2bd9-49c1-9c85-68872c5cee57",
  "amount_cents": 4900,
  "interval": "biweekly",
  "start_date": "2026-11-04",
  "total_count": 12,
  "payday_window_days": 3,
  "description": "Shop supplies plan",
  "authorization_text_sha256": "59b344d797487ea4d4830a8a5cb8a5a2d24ffa7a2aca0794228140152dc3c853",
  "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",
  "external_id": "plan_2201"
}'

Response · 201

HTTP 201
Cache-Control: no-store

{
  "data": {
    "id": "ds_b2a7bd4a-cb37-4e32-a367-166bf081fea2",
    "object": "debit_schedule",
    "status": "active",
    "amount_cents": 4900,
    "currency": "USD",
    "interval": "biweekly",
    "start_date": "2026-11-04",
    "total_count": 12,
    "payday_window_days": 3,
    "schedule_description": "every two weeks on Wednesday, starting 2026-11-04, 12 times",
    "description": "Shop supplies plan",
    "entry_code": "WEB",
    "payer_id": "faac6000-d575-4826-af0a-cfa4e0f6bc9a",
    "bank_account_id": "0fb9dd42-2bd9-49c1-9c85-68872c5cee57",
    "authorization_id": "0c1ef864-b5cb-465e-88fc-2f68c61ba5f3",
    "statement_descriptor": null,
    "external_id": "plan_2201",
    "metadata": null,
    "next_debit": {
      "sequence": 1,
      "due_date": "2026-11-04",
      "latest_date": "2026-11-06",
      "planned_date": "2026-11-04",
      "timing": "scheduled_date",
      "status": "scheduled",
      "payment_id": null,
      "failure": null
    },
    "debits": [
      {
        "sequence": 1,
        "due_date": "2026-11-04",
        "latest_date": "2026-11-06",
        "planned_date": "2026-11-04",
        "timing": "scheduled_date",
        "status": "scheduled",
        "payment_id": null,
        "failure": null
      }
    ],
    "cancelled_at": null,
    "cancel_reason": null,
    "created_at": "2026-10-30T00:28:43.764Z"
  }
}

GET /v1/debit-schedules/{id}

Get a debit schedule with every debit so far and the next one

Secret key

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

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`200`	Debit schedule (`DebitSchedule`)
`404`	Error — error shape and codes

Fields of `data` (200)

The same fields as under listDebitSchedules.

Example

A schedule with its first debit taken

GET /v1/debit-schedules/ds_b2a7bd4a-cb37-4e32-a367-166bf081fea2

curl https://sandbox.socialmatterspay.com/v1/debit-schedules/ds_b2a7bd4a-cb37-4e32-a367-166bf081fea2 \
  -H 'Authorization: Bearer sk_sandbox_…'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "ds_b2a7bd4a-cb37-4e32-a367-166bf081fea2",
    "object": "debit_schedule",
    "status": "active",
    "amount_cents": 4900,
    "currency": "USD",
    "interval": "biweekly",
    "start_date": "2026-11-04",
    "total_count": 12,
    "payday_window_days": 3,
    "schedule_description": "every two weeks on Wednesday, starting 2026-11-04, 12 times",
    "description": "Shop supplies plan",
    "entry_code": "WEB",
    "payer_id": "faac6000-d575-4826-af0a-cfa4e0f6bc9a",
    "bank_account_id": "0fb9dd42-2bd9-49c1-9c85-68872c5cee57",
    "authorization_id": "0c1ef864-b5cb-465e-88fc-2f68c61ba5f3",
    "statement_descriptor": null,
    "external_id": "plan_2201",
    "metadata": null,
    "next_debit": {
      "sequence": 2,
      "due_date": "2026-11-18",
      "latest_date": "2026-11-20",
      "planned_date": "2026-11-18",
      "timing": "scheduled_date",
      "status": "scheduled",
      "payment_id": null,
      "failure": null
    },
    "debits": [
      {
        "sequence": 1,
        "due_date": "2026-11-04",
        "latest_date": "2026-11-06",
        "planned_date": "2026-11-04",
        "timing": "scheduled_date",
        "status": "submitted",
        "payment_id": "1cb29cc3-79f4-48b2-bcf7-fec8686e5a0b",
        "failure": null
      },
      {
        "sequence": 2,
        "due_date": "2026-11-18",
        "latest_date": "2026-11-20",
        "planned_date": "2026-11-18",
        "timing": "scheduled_date",
        "status": "scheduled",
        "payment_id": null,
        "failure": null
      }
    ],
    "cancelled_at": null,
    "cancel_reason": null,
    "created_at": "2026-10-30T00:28:43.764Z"
  }
}

POST /v1/debit-schedules/{id}/cancel

Stop a schedule (the payer revoked it, or you end it); revokes its authorization

Secret key

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

No further debit is taken. A debit already sent to the bank is not recalled; void or refund that payment.

Parameters

Field	Notes
`id` requiredpath · string	—

Request body

Field	Notes
`reason`string	up to 200 characters

Responses

Status	Meaning
`200`	Debit schedule (`DebitSchedule`)
`404`	Error — error shape and codes
`409`	Error — error shape and codes

Fields of `data` (200)

The same fields as under listDebitSchedules.

Example

The payer revoked it

POST /v1/debit-schedules/ds_b2a7bd4a-cb37-4e32-a367-166bf081fea2/cancel

curl -X POST https://sandbox.socialmatterspay.com/v1/debit-schedules/ds_b2a7bd4a-cb37-4e32-a367-166bf081fea2/cancel \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "reason": "The payer revoked it by phone"
}'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "ds_b2a7bd4a-cb37-4e32-a367-166bf081fea2",
    "object": "debit_schedule",
    "status": "cancelled",
    "amount_cents": 4900,
    "currency": "USD",
    "interval": "biweekly",
    "start_date": "2026-11-04",
    "total_count": 12,
    "payday_window_days": 3,
    "schedule_description": "every two weeks on Wednesday, starting 2026-11-04, 12 times",
    "description": "Shop supplies plan",
    "entry_code": "WEB",
    "payer_id": "faac6000-d575-4826-af0a-cfa4e0f6bc9a",
    "bank_account_id": "0fb9dd42-2bd9-49c1-9c85-68872c5cee57",
    "authorization_id": "0c1ef864-b5cb-465e-88fc-2f68c61ba5f3",
    "statement_descriptor": null,
    "external_id": "plan_2201",
    "metadata": null,
    "next_debit": null,
    "debits": [
      {
        "sequence": 1,
        "due_date": "2026-11-04",
        "latest_date": "2026-11-06",
        "planned_date": "2026-11-04",
        "timing": "scheduled_date",
        "status": "submitted",
        "payment_id": "1cb29cc3-79f4-48b2-bcf7-fec8686e5a0b",
        "failure": null
      },
      {
        "sequence": 2,
        "due_date": "2026-11-18",
        "latest_date": "2026-11-20",
        "planned_date": "2026-11-18",
        "timing": "scheduled_date",
        "status": "cancelled",
        "payment_id": null,
        "failure": null
      }
    ],
    "cancelled_at": "2026-11-04T03:00:00.801Z",
    "cancel_reason": "The payer revoked it by phone",
    "created_at": "2026-10-30T00:28:43.764Z"
  }
}

The standing authorization's exact words, to show the payer before they agree

Request body

Responses

Fields of data (200)

List debit schedules, newest first, each with its next debit

Parameters

Responses

Fields of each item of data (200)

Set up a recurring debit under one standing authorization

Parameters

Request body

Responses

Fields of data (200)

Get a debit schedule with every debit so far and the next one

Parameters

Responses

Fields of data (200)

Stop a schedule (the payer revoked it, or you end it); revokes its authorization

Parameters

Request body

Responses

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)