DRAFTThe sandbox is not live yet. Every example here was returned by the platform's code in a test run on 2026-10-28, priced with example fees: no fee amount in them is an SMP price. Paths and fields can change before launch. Live keys are issued only after our bank program is approved.Sandbox not live yet · examples from a test run on 2026-10-28 · example fees

Reference · 4 operations

Invoices

Invoices with their own account number: the customer sends the money from their bank, and the money that lands there is matched to the invoice.

Sandboxhttps://sandbox.socialmatterspay.com
Livehttps://api.socialmatterspay.com
GET /v1/invoices

List invoices, newest first
Secret key

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

Parameters

FieldNotes
limitquery · integer1 to 100. default 25
offsetquery · integerdefault 0
statusquery · stringone of sent, partially_paid, paid, overdue, cancelled

Responses

StatusMeaning
200A page of invoices, without payment instructions
400Error — error shape and codes

Fields of each item of data (200)

FieldNotes
idstring—
objectstring = "invoice"—
statusenumone of sent, partially_paid, paid, overdue, cancelled
amount_centsinteger—
paid_centsinteger—
remaining_centsinteger—
overpaid_centsinteger—
currencystring = "USD"—
customer_namestring—
customer_emailstring—
due_datestring (date)—
descriptionstring | null—
line_itemsarray of objectAs you sent them; they add up to amount_cents. null when the invoice has none
3 child fields
descriptionstringup to 200 characters
quantityinteger1 to 1000000
unit_price_centsinteger0 to 1000000000
external_idstring | null—
fundsobject
4 child fields
received_centsinteger—
booked_centsintegerMoved into the merchant's balance
held_at_bank_centsintegerReceived and still in the invoice's account at the bank
statusenumone of none, held_at_bank, booked
virtual_account_last_fourstring | null—
payment_instructionsobjectOnly on create and GET /v1/invoices/{id}
4 child fields
account_numberstring—
routing_numberstring—
account_typestring = "checking"—
referencestring—
paid_atstring | null (date-time)—
cancelled_atstring | null (date-time)—
overdue_atstring | null (date-time)—
created_atstring (date-time)—

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

Example

List invoices

GET /v1/invoices
curl https://sandbox.socialmatterspay.com/v1/invoices \
  -H 'Authorization: Bearer sk_sandbox_…'
Response · 200
HTTP 200
Cache-Control: no-store

{
  "data": [
    {
      "id": "9e80b109-af15-4764-9a39-0d09aa053140",
      "object": "invoice",
      "status": "cancelled",
      "amount_cents": 64000,
      "paid_cents": 0,
      "remaining_cents": 64000,
      "overpaid_cents": 0,
      "currency": "USD",
      "customer_name": "Acme Wholesale Inc",
      "customer_email": "ap@acme.example",
      "due_date": "2026-11-27",
      "description": null,
      "line_items": null,
      "external_id": "INV-2026-0413",
      "funds": {
        "received_cents": 0,
        "booked_cents": 0,
        "held_at_bank_cents": 0,
        "status": "none"
      },
      "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",
      "object": "invoice",
      "status": "paid",
      "amount_cents": 1850000,
      "paid_cents": 1850000,
      "remaining_cents": 0,
      "overpaid_cents": 0,
      "currency": "USD",
      "customer_name": "Acme Wholesale Inc",
      "customer_email": "ap@acme.example",
      "due_date": "2026-11-27",
      "description": "October shop supplies",
      "line_items": [
        {
          "description": "Shelving units",
          "quantity": 40,
          "unit_price_cents": 42500
        },
        {
          "description": "Delivery and installation",
          "quantity": 1,
          "unit_price_cents": 150000
        }
      ],
      "external_id": "INV-2026-0412",
      "funds": {
        "received_cents": 1850000,
        "booked_cents": 1850000,
        "held_at_bank_cents": 0,
        "status": "booked"
      },
      "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"
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 25,
    "offset": 0,
    "has_more": false
  }
}
POST /v1/invoices

An invoice with its own account number; whatever the customer sends there pays it
Secret key Idempotency-Key required

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

For large business payments: the customer pushes the money from their own bank (an ACH credit or an instant payment) to the invoice's account and routing number, so no debit limit applies. Money is matched by account, so partial payments and overpayments are recorded too (invoice.partially_paid, invoice.paid), and so is money the customer sends after the invoice is paid (invoice.paid again, with received_now_cents and overpaid_cents). Past its due date with money still owed, the invoice becomes overdue once (invoice.overdue). funds says where the money is: received money stays in the invoice's account at the bank, outside the merchant's balance and payouts, until it is booked. payment_instructions (the full account number) is returned here and by GET /v1/invoices/{id} only. The same Idempotency-Key with the same body returns the same invoice (200); with a different body it is a 409.

Parameters

FieldNotes
Idempotency-Key requiredheader · string1–255 characters. printable characters, no spaces; see Idempotency

Request body

FieldNotes
customer_name requiredstringup to 200 characters
customer_email requiredstring (email)—
amount_cents requiredinteger1 to 1000000000
due_date requiredstring (date)Today or later
descriptionstringup to 1000 characters
external_idstringup to 255 characters
line_itemsarray of objectMust add up to amount_cents. at least 1 item. at most 100 items
3 child fields
description requiredstringup to 200 characters
quantity requiredinteger1 to 1000000
unit_price_cents requiredinteger0 to 1000000000

Responses

StatusMeaning
200Invoice (Invoice)
201Invoice (Invoice)
400Error — error shape and codes
403Error — error shape and codes
409Error — error shape and codes

Fields of data (200)

The same fields as under listInvoices.

Example

Invoice a business customer

POST /v1/invoices
curl -X POST https://sandbox.socialmatterspay.com/v1/invoices \
  -H 'Idempotency-Key: inv_2026_0412' \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "customer_name": "Acme Wholesale Inc",
  "customer_email": "ap@acme.example",
  "amount_cents": 1850000,
  "due_date": "2026-11-27",
  "description": "October shop supplies",
  "external_id": "INV-2026-0412",
  "line_items": [
    {
      "description": "Shelving units",
      "quantity": 40,
      "unit_price_cents": 42500
    },
    {
      "description": "Delivery and installation",
      "quantity": 1,
      "unit_price_cents": 150000
    }
  ]
}'
Response · 201
HTTP 201
Cache-Control: no-store

