Bank accounts · Social Matter Payments API

GET /v1/bank-accounts

List bank accounts (newest 100)

Secret key

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

Parameters

Field	Notes
`payer_id`query · string	—

Responses

Status	Meaning
`200`	Bank accounts

Fields of each item of `data` (200)

Field	Notes
`id`string	—
`object`string = "bank_account"	—
`payer_id`string	—
`account_type`enum	one of `checking`, `savings`
`bank_name`string	—
`last_four`string	—
`owner_name`string	—
`link_method`enum	one of `plaid_instant`, `plaid_match`, `micro_deposit`, `manual`, `sandbox`
`available_balance_cents`integer	A sandbox test account only: the balance the risk checks read
`status`enum	one of `pending_verification`, `verified`, `disconnected`, `failed`
`identity_match_score`integer \| null	—
`signal_score`integer \| null	—
`verified_at`string \| null (date-time)	—
`disconnected_at`string \| null (date-time)	—
`is_tokenized`boolean	The bank gave a tokenized account number, which stops working when the payer's consent ends
`item_health`enum	The bank connection, from Plaid's item webhooks (bank_account.relink_recommended / relink_required). one of `ok`, `login_required`, `consent_expiring`, `disconnect_pending`, `revoked`
`consent_expires_at`string \| null (date-time)	—
`disconnect_at`string \| null (date-time)	—
`debit_block`enum	Set when a debit to this account would fail; POST /v1/payments answers 422 relink_required. one of `access_revoked`, `consent_expired`, `disconnected`,
`owner_changed_from`string \| null	Set when this account's holder name matches none of the payer's earlier accounts: the most recent of them. The merchant also gets bank_account.owner_changed. Names are compared without case, accents, punctuation, initials or Jr/Sr, and one name's words inside the other's count as the same holder.
`created_at`string (date-time)	—

Example

List a payer's bank accounts

GET /v1/bank-accounts

curl https://sandbox.socialmatterspay.com/v1/bank-accounts?payer_id=6427de75-801c-4ac6-95fa-870665d10af3 \
  -H 'Authorization: Bearer sk_sandbox_…'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": [
    {
      "id": "1357923a-53e2-4aa9-a547-a20155759d6c",
      "object": "bank_account",
      "payer_id": "6427de75-801c-4ac6-95fa-870665d10af3",
      "account_type": "checking",
      "bank_name": "Plaid Checking (sandbox)",
      "last_four": "9606",
      "owner_name": "Ana Lopez",
      "link_method": "sandbox",
      "status": "verified",
      "identity_match_score": null,
      "signal_score": null,
      "verified_at": "2026-10-28T00:22:35.485Z",
      "disconnected_at": null,
      "is_tokenized": false,
      "item_health": "ok",
      "consent_expires_at": null,
      "disconnect_at": null,
      "debit_block": null,
      "owner_changed_from": null,
      "created_at": "2026-10-28T00:22:35.485Z"
    }
  ]
}

POST /v1/bank-accounts/link-token

A Plaid Link token for one payer

Secret key

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

Give payer_id, or payer_email to create-or-find the payer. 503 when Plaid is not configured.

Request body

Field	Notes
`payer_id`string	—
`payer_email`string (email)	—
`payer_name`string	—
`payer_ip`string	The payer's IP at checkout; sets private_relay

Responses

Status	Meaning
`201`	Link token
`404`	Error — error shape and codes
`503`	Error — error shape and codes

Fields of `data` (201)

Field	Notes
`object`string = "link_token"	—
`link_token`string	—
`expiration`string (date-time)	—
`payer_id`string	—
`private_relay`boolean \| null	True when payer_ip is an iCloud Private Relay address, which some banks' sign-in pages block; null when not given or unknown

Example

status 503 in this build: Plaid keys are not configured.

Start a Plaid bank sign-in

POST /v1/bank-accounts/link-token

curl -X POST https://sandbox.socialmatterspay.com/v1/bank-accounts/link-token \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "payer_id": "6427de75-801c-4ac6-95fa-870665d10af3"
}'

Response · 503

HTTP 503
Cache-Control: no-store

{
  "error": "plaid_not_configured",
  "message": "Plaid credentials are not configured on this deployment"
}

POST /v1/bank-accounts/exchange

Turn a Plaid public token into a verified bank account

Secret key

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

The account and routing numbers are sealed (ECDH P-256 + AES-256-GCM) before they are stored.

Request body

Field	Notes
`payer_id` requiredstring	—
`public_token` requiredstring	—
`account_id` requiredstring	—
`payer_name`string	Used for Plaid Identity Match

Responses

Status	Meaning
`201`	Bank account (`BankAccount`)
`404`	Error — error shape and codes
`503`	Error — error shape and codes

Fields of `data` (201)

The same fields as under listBankAccounts.

Example

