Payers · Social Matter Payments API

POST /v1/payers

Create the payer for an email, or return the existing one

Secret key

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

One payer per email per merchant (emails are lowercased). 201 when created, 200 when it already existed.

Request body

Field	Notes
`email` requiredstring (email)	—
`name`string	up to 200 characters
`phone`string	up to 40 characters

Responses

Status	Meaning
`200`	Payer (`Payer`)
`201`	Payer (`Payer`)
`400`	Error — error shape and codes
`401`	Error — error shape and codes

Fields of `data` (200)

Field	Notes
`id`string	—
`object`string = "payer"	—
`email`string	—
`name`string \| null	—
`phone`string \| null	—
`created_at`string (date-time)	—

Examples (2)

Create a payer

POST /v1/payers

curl -X POST https://sandbox.socialmatterspay.com/v1/payers \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "ana.lopez@example.com",
  "name": "Ana Lopez"
}'

Response · 201

HTTP 201
Cache-Control: no-store

{
  "data": {
    "id": "6427de75-801c-4ac6-95fa-870665d10af3",
    "object": "payer",
    "email": "ana.lopez@example.com",
    "name": "Ana Lopez",
    "phone": null,
    "created_at": "2026-10-28T00:22:35.474Z"
  }
}

Same email again returns the same payer

POST /v1/payers

curl -X POST https://sandbox.socialmatterspay.com/v1/payers \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "ana.lopez@example.com"
}'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "6427de75-801c-4ac6-95fa-870665d10af3",
    "object": "payer",
    "email": "ana.lopez@example.com",
    "name": "Ana Lopez",
    "phone": null,
    "created_at": "2026-10-28T00:22:35.474Z"
  }
}

GET /v1/payers/{id}

Get a payer

Secret key

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

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`200`	Payer (`Payer`)
`404`	Error — error shape and codes

Fields of `data` (200)

Field	Notes
`id`string	—
`object`string = "payer"	—
`email`string	—
`name`string \| null	—
`phone`string \| null	—
`created_at`string (date-time)	—

Example

Get a payer

GET /v1/payers/6427de75-801c-4ac6-95fa-870665d10af3

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

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "6427de75-801c-4ac6-95fa-870665d10af3",
    "object": "payer",
    "email": "ana.lopez@example.com",
    "name": "Ana Lopez",
    "phone": null,
    "created_at": "2026-10-28T00:22:35.474Z"
  }
}

GET /v1/payers/{id}/override

The payer's override (404 when there is none)

Secret key

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

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`200`	Payer override (`PayerOverride`)
`404`	Error — error shape and codes

Fields of `data` (200)

Field	Notes
`id`string	—
`object`string = "payer_override"	—
`payer_id`string	—
`reason`string	—
`max_amount_cents`integer \| null	—
`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)	—
`active`boolean	Neither revoked nor expired

Example

The payer's override

GET /v1/payers/6427de75-801c-4ac6-95fa-870665d10af3/override

curl https://sandbox.socialmatterspay.com/v1/payers/6427de75-801c-4ac6-95fa-870665d10af3/override \
  -H 'Authorization: Bearer sk_sandbox_…'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "48b10719-2e66-498e-9ee3-a2580c651ea4",
    "object": "payer_override",
    "payer_id": "6427de75-801c-4ac6-95fa-870665d10af3",
    "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": null,
    "active": true
  }
}

POST /v1/payers/{id}/override

Let one payer past the soft risk checks

Secret key

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

Effective on the payer's next payment; it replaces any override the payer already has. It covers the velocity limits, a high return-risk score, a weak identity or name match, the first-payment cap, a foreign IP, the payer's return rate and a score below the threshold. It never covers a merchant limit, the unauthorized-return pause, a known short balance, an unauthorized return by this payer, or a bank account that must be linked again. Every change is in the audit log, and a payment it let through carries its override_id.

Parameters

Field	Notes
`id` requiredpath · string	—

Request body

Field	Notes
`reason` requiredstring	1–500 characters
`max_amount_cents`integer	A larger payment gets no override. 1 to 99999999
`expires_at`string (date-time)	In the future; without it the override lasts until revoked

Responses

Status	Meaning
`201`	Payer override (`PayerOverride`)
`400`	Error — error shape and codes
`404`	Error — error shape and codes

Fields of `data` (201)

The same fields as under getPayerOverride.

Example

Let a payer past the soft checks, up to an amount

POST /v1/payers/6427de75-801c-4ac6-95fa-870665d10af3/override

curl -X POST https://sandbox.socialmatterspay.com/v1/payers/6427de75-801c-4ac6-95fa-870665d10af3/override \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "reason": "Long-standing customer; large order confirmed by phone",
  "max_amount_cents": 250000,
  "expires_at": "2026-11-27T00:22:38.641Z"
}'

Response · 201

HTTP 201
Cache-Control: no-store

{
  "data": {
    "id": "48b10719-2e66-498e-9ee3-a2580c651ea4",
    "object": "payer_override",
    "payer_id": "6427de75-801c-4ac6-95fa-870665d10af3",
    "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": null,
    "active": true
  }
}

DELETE /v1/payers/{id}/override

Revoke the payer's override, effective on the next payment

Secret key

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

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`200`	Payer override (`PayerOverride`)
`404`	Error — error shape and codes

Fields of `data` (200)

The same fields as under getPayerOverride.

Example

Revoke it

DELETE /v1/payers/6427de75-801c-4ac6-95fa-870665d10af3/override

curl -X DELETE https://sandbox.socialmatterspay.com/v1/payers/6427de75-801c-4ac6-95fa-870665d10af3/override \
  -H 'Authorization: Bearer sk_sandbox_…'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "48b10719-2e66-498e-9ee3-a2580c651ea4",
    "object": "payer_override",
    "payer_id": "6427de75-801c-4ac6-95fa-870665d10af3",
    "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",
    "active": false
  }
}

POST /admin/v1/payers/{id}/override

SMP staff — set a payer's override, by the same rules as the merchant's

SMP staff token

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

Parameters

Field	Notes
`id` requiredpath · string	—

Request body

Field	Notes
`reason` requiredstring	1–500 characters
`max_amount_cents`integer	A larger payment gets no override. 1 to 99999999
`expires_at`string (date-time)	In the future; without it the override lasts until revoked
`set_by` requiredstring	up to 200 characters

Responses

Status	Meaning
`201`	Payer override, with the payer's merchant (`AdminPayerOverride`)
`400`	Error — error shape and codes
`401`	Error — error shape and codes
`404`	Error — error shape and codes

Fields of `data` (201)

Field	Notes
`id`string	—
`object`string = "payer_override"	—
`payer_id`string	—
`reason`string	—
`max_amount_cents`integer \| null	—
`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)	—
`active`boolean	Neither revoked nor expired
`merchant_id`string	—

