Payer imports · Social Matter Payments API

GET /v1/payer-imports

List imports, newest first, each with its funnel

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`

Responses

Status	Meaning
`200`	A page of imports
`400`	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

List imports

GET /v1/payer-imports

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

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": 0,
        "bank_connected": 0,
        "paid": 0,
        "opted_out": 0,
        "failed": 0
      },
      "created_at": "2026-11-04T03:00:00.806Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 25,
    "offset": 0,
    "has_more": false
  }
}

POST /v1/payer-imports

Import your own customer list and invite each customer to connect their bank

Secret key Idempotency-Key required

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

Each customer gives an email and, optionally, a name; any other field is refused (customer_data_refused), because customer or account IDs, bank details and tokens from another provider must never be uploaded. The three attestations are required and kept with the import. Skipped, with the reason counted: a repeat in the list, a customer who opted out of your invites, one already invited, one whose bank is already connected. landing_url must be on your own site; an invite's link counts the click, then goes there. An account excluded from migration is refused (migration_excluded). In the sandbox invites go to the sandbox outbox; elsewhere they wait as queued until the invite email is live. The same Idempotency-Key with the same body returns the same import (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

source requiredstring = "provider_migration" —

landing_url requiredstring The https address of your own page where customers pay by bank

incentivestring Your own offer, shown in the invite, e.g. "Save 5% when you pay by bank". up to 80 characters

attestation requiredobject

3 child fields

`owns_list` requiredboolean = true	These are your own customers
`may_email` requiredboolean = true	You have their consent to be emailed
`not_from_previous_provider` requiredboolean = true	None of this came from another provider's systems (IDs, bank details, tokens)

customers requiredarray of object

at least 1 item. at most 1000 items

2 child fields

`email` requiredstring (email)	—
`name`string	up to 200 characters

Responses

Status	Meaning
`200`	Payer import (`PayerImport`)
`201`	Payer import (`PayerImport`)
`400`	Error — error shape and codes
`403`	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 listPayerImports.

Example

Invite your own customers

POST /v1/payer-imports

curl -X POST https://sandbox.socialmatterspay.com/v1/payer-imports \
  -H 'Idempotency-Key: import_2026_10' \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "source": "provider_migration",
  "landing_url": "https://northwind.example/pay-by-bank",
  "incentive": "Save 5% when you pay by bank",
  "attestation": {
    "owns_list": true,
    "may_email": true,
    "not_from_previous_provider": true
  },
  "customers": [
    {
      "email": "kai.moreno@example.com",
      "name": "Kai Moreno"
    },
    {
      "email": "ivy.chen@example.com",
      "name": "Ivy Chen"
    }
  ]
}'

Response · 201

HTTP 201
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": 2,
      "sent": 0,
      "clicked": 0,
      "bank_connected": 0,
      "paid": 0,
      "opted_out": 0,
      "failed": 0
    },
    "created_at": "2026-11-04T03:00:00.806Z"
  }
}

GET /v1/payer-imports/{id}

An import and its funnel

Secret key

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

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

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

Fields of `data` (200)

The same fields as under listPayerImports.

Example

The import and its funnel

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

curl https://sandbox.socialmatterspay.com/v1/payer-imports/pi_b741ef63-34c4-4570-be8b-24c71d704c80 \
  -H 'Authorization: Bearer sk_sandbox_…'

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": 0,
      "failed": 0
    },
    "created_at": "2026-11-04T03:00:00.806Z"
  }
}

GET /v1/payer-imports/{id}/invites

The import's invites, each with where its customer got to

Secret key

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

Parameters

Field	Notes
`id` requiredpath · string	—
`limit`query · integer	1 to 100. default `25`
`offset`query · integer	default `0`
`status`query · string	one of `queued`, `sent`, `opted_out`, `failed`

Responses

Status	Meaning
`200`	A page of invites
`400`	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

The import's invites

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

curl https://sandbox.socialmatterspay.com/v1/payer-imports/pi_b741ef63-34c4-4570-be8b-24c71d704c80/invites \
  -H 'Authorization: Bearer sk_sandbox_…'

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": "sent",
      "sent_at": "2026-11-04T03:00:00.811Z",
      "clicked_at": null,
      "click_count": 0,
      "bank_connected": false,
      "paid": false,
      "opted_out_at": null,
      "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
  }
}

GET /i/{token}

The invite link a customer clicks; counts the click and redirects to the merchant's Pay by bank page

No auth

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

Parameters

Field	Notes
`token` requiredpath · string	—

Responses

Status	Meaning
`302`	To the import's landing_url, with no Referer
`404`	Error — error shape and codes

Example

The customer opens the invite

GET /i/payer_invite_token

curl https://sandbox.socialmatterspay.com/i/payer_invite_token

Response · 302

HTTP 302
Location: https://northwind.example/pay-by-bank
Cache-Control: no-store

GET /i/{token}/unsubscribe

Asks the customer to confirm they want no more invites (a page with one button)

No auth

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

Parameters

Field	Notes
`token` requiredpath · string	—

Responses

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

Example

The customer asks for no more invites

GET /i/payer_invite_token/unsubscribe

curl https://sandbox.socialmatterspay.com/i/payer_invite_token/unsubscribe

Response · 200

HTTP 200
Content-Type: text/html; charset=utf-8
Cache-Control: no-store

(an HTML page, 680 bytes)

POST /i/{token}/unsubscribe

No more invites from this merchant to this address (the page's button, and RFC 8058 one-click unsubscribe)

No auth

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

Parameters

Field	Notes
`token` requiredpath · string	—

Responses

Status	Meaning
`200`	Opted out
`404`	Error — error shape and codes

Example

They confirm

POST /i/payer_invite_token/unsubscribe

curl -X POST https://sandbox.socialmatterspay.com/i/payer_invite_token/unsubscribe

Response · 200

HTTP 200
Content-Type: text/plain; charset=utf-8
Cache-Control: no-store

Done. Northwind Supply won't send you more invites.

List imports, newest first, each with its funnel

Parameters

Responses

Fields of each item of data (200)

Import your own customer list and invite each customer to connect their bank

Parameters

Request body

Responses

Fields of data (200)

An import and its funnel

Parameters

Responses

Fields of data (200)

The import's invites, each with where its customer got to

Parameters

Responses

Fields of each item of data (200)

The invite link a customer clicks; counts the click and redirects to the merchant's Pay by bank page

Parameters

Responses

Asks the customer to confirm they want no more invites (a page with one button)

Parameters

Responses

No more invites from this merchant to this address (the page's button, and RFC 8058 one-click unsubscribe)

Parameters

Responses

Fields of each item of `data` (200)

Fields of `data` (200)

Fields of `data` (200)

Fields of each item of `data` (200)