status 503 in this build: Plaid keys are not configured.

Exchange Plaid's public token

POST /v1/bank-accounts/exchange

curl -X POST https://sandbox.socialmatterspay.com/v1/bank-accounts/exchange \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "payer_id": "6427de75-801c-4ac6-95fa-870665d10af3",
  "public_token": "public-sandbox-00000000-0000-0000-0000-000000000000",
  "account_id": "plaid-account-id"
}'

Response · 503

HTTP 503
Cache-Control: no-store

{
  "error": "plaid_not_configured",
  "message": "Plaid credentials are not configured on this deployment"
}

POST /v1/bank-accounts/sandbox-link

Sandbox only — link Plaid's documented test checking account without Plaid keys

Secret key Sandbox only

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

Seals account 9900009606 / routing 011401533 (Plaid's /auth/get example). An optional balance becomes the payer's live balance for risk.

Request body

Field	Notes
`payer_email` requiredstring (email)	—
`payer_name`string	—
`available_balance_cents`integer	at least 0

Responses

Status	Meaning
`201`	Bank account (`BankAccount`)
`404`	Error — error shape and codes

Fields of `data` (201)

The same fields as under listBankAccounts.

Example

Link a sandbox test bank account

POST /v1/bank-accounts/sandbox-link

curl -X POST https://sandbox.socialmatterspay.com/v1/bank-accounts/sandbox-link \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "payer_email": "ana.lopez@example.com",
  "payer_name": "Ana Lopez",
  "available_balance_cents": 250000
}'

Response · 201

HTTP 201
Cache-Control: no-store

{
  "data": {
    "id": "1357923a-53e2-4aa9-a547-a20155759d6c",
    "object": "bank_account",
    "payer_id": "6427de75-801c-4ac6-95fa-870665d10af3",
    "account_type": "checking",
    "bank_name": "Plaid Checking (sandbox)",
    "last_four": "9606",
    "owner_name": "Ana Lopez",
    "link_method": "sandbox",
    "status": "verified",
    "identity_match_score": null,
    "signal_score": null,
    "verified_at": "2026-10-28T00:22:35.485Z",
    "disconnected_at": null,
    "is_tokenized": false,
    "item_health": "ok",
    "consent_expires_at": null,
    "disconnect_at": null,
    "debit_block": null,
    "owner_changed_from": null,
    "created_at": "2026-10-28T00:22:35.485Z",
    "available_balance_cents": 250000
  }
}

POST /v1/bank-accounts/micro-deposits

Link by account and routing number; SMP sends two small credits to confirm

Secret key

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

Request body

Field	Notes
`payer_email` requiredstring (email)	—
`account_number` requiredstring	pattern `^\d{4,17}$`
`routing_number` requiredstring	Must pass the ABA checksum. pattern `^\d{9}$`
`account_type`enum	one of `checking`, `savings`. default `"checking"`
`account_holder_name` requiredstring	—

Responses

Status	Meaning
`201`	Bank account (`BankAccount`)
`400`	Error — error shape and codes
`502`	Error — error shape and codes
`503`	Error — error shape and codes

Fields of `data` (201)

The same fields as under listBankAccounts.

Example

Start micro-deposit verification

POST /v1/bank-accounts/micro-deposits

curl -X POST https://sandbox.socialmatterspay.com/v1/bank-accounts/micro-deposits \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "payer_email": "sam.chen@example.com",
  "account_number": "000123456789",
  "routing_number": "110000000",
  "account_type": "checking",
  "account_holder_name": "Sam Chen"
}'

Response · 201

HTTP 201
Cache-Control: no-store

{
  "data": {
    "id": "88f55d73-0426-4ef9-bd68-319118670a30",
    "object": "bank_account",
    "payer_id": "459cd5c9-9b27-4f89-a937-22716591353e",
    "account_type": "checking",
    "bank_name": "Bank account",
    "last_four": "6789",
    "owner_name": "Sam Chen",
    "link_method": "micro_deposit",
    "status": "pending_verification",
    "identity_match_score": null,
    "signal_score": null,
    "verified_at": null,
    "disconnected_at": null,
    "is_tokenized": false,
    "item_health": "ok",
    "consent_expires_at": null,
    "disconnect_at": null,
    "debit_block": null,
    "owner_changed_from": null,
    "created_at": "2026-10-28T00:22:35.499Z"
  }
}

GET /v1/bank-accounts/{id}

Get a bank account

Secret key

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

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`200`	Bank account (`BankAccount`)
`404`	Error — error shape and codes

Fields of `data` (200)

The same fields as under listBankAccounts.

Example

Get a bank account

GET /v1/bank-accounts/1357923a-53e2-4aa9-a547-a20155759d6c

