Returns · Social Matter Payments API

GET /v1/returns

List returns

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`
`category`query · string	one of `nsf`, `admin`, `unauthorized`
`netted`query · string	one of `true`, `false`

Responses

Status	Meaning
`200`	A page of returns

Fields of each item of `data` (200)

Field	Notes
`id`string	—
`object`string = "return"	—
`payment_id`string	—
`amount_cents`integer	—
`return_code`string	—
`return_reason`string	—
`category`enum	one of `nsf`, `admin`, `unauthorized`
`netted`boolean	—
`netted_from_payout_id`string \| null	—
`evidence_url`string \| null	—
`covered`boolean	Bounce Protection pays this return back from SMP's reserve (R01 or R09 on a covered payment); the merchant keeps the order paid
`covered_cents`integer	What the cover pays: the returned amount up to the payment's cap; 0 when not covered
`external_order_id`string \| null	—
`returned_at`string (date-time)	—
`created_at`string (date-time)	—

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

Example

List returns

GET /v1/returns

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

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": [
    {
      "id": "cf78dfa0-3095-4c6b-aab7-e7fd7a67d3c0",
      "object": "return",
      "payment_id": "b17067cf-5562-4448-a039-3149a0ccd6cc",
      "amount_cents": 4200,
      "return_code": "R01",
      "return_reason": "Insufficient Funds",
      "category": "nsf",
      "netted": false,
      "netted_from_payout_id": null,
      "evidence_url": null,
      "covered": false,
      "covered_cents": 0,
      "external_order_id": "order_10485",
      "returned_at": "2026-10-28T00:24:38.640Z",
      "created_at": "2026-10-28T00:27:38.650Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 25,
    "offset": 0,
    "has_more": false
  }
}

GET /v1/returns/summary

Return counts and rates against the Nacha thresholds

Secret key

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

Responses

Status	Meaning
`200`	Summary

Fields of `data` (200)

Field Notes

total_returnsinteger —

nsf_countinteger —

admin_countinteger —

unauthorized_countinteger —

total_return_centsinteger —

unnetted_centsinteger —

debits_originatedinteger —

overall_return_ratenumber —

unauthorized_return_ratenumber —

nacha_unauthorized_ceilingnumber —

merchant_pause_thresholdnumber —

nacha_60_dayobject

The rates SMP acts on, by Nacha's method over the preceding 60 days (the lifetime figures above are for reference)

11 child fields

window_startstring (date-time) —

window_endstring (date-time) —

debits_originatedinteger —

unauthorized_returnsinteger —

administrative_returnsinteger —

total_returnsinteger —

unauthorized_return_ratenumber | null —

administrative_return_ratenumber | null —

overall_return_ratenumber | null —

levelsobject

3 child fields

`unauthorized`enum	one of `compliant`, `warning`, `critical`, `breach`
`administrative`enum	one of `compliant`, `warning`, `critical`, `breach`
`overall`enum	one of `compliant`, `warning`, `critical`, `breach`

levelenum one of compliant, warning, critical, breach

Examples (2)

Return rates

GET /v1/returns/summary

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

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "total_returns": 1,
    "nsf_count": 1,
    "admin_count": 0,
    "unauthorized_count": 0,
    "total_return_cents": 4200,
    "unnetted_cents": 4200,
    "debits_originated": 2,
    "overall_return_rate": 0.5,
    "unauthorized_return_rate": 0,
    "nacha_unauthorized_ceiling": 0.005,
    "merchant_pause_threshold": 0.003,
    "nacha_60_day": {
      "window_start": "2026-08-29T00:27:38.668Z",
      "window_end": "2026-10-28T00:27:38.668Z",
      "debits_originated": 2,
      "unauthorized_returns": 0,
      "administrative_returns": 0,
      "total_returns": 1,
      "unauthorized_return_rate": 0,
      "administrative_return_rate": 0,
      "overall_return_rate": 0.5,
      "levels": {
        "unauthorized": "compliant",
        "administrative": "compliant",
        "overall": "breach"
      },
      "level": "breach"
    }
  }
}

Return rates after an unauthorized return

GET /v1/returns/summary

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

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "total_returns": 1,
    "nsf_count": 0,
    "admin_count": 0,
    "unauthorized_count": 1,
    "total_return_cents": 3300,
    "unnetted_cents": 3300,
    "debits_originated": 1,
    "overall_return_rate": 1,
    "unauthorized_return_rate": 1,
    "nacha_unauthorized_ceiling": 0.005,
    "merchant_pause_threshold": 0.003,
    "nacha_60_day": {
      "window_start": "2026-08-29T00:26:38.758Z",
      "window_end": "2026-10-28T00:26:38.758Z",
      "debits_originated": 1,
      "unauthorized_returns": 1,
      "administrative_returns": 0,
      "total_returns": 1,
      "unauthorized_return_rate": 1,
      "administrative_return_rate": 0,
      "overall_return_rate": 1,
      "levels": {
        "unauthorized": "breach",
        "administrative": "compliant",
        "overall": "breach"
      },
      "level": "breach"
    }
  }
}

GET /v1/returns/{id}

Get a return

Secret key

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

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`200`	The return
`404`	Error — error shape and codes

Fields of `data` (200)

The same fields as under listReturns.

Example

Get a return

GET /v1/returns/cf78dfa0-3095-4c6b-aab7-e7fd7a67d3c0

curl https://sandbox.socialmatterspay.com/v1/returns/cf78dfa0-3095-4c6b-aab7-e7fd7a67d3c0 \
  -H 'Authorization: Bearer sk_sandbox_…'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "cf78dfa0-3095-4c6b-aab7-e7fd7a67d3c0",
    "object": "return",
    "payment_id": "b17067cf-5562-4448-a039-3149a0ccd6cc",
    "amount_cents": 4200,
    "return_code": "R01",
    "return_reason": "Insufficient Funds",
    "category": "nsf",
    "netted": false,
    "netted_from_payout_id": null,
    "evidence_url": null,
    "covered": false,
    "covered_cents": 0,
    "external_order_id": "order_10485",
    "returned_at": "2026-10-28T00:24:38.640Z",
    "created_at": "2026-10-28T00:27:38.650Z"
  }
}

GET /v1/returns/{id}/evidence

The dispute evidence packet of an unauthorized return

Secret key

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

The authorization the payer gave (text, time, IP, user agent), the payment and the bank account's last four.

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`200`	Evidence packet
`404`	Error — error shape and codes

Fields of the response (200)

Field Notes

returnobject

4 child fields

`id`string	—
`code`string	—
`reason`string	—
`returned_at`string (date-time)	—

paymentobject

7 child fields

`id`string	—
`amount_cents`integer	—
`entry_code`enum	one of `WEB`, `PPD`, `CCD`, `TEL`
`statement_descriptor`string	—
`external_order_id`string \| null	—
`created_at`string (date-time)	—
`settled_at`string \| null (date-time)	—

authorizationobject | null

The authorization the payer gave, word for word; null if its record is missing

7 child fields

`authorization_text`string	The exact words the payer agreed to
`ip_address`string	—
`user_agent`string \| null	—
`consent_timestamp`string (date-time)	The moment the payer agreed
`entry_code`enum	one of `WEB`, `PPD`, `CCD`, `TEL`
`frequency`enum	one of `one_time`, `recurring`, `variable`
`expires_at`string (date-time)	—

bank_accountobject | null

The payer's bank account as SMP holds it (never the full number); null if its record is missing

5 child fields

`last_four`string	—
`owner_name`string	—
`link_method`enum	one of `plaid_instant`, `plaid_match`, `micro_deposit`, `manual`, `sandbox`
`identity_match_score`integer \| null	Plaid Identity Match, 0 to 100
`verified_at`string \| null (date-time)	—

Example

An unauthorized return's evidence packet

GET /v1/returns/e1c07144-04d7-4196-9b40-4d528eb48f74/evidence

curl https://sandbox.socialmatterspay.com/v1/returns/e1c07144-04d7-4196-9b40-4d528eb48f74/evidence \
  -H 'Authorization: Bearer sk_sandbox_…'

Response · 200

HTTP 200
Cache-Control: private, no-store

{
  "return": {
    "id": "e1c07144-04d7-4196-9b40-4d528eb48f74",
    "code": "R10",
    "reason": "Customer Advises Not Authorized",
    "returned_at": "2026-10-28T00:23:38.732Z"
  },
  "payment": {
    "id": "3078ebdd-da4d-492a-9050-f2bcc55a14ea",
    "amount_cents": 3300,
    "entry_code": "WEB",
    "statement_descriptor": "LAKESIDE",
    "external_order_id": "order_20311",
    "created_at": "2026-10-28T00:22:37.714Z",
    "settled_at": "2026-10-28T00:23:37.717Z"
  },
  "authorization": {
    "authorization_text": "By completing this payment, you authorize Lakeside Outfitters to initiate a one-time electronic debit of $33.00 from your bank account ending in 9606. You may revoke this authorization at any time by contacting Lakeside Outfitters, with the understanding that it may take up to 3 business days to process.",
    "ip_address": "203.0.113.7",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6) AppleWebKit/605.1.15 Safari/605.1.15",
    "consent_timestamp": "2026-10-28T00:22:37.714Z",
    "entry_code": "WEB",
    "frequency": "one_time",
    "expires_at": "2028-10-27T12:22:37.714Z"
  },
  "bank_account": {
    "last_four": "9606",
    "owner_name": "Riley Ng",
    "link_method": "sandbox",
    "identity_match_score": null,
    "verified_at": "2026-10-28T00:22:37.706Z"
  }
}

List returns

Parameters

Responses

Fields of each item of data (200)

Return counts and rates against the Nacha thresholds

Responses

Fields of data (200)

Get a return

Parameters

Responses

Fields of data (200)

The dispute evidence packet of an unauthorized return

Parameters

Responses

Fields of the response (200)

Fields of each item of `data` (200)

Fields of `data` (200)

Fields of `data` (200)