{
  "data": {
    "id": "69fcf9e0-a58f-4891-ac46-3f2a615e070d",
    "object": "invoice",
    "status": "sent",
    "amount_cents": 1850000,
    "paid_cents": 0,
    "remaining_cents": 1850000,
    "overpaid_cents": 0,
    "currency": "USD",
    "customer_name": "Acme Wholesale Inc",
    "customer_email": "ap@acme.example",
    "due_date": "2026-11-27",
    "description": "October shop supplies",
    "line_items": [
      {
        "description": "Shelving units",
        "quantity": 40,
        "unit_price_cents": 42500
      },
      {
        "description": "Delivery and installation",
        "quantity": 1,
        "unit_price_cents": 150000
      }
    ],
    "external_id": "INV-2026-0412",
    "funds": {
      "received_cents": 0,
      "booked_cents": 0,
      "held_at_bank_cents": 0,
      "status": "none"
    },
    "virtual_account_last_four": "6252",
    "paid_at": null,
    "cancelled_at": null,
    "overdue_at": null,
    "created_at": "2026-10-28T00:27:40.662Z",
    "payment_instructions": {
      "account_number": "9434316252",
      "routing_number": "110000000",
      "account_type": "checking",
      "reference": "69fcf9e0-a58f-4891-ac46-3f2a615e070d"
    }
  }
}
GET /v1/invoices/{id}

Get an invoice, with its payment instructions
Secret key

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

Reads the invoice's account at the bank first, so money that just landed shows at once.

Parameters

FieldNotes
id requiredpath · string—

Responses

StatusMeaning
200Invoice (Invoice)
404Error — error shape and codes

Fields of data (200)

The same fields as under listInvoices.

Example

Partly paid, the money held at the bank

GET /v1/invoices/69fcf9e0-a58f-4891-ac46-3f2a615e070d
curl https://sandbox.socialmatterspay.com/v1/invoices/69fcf9e0-a58f-4891-ac46-3f2a615e070d \
  -H 'Authorization: Bearer sk_sandbox_…'
Response · 200
HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "69fcf9e0-a58f-4891-ac46-3f2a615e070d",
    "object": "invoice",
    "status": "partially_paid",
    "amount_cents": 1850000,
    "paid_cents": 1000000,
    "remaining_cents": 850000,
    "overpaid_cents": 0,
    "currency": "USD",
    "customer_name": "Acme Wholesale Inc",
    "customer_email": "ap@acme.example",
    "due_date": "2026-11-27",
    "description": "October shop supplies",
    "line_items": [
      {
        "description": "Shelving units",
        "quantity": 40,
        "unit_price_cents": 42500
      },
      {
        "description": "Delivery and installation",
        "quantity": 1,
        "unit_price_cents": 150000
      }
    ],
    "external_id": "INV-2026-0412",
    "funds": {
      "received_cents": 1000000,
      "booked_cents": 1000000,
      "held_at_bank_cents": 0,
      "status": "booked"
    },
    "virtual_account_last_four": "6252",
    "paid_at": null,
    "cancelled_at": null,
    "overdue_at": null,
    "created_at": "2026-10-28T00:27:40.662Z",
    "payment_instructions": {
      "account_number": "9434316252",
      "routing_number": "110000000",
      "account_type": "checking",
      "reference": "69fcf9e0-a58f-4891-ac46-3f2a615e070d"
    }
  }
}
POST /v1/invoices/{id}/cancel

Cancel an unpaid invoice
Secret key

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

Money that lands after cancellation is still recorded on the invoice, so the merchant can send it back.

Parameters

FieldNotes
id requiredpath · string—

Responses

StatusMeaning
200Invoice (Invoice)
404Error — error shape and codes
409Error — error shape and codes
422Error — error shape and codes

Fields of data (200)

The same fields as under listInvoices.

Example

Cancel an unpaid invoice

POST /v1/invoices/9e80b109-af15-4764-9a39-0d09aa053140/cancel
curl -X POST https://sandbox.socialmatterspay.com/v1/invoices/9e80b109-af15-4764-9a39-0d09aa053140/cancel \
  -H 'Authorization: Bearer sk_sandbox_…'
Response · 200
HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "9e80b109-af15-4764-9a39-0d09aa053140",
    "object": "invoice",
    "status": "cancelled",
    "amount_cents": 64000,
    "paid_cents": 0,
    "remaining_cents": 64000,
    "overpaid_cents": 0,
    "currency": "USD",
    "customer_name": "Acme Wholesale Inc",
    "customer_email": "ap@acme.example",
    "due_date": "2026-11-27",
    "description": null,
    "line_items": null,
    "external_id": "INV-2026-0413",
    "funds": {
      "received_cents": 0,
      "booked_cents": 0,
      "held_at_bank_cents": 0,
      "status": "none"
    },
    "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"
  }
}