curl https://sandbox.socialmatterspay.com/v1/bank-accounts/1357923a-53e2-4aa9-a547-a20155759d6c \
  -H 'Authorization: Bearer sk_sandbox_…'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "1357923a-53e2-4aa9-a547-a20155759d6c",
    "object": "bank_account",
    "payer_id": "6427de75-801c-4ac6-95fa-870665d10af3",
    "account_type": "checking",
    "bank_name": "Plaid Checking (sandbox)",
    "last_four": "9606",
    "owner_name": "Ana Lopez",
    "link_method": "sandbox",
    "status": "verified",
    "identity_match_score": null,
    "signal_score": null,
    "verified_at": "2026-10-28T00:22:35.485Z",
    "disconnected_at": null,
    "is_tokenized": false,
    "item_health": "ok",
    "consent_expires_at": null,
    "disconnect_at": null,
    "debit_block": null,
    "owner_changed_from": null,
    "created_at": "2026-10-28T00:22:35.485Z"
  }
}

DELETE /v1/bank-accounts/{id}

Disconnect a bank account (no further debits)

Secret key

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

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`200`	Bank account (`BankAccount`)
`404`	Error — error shape and codes
`409`	Error — error shape and codes

Fields of `data` (200)

The same fields as under listBankAccounts.

Example

Disconnect a bank account

DELETE /v1/bank-accounts/88f55d73-0426-4ef9-bd68-319118670a30

curl -X DELETE https://sandbox.socialmatterspay.com/v1/bank-accounts/88f55d73-0426-4ef9-bd68-319118670a30 \
  -H 'Authorization: Bearer sk_sandbox_…'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "88f55d73-0426-4ef9-bd68-319118670a30",
    "object": "bank_account",
    "payer_id": "459cd5c9-9b27-4f89-a937-22716591353e",
    "account_type": "checking",
    "bank_name": "Bank account",
    "last_four": "6789",
    "owner_name": "Sam Chen",
    "link_method": "micro_deposit",
    "status": "disconnected",
    "identity_match_score": null,
    "signal_score": null,
    "verified_at": "2026-10-28T00:22:35.507Z",
    "disconnected_at": "2026-10-28T00:22:37.694Z",
    "is_tokenized": false,
    "item_health": "ok",
    "consent_expires_at": null,
    "disconnect_at": null,
    "debit_block": null,
    "owner_changed_from": null,
    "created_at": "2026-10-28T00:22:35.499Z"
  }
}

POST /v1/bank-accounts/{id}/verify

Confirm the two micro-deposit amounts; three wrong tries fail the account

Secret key

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

Parameters

Field	Notes
`id` requiredpath · string	—

Request body

Field	Notes
`amounts` requiredarray of integer	at least 2 items. at most 2 items

Responses

Status	Meaning
`200`	Bank account (`BankAccount`)
`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 listBankAccounts.

Example

Confirm the two amounts

POST /v1/bank-accounts/88f55d73-0426-4ef9-bd68-319118670a30/verify

curl -X POST https://sandbox.socialmatterspay.com/v1/bank-accounts/88f55d73-0426-4ef9-bd68-319118670a30/verify \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "amounts": [
    45,
    89
  ]
}'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "88f55d73-0426-4ef9-bd68-319118670a30",
    "object": "bank_account",
    "payer_id": "459cd5c9-9b27-4f89-a937-22716591353e",
    "account_type": "checking",
    "bank_name": "Bank account",
    "last_four": "6789",
    "owner_name": "Sam Chen",
    "link_method": "micro_deposit",
    "status": "verified",
    "identity_match_score": null,
    "signal_score": null,
    "verified_at": "2026-10-28T00:22:35.507Z",
    "disconnected_at": null,
    "is_tokenized": false,
    "item_health": "ok",
    "consent_expires_at": null,
    "disconnect_at": null,
    "debit_block": null,
    "owner_changed_from": null,
    "created_at": "2026-10-28T00:22:35.499Z"
  }
}

List bank accounts (newest 100)

Parameters

Responses

Fields of each item of data (200)

A Plaid Link token for one payer

Request body

Responses

Fields of data (201)

Turn a Plaid public token into a verified bank account

Request body

Responses

Fields of data (201)

Sandbox only — link Plaid's documented test checking account without Plaid keys

Request body

Responses

Fields of data (201)

Link by account and routing number; SMP sends two small credits to confirm

Request body

Responses

Fields of data (201)

Get a bank account

Parameters

Responses

Fields of data (200)

Disconnect a bank account (no further debits)

Parameters

Responses

Fields of data (200)

Confirm the two micro-deposit amounts; three wrong tries fail the account

Parameters

Request body

Responses

Fields of data (200)

Fields of each item of `data` (200)

Fields of `data` (201)

Fields of `data` (201)

Fields of `data` (201)

Fields of `data` (201)

Fields of `data` (200)

Fields of `data` (200)

Fields of `data` (200)