Example

Set an override (SMP staff)

POST /admin/v1/payers/c5a33620-8024-4315-8bc4-b09ab52d4a86/override

curl -X POST https://sandbox.socialmatterspay.com/admin/v1/payers/c5a33620-8024-4315-8bc4-b09ab52d4a86/override \
  -H 'Authorization: Bearer smp_staff_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "reason": "Identity confirmed by the risk team",
  "set_by": "risk-ops",
  "max_amount_cents": 100000
}'

Response · 201

HTTP 201
Cache-Control: no-store

{
  "data": {
    "id": "b73ed849-bd29-4040-92a2-23a1e7b0494b",
    "object": "payer_override",
    "payer_id": "c5a33620-8024-4315-8bc4-b09ab52d4a86",
    "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": null,
    "active": true,
    "merchant_id": "a5fc4446-e0a0-4260-ac10-e06060393364"
  }
}

POST /admin/v1/payers/{id}/override/revoke

SMP staff — revoke a payer's override

SMP staff token

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

Parameters

Field	Notes
`id` requiredpath · string	—

Request body

Field	Notes
`revoked_by` requiredstring	up to 200 characters

Responses

Status	Meaning
`200`	Payer override, with the payer's merchant (`AdminPayerOverride`)
`400`	Error — error shape and codes
`401`	Error — error shape and codes
`404`	Error — error shape and codes

Fields of `data` (200)

Field	Notes
`id`string	—
`object`string = "payer_override"	—
`payer_id`string	—
`reason`string	—
`max_amount_cents`integer \| null	—
`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)	—
`active`boolean	Neither revoked nor expired
`merchant_id`string	—

Example

Revoke an override (SMP staff)

POST /admin/v1/payers/c5a33620-8024-4315-8bc4-b09ab52d4a86/override/revoke

curl -X POST https://sandbox.socialmatterspay.com/admin/v1/payers/c5a33620-8024-4315-8bc4-b09ab52d4a86/override/revoke \
  -H 'Authorization: Bearer smp_staff_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "revoked_by": "risk-ops"
}'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "b73ed849-bd29-4040-92a2-23a1e7b0494b",
    "object": "payer_override",
    "payer_id": "c5a33620-8024-4315-8bc4-b09ab52d4a86",
    "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",
    "active": false,
    "merchant_id": "a5fc4446-e0a0-4260-ac10-e06060393364"
  }
}

Create the payer for an email, or return the existing one

Request body

Responses

Fields of data (200)

Get a payer

Parameters

Responses

Fields of data (200)

The payer's override (404 when there is none)

Parameters

Responses

Fields of data (200)

Let one payer past the soft risk checks

Parameters

Request body

Responses

Fields of data (201)

Revoke the payer's override, effective on the next payment

Parameters

Responses

Fields of data (200)

SMP staff — set a payer's override, by the same rules as the merchant's

Parameters

Request body

Responses

Fields of data (201)

SMP staff — revoke a payer's override

Parameters

Request body

Responses

Fields of data (200)

Fields of `data` (200)

Fields of `data` (200)

Fields of `data` (200)

Fields of `data` (201)

Fields of `data` (200)

Fields of `data` (201)

Fields of `data` (200)