Dashboard: customers · Social Matter Payments API

GET /portal/api/invoices

Invoices, newest first, with what has been paid

Dashboard session

Host https://app.socialmatterspay.com

Parameters

Field	Notes
`status`query · string	one of `sent`, `partially_paid`, `paid`, `overdue`, `cancelled`
`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	—
`customer_name`string	—
`customer_email`string	—
`amount_cents`integer	—
`paid_cents`integer	—
`booked_cents`integer	Moved into the merchant balance
`status`enum	A draft is never listed. one of `sent`, `partially_paid`, `paid`, `overdue`, `cancelled`
`due_date`string (date)	—
`description`string \| null	—
`external_id`string \| null	—
`virtual_account_last_four`string \| null	—
`paid_at`string \| null (date-time)	—
`cancelled_at`string \| null (date-time)	—
`overdue_at`string \| null (date-time)	—
`created_at`string (date-time)	—

Example

Invoices

GET /portal/api/invoices

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

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": [
    {
      "id": "9d34a1e9-c788-4301-8025-1f403666ff5e",
      "customer_name": "Acme Wholesale Inc",
      "customer_email": "ap@acme.example",
      "amount_cents": 120000,
      "paid_cents": 0,
      "booked_cents": 0,
      "status": "overdue",
      "due_date": "2026-10-28",
      "description": null,
      "external_id": "INV-2026-0414",
      "virtual_account_last_four": "5438",
      "paid_at": null,
      "cancelled_at": null,
      "overdue_at": "2026-10-30T00:28:41.718Z",
      "created_at": "2026-10-28T00:28:41.707Z"
    },
    {
      "id": "9e80b109-af15-4764-9a39-0d09aa053140",
      "customer_name": "Acme Wholesale Inc",
      "customer_email": "ap@acme.example",
      "amount_cents": 64000,
      "paid_cents": 0,
      "booked_cents": 0,
      "status": "cancelled",
      "due_date": "2026-11-27",
      "description": null,
      "external_id": "INV-2026-0413",
      "virtual_account_last_four": "8494",
      "paid_at": null,
      "cancelled_at": "2026-10-28T00:28:41.700Z",
      "overdue_at": null,
      "created_at": "2026-10-28T00:28:41.695Z"
    },
    {
      "id": "69fcf9e0-a58f-4891-ac46-3f2a615e070d",
      "customer_name": "Acme Wholesale Inc",
      "customer_email": "ap@acme.example",
      "amount_cents": 1850000,
      "paid_cents": 1850000,
      "booked_cents": 1850000,
      "status": "paid",
      "due_date": "2026-11-27",
      "description": "October shop supplies",
      "external_id": "INV-2026-0412",
      "virtual_account_last_four": "6252",
      "paid_at": "2026-10-28T00:28:41.687Z",
      "cancelled_at": null,
      "overdue_at": null,
      "created_at": "2026-10-28T00:27:40.662Z"
    }
  ],
  "total": 3,
  "limit": 50,
  "offset": 0
}

GET /portal/api/payers/overrides

Payer overrides, live first, each active, expired or revoked

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	—
`payer_id`string	—
`payer_name`string \| null	—
`payer_email`string	—
`reason`string	—
`max_amount_cents`integer \| null	Most one payment may be; null for no limit
`expires_at`string \| null (date-time)	—
`created_by_type`enum	one of `merchant`, `admin`
`created_at`string (date-time)	—
`revoked_at`string \| null (date-time)	—
`revoked_by_type`enum	one of `merchant`, `admin`,
`state`enum	The test the payment path applies: live until revoked or past its expiry. one of `active`, `expired`, `revoked`

Example

Payers let past the soft risk checks

GET /portal/api/payers/overrides

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

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": [
    {
      "id": "b73ed849-bd29-4040-92a2-23a1e7b0494b",
      "payer_id": "c5a33620-8024-4315-8bc4-b09ab52d4a86",
      "payer_name": "Taylor Reed",
      "payer_email": "taylor.reed@example.com",
      "reason": "Identity confirmed by the risk team",
      "max_amount_cents": 100000,
      "expires_at": null,
      "created_by_type": "admin",
      "created_at": "2026-10-28T00:27:40.653Z",
      "revoked_at": "2026-10-28T00:27:40.655Z",
      "revoked_by_type": "admin",
      "state": "revoked"
    },
    {
      "id": "48b10719-2e66-498e-9ee3-a2580c651ea4",
      "payer_id": "6427de75-801c-4ac6-95fa-870665d10af3",
      "payer_name": "Ana Lopez",
      "payer_email": "ana.lopez@example.com",
      "reason": "Long-standing customer; large order confirmed by phone",
      "max_amount_cents": 250000,
      "expires_at": "2026-11-27T00:22:38.641Z",
      "created_by_type": "merchant",
      "created_at": "2026-10-28T00:27:40.643Z",
      "revoked_at": "2026-10-28T00:27:40.648Z",
      "revoked_by_type": "merchant",
      "state": "revoked"
    }
  ],
  "as_of": "2026-11-04T03:01:24.796Z"
}

GET /portal/api/payers/bank-health

Payers' bank links that need relinking, required or recommended

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	The bank account
`payer_id`string	—
`payer_name`string \| null	—
`payer_email`string	—
`bank_name`string	—
`last_four`string	—
`is_tokenized`enum	1 when the bank gave a tokenized account number, which stops working when the payer's consent ends. one of `0`, `1`
`item_health`enum	Only accounts that are not ok are listed. one of `login_required`, `consent_expiring`, `disconnect_pending`, `revoked`
`consent_expires_at`string \| null (date-time)	—
`disconnect_at`string \| null (date-time)	—
`item_health_updated_at`string \| null (date-time)	—
`debit_block`enum	Set when a debit to the account would fail. one of `access_revoked`, `consent_expired`, `disconnected`,
`relink`enum	required: the account can no longer be debited; recommended: it still can. one of `required`, `recommended`
`message`string \| null	What to tell the payer; null when relinking is only recommended

Example

Payers' bank connections that need attention

GET /portal/api/payers/bank-health

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

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": [],
  "as_of": "2026-11-04T03:01:24.798Z"
}

GET /portal/api/debit-schedules

Recurring debit schedules, as GET /v1/debit-schedules answers the merchant

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

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 Number of debits; null until revoked

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

next_debitobject | null

The next debit still to go; null when none

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	—

cancelled_atstring | null (date-time) —

cancel_reasonstring | null —

created_atstring (date-time) —

payerobject | null

null when the payer is not found

2 child fields

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

bank_accountobject | null

null when the bank account is not found

2 child fields

`bank_name`string \| null	—
`last_four`string	—

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

Example

Recurring debits

GET /portal/api/debit-schedules

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

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,
      "cancelled_at": "2026-11-04T03:00:00.801Z",
      "cancel_reason": "The payer revoked it by phone",
      "created_at": "2026-10-30T00:28:43.764Z",
      "payer": {
        "name": "Robin Hale",
        "email": "robin.hale@example.com"
      },
      "bank_account": {
        "bank_name": "Plaid Checking (sandbox)",
        "last_four": "9606"
      }
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 25,
    "offset": 0,
    "has_more": false
  }
}

GET /portal/api/debit-schedules/{id}

One debit schedule with its runs

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

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 Number of debits; null until revoked

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

next_debitobject | null The next debit still to go; null when none Its fields are listed under portalDebitSchedules · next_debit.

cancelled_atstring | null (date-time) —

cancel_reasonstring | null —

created_atstring (date-time) —

payerobject | null

null when the payer is not found

2 child fields

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

bank_accountobject | null

null when the bank account is not found

2 child fields

`bank_name`string \| null	—
`last_four`string	—

debitsarray of object Every debit so far and the next Its fields are listed under portalDebitSchedules · next_debit.

Example

One recurring debit and its runs

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

curl https://app.socialmatterspay.com/portal/api/debit-schedules/ds_b2a7bd4a-cb37-4e32-a367-166bf081fea2 \
  -H 'Authorization: Bearer portal_session_token'

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",
    "payer": {
      "name": "Robin Hale",
      "email": "robin.hale@example.com"
    },
    "bank_account": {
      "bank_name": "Plaid Checking (sandbox)",
      "last_four": "9606"
    }
  }
}

GET /portal/api/payday-aware-debits

Whether payday-aware debits are on for this account

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 = "payday_aware_debits" —

enabledboolean —

applies_tostring = "debit_schedules" —

max_window_daysobject

The most days a debit may move after its scheduled date, by interval

3 child fields

`weekly`integer	—
`biweekly`integer	—
`monthly`integer	—

Example

Payday-aware debits: on or off

GET /portal/api/payday-aware-debits

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

Response · 200

HTTP 200
Cache-Control: no-store

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

PUT /portal/api/payday-aware-debits

Turn payday-aware debits on or off (audit-logged with the login that changed it)

Dashboard session

Host https://app.socialmatterspay.com

Request body

Field	Notes
`enabled` requiredboolean	—

Responses

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

Fields of `data` (200)

Field Notes

objectstring = "payday_aware_debits" —

enabledboolean —

applies_tostring = "debit_schedules" —

max_window_daysobject

The most days a debit may move after its scheduled date, by interval

3 child fields

`weekly`integer	—
`biweekly`integer	—
`monthly`integer	—

Example

Turn payday-aware debits on

PUT /portal/api/payday-aware-debits

curl -X PUT https://app.socialmatterspay.com/portal/api/payday-aware-debits \
  -H 'Authorization: Bearer portal_session_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "enabled": true
}'

Response · 200

HTTP 200
Cache-Control: no-store

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

GET /portal/api/payer-imports

Payer imports (customers invited to link their bank) and their funnel

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

idstring —

objectstring = "payer_import" —

sourcestring = "provider_migration" —

landing_urlstring —

incentivestring | null —

rows_receivedinteger —

invites_createdinteger —

skippedobject

Rows not invited, by reason

4 child fields

`duplicate_in_list`integer	—
`opted_out`integer	—
`already_invited`integer	—
`already_connected`integer	—

funnelobject

8 child fields

`invited`integer	—
`queued`integer	—
`sent`integer	—
`clicked`integer	—
`bank_connected`integer	Connected a bank with you after the invite
`paid`integer	Paid you by bank after the invite
`opted_out`integer	—
`failed`integer	—

created_atstring (date-time) —

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

Example

Customer invitations

GET /portal/api/payer-imports

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

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": [
    {
      "id": "pi_b741ef63-34c4-4570-be8b-24c71d704c80",
      "object": "payer_import",
      "source": "provider_migration",
      "landing_url": "https://northwind.example/pay-by-bank",
      "incentive": "Save 5% when you pay by bank",
      "rows_received": 2,
      "invites_created": 2,
      "skipped": {},
      "funnel": {
        "invited": 2,
        "queued": 0,
        "sent": 2,
        "clicked": 1,
        "bank_connected": 0,
        "paid": 0,
        "opted_out": 1,
        "failed": 0
      },
      "created_at": "2026-11-04T03:00:00.806Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 25,
    "offset": 0,
    "has_more": false
  }
}

GET /portal/api/payer-imports/{id}

One payer import

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)

The same fields as under portalPayerImports.

Example

One invitation batch

GET /portal/api/payer-imports/pi_b741ef63-34c4-4570-be8b-24c71d704c80

curl https://app.socialmatterspay.com/portal/api/payer-imports/pi_b741ef63-34c4-4570-be8b-24c71d704c80 \
  -H 'Authorization: Bearer portal_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "pi_b741ef63-34c4-4570-be8b-24c71d704c80",
    "object": "payer_import",
    "source": "provider_migration",
    "landing_url": "https://northwind.example/pay-by-bank",
    "incentive": "Save 5% when you pay by bank",
    "rows_received": 2,
    "invites_created": 2,
    "skipped": {},
    "funnel": {
      "invited": 2,
      "queued": 0,
      "sent": 2,
      "clicked": 1,
      "bank_connected": 0,
      "paid": 0,
      "opted_out": 1,
      "failed": 0
    },
    "created_at": "2026-11-04T03:00:00.806Z"
  }
}

GET /portal/api/payer-imports/{id}/invites

The invites of one payer import and what came of each

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 each item of `data` (200)

Field	Notes
`id`string	—
`object`string = "payer_invite"	—
`import_id`string	—
`payer_id`string	—
`email`string	—
`name`string \| null	—
`status`enum	one of `queued`, `sent`, `opted_out`, `failed`
`sent_at`string \| null (date-time)	—
`clicked_at`string \| null (date-time)	—
`click_count`integer	—
`bank_connected`boolean	—
`paid`boolean	—
`opted_out_at`string \| null (date-time)	—
`created_at`string (date-time)	—

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

Example

A batch's invitations, one by one

GET /portal/api/payer-imports/pi_b741ef63-34c4-4570-be8b-24c71d704c80/invites

curl https://app.socialmatterspay.com/portal/api/payer-imports/pi_b741ef63-34c4-4570-be8b-24c71d704c80/invites \
  -H 'Authorization: Bearer portal_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": [
    {
      "id": "inv_74c3b994-310e-44ae-82b9-af1a873e734c",
      "object": "payer_invite",
      "import_id": "pi_b741ef63-34c4-4570-be8b-24c71d704c80",
      "payer_id": "ac93ed22-86f2-403a-99f2-10d4267c5bdf",
      "email": "ivy.chen@example.com",
      "name": "Ivy Chen",
      "status": "opted_out",
      "sent_at": "2026-11-04T03:00:00.811Z",
      "clicked_at": null,
      "click_count": 0,
      "bank_connected": false,
      "paid": false,
      "opted_out_at": "2026-11-04T03:00:00.830Z",
      "created_at": "2026-11-04T03:00:00.806Z"
    },
    {
      "id": "inv_6f0994b7-d21e-45af-86ec-8dcde15f88e4",
      "object": "payer_invite",
      "import_id": "pi_b741ef63-34c4-4570-be8b-24c71d704c80",
      "payer_id": "145ab697-b38a-44f1-a84b-b97c17941bdf",
      "email": "kai.moreno@example.com",
      "name": "Kai Moreno",
      "status": "sent",
      "sent_at": "2026-11-04T03:00:00.811Z",
      "clicked_at": "2026-11-04T03:00:00.819Z",
      "click_count": 1,
      "bank_connected": false,
      "paid": false,
      "opted_out_at": null,
      "created_at": "2026-11-04T03:00:00.806Z"
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 25,
    "offset": 0,
    "has_more": false
  }
}

Invoices, newest first, with what has been paid

Parameters

Responses

Fields of each item of data (200)

Payer overrides, live first, each active, expired or revoked

Responses

Fields of each item of data (200)

Payers' bank links that need relinking, required or recommended

Responses

Fields of each item of data (200)

Recurring debit schedules, as GET /v1/debit-schedules answers the merchant

Responses

Fields of each item of data (200)

One debit schedule with its runs

Parameters

Responses

Fields of data (200)

Whether payday-aware debits are on for this account

Responses

Fields of data (200)

Turn payday-aware debits on or off (audit-logged with the login that changed it)

Request body

Responses

Fields of data (200)

Payer imports (customers invited to link their bank) and their funnel

Responses

Fields of each item of data (200)

One payer import

Parameters

Responses

Fields of data (200)

The invites of one payer import and what came of each

Parameters

Responses

Fields of each item 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 each item 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 each item of `data` (200)