Checkout sessions · Social Matter Payments API

POST /v1/checkout-sessions

Open a checkout session for the drop-in Pay by bank button

Secret key Idempotency-Key required

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

Call it from your server with your secret key, then give the session's id and client_secret to SMP.mount() on your checkout page (the script is GET /js/v1/smp.js). The browser can use the session only from allowed_origin, only with the client secret, and only until expires_at. The debit it asks for is a WEB payment like any other, authorized before debit, with metadata.checkout_session_id set. A declined attempt leaves the session open for another bank account; one approved payment completes it. The same Idempotency-Key with the same body returns the same session (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
`amount_cents` requiredinteger	1 to 99999999
`payer_email` requiredstring (email)	—
`payer_name`string	up to 200 characters
`allowed_origin` requiredstring	The https origin of your checkout page, e.g. https://shop.example.com (http://localhost in the sandbox)
`statement_descriptor`string	pattern `^[A-Za-z0-9 .&-]{1,12}$`
`external_order_id`string	up to 255 characters
`metadata`object	at most 19 keys
`expires_in_seconds`integer	300 to 86400. default `1800`
`site_id`string	The site its payment belongs to (a site's key sets its own)

Responses

Status	Meaning
`200`	Checkout session (`CheckoutSession`)
`201`	Checkout session (`CheckoutSession`)
`400`	Error — error shape and codes
`403`	Error — error shape and codes
`409`	Error — error shape and codes

Fields of `data` (200)

Field Notes

idstring —

objectstring = "checkout_session" —

statusenum one of open, processing, complete, expired, cancelled

amount_centsinteger —

currencystring = "USD" —

payer_emailstring —

payer_namestring | null —

allowed_originstring —

statement_descriptorstring | null —

external_order_idstring | null —

metadataobject | null Your own keys and values, as you sent them; null when there are none. The payment the session makes carries them, plus checkout_session_id. at most 19 keys

site_idstring | null —

client_secretstring For SMP.mount() on your checkout page; never your secret key

paymentobject | null

The payment that completed it

3 child fields

`id`string	—
`status`enum	Forward only. declined, returned, voided and refunded are terminal. A payment SMP holds for review before any debit (a merchant whose return rates are at the critical level, above $200) is answered 201 and stays pending_authorization until SMP approves it (payment.authorized follows) or declines it (payment.declined). one of `pending_authorization`, `authorized`, `submitted`, `settled`, `released`, `paid_out`, `declined`, `returned`, `voided`, `refunded`
`amount_cents`integer	—

last_attemptobject | null

The latest attempt, declined ones included

3 child fields

`id`string	—
`status`enum	Forward only. declined, returned, voided and refunded are terminal. A payment SMP holds for review before any debit (a merchant whose return rates are at the critical level, above $200) is answered 201 and stays pending_authorization until SMP approves it (payment.authorized follows) or declines it (payment.declined). one of `pending_authorization`, `authorized`, `submitted`, `settled`, `released`, `paid_out`, `declined`, `returned`, `voided`, `refunded`
`amount_cents`integer	—

expires_atstring (date-time) —

completed_atstring | null (date-time) —

created_atstring (date-time) —

Example

Open a checkout session

POST /v1/checkout-sessions

curl -X POST https://sandbox.socialmatterspay.com/v1/checkout-sessions \
  -H 'Idempotency-Key: order_10511' \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount_cents": 6400,
  "payer_email": "taylor.reed@example.com",
  "payer_name": "Taylor Reed",
  "allowed_origin": "https://northwind.example",
  "external_order_id": "order_10511",
  "metadata": {
    "cart_id": "c_7790"
  }
}'

Response · 201

HTTP 201
Cache-Control: no-store

{
  "data": {
    "id": "cs_588577021eb7470daccc4a7a5d722873",
    "object": "checkout_session",
    "status": "open",
    "amount_cents": 6400,
    "currency": "USD",
    "payer_email": "taylor.reed@example.com",
    "payer_name": "Taylor Reed",
    "allowed_origin": "https://northwind.example",
    "statement_descriptor": null,
    "external_order_id": "order_10511",
    "metadata": {
      "cart_id": "c_7790"
    },
    "site_id": null,
    "client_secret": "cs_588577021eb7470daccc4a7a5d722873_secret_…",
    "payment": null,
    "last_attempt": null,
    "expires_at": "2026-10-28T00:52:38.591Z",
    "completed_at": null,
    "created_at": "2026-10-28T00:22:38.591Z"
  }
}

GET /v1/checkout-sessions/{id}

Get a checkout session

Secret key

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

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`200`	Checkout session (`CheckoutSession`)
`404`	Error — error shape and codes

Fields of `data` (200)

The same fields as under createCheckoutSession.

Examples (2)

Get a checkout session

GET /v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873

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

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "cs_588577021eb7470daccc4a7a5d722873",
    "object": "checkout_session",
    "status": "open",
    "amount_cents": 6400,
    "currency": "USD",
    "payer_email": "taylor.reed@example.com",
    "payer_name": "Taylor Reed",
    "allowed_origin": "https://northwind.example",
    "statement_descriptor": null,
    "external_order_id": "order_10511",
    "metadata": {
      "cart_id": "c_7790"
    },
    "site_id": null,
    "client_secret": "cs_588577021eb7470daccc4a7a5d722873_secret_…",
    "payment": null,
    "last_attempt": null,
    "expires_at": "2026-10-28T00:52:38.591Z",
    "completed_at": null,
    "created_at": "2026-10-28T00:22:38.591Z"
  }
}

After the payer approved

GET /v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873

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

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "cs_588577021eb7470daccc4a7a5d722873",
    "object": "checkout_session",
    "status": "complete",
    "amount_cents": 6400,
    "currency": "USD",
    "payer_email": "taylor.reed@example.com",
    "payer_name": "Taylor Reed",
    "allowed_origin": "https://northwind.example",
    "statement_descriptor": null,
    "external_order_id": "order_10511",
    "metadata": {
      "cart_id": "c_7790"
    },
    "site_id": null,
    "client_secret": "cs_588577021eb7470daccc4a7a5d722873_secret_…",
    "payment": {
      "id": "87cd9c43-25f8-4e35-96e4-7d42f84e286a",
      "status": "submitted",
      "amount_cents": 6400
    },
    "last_attempt": {
      "id": "87cd9c43-25f8-4e35-96e4-7d42f84e286a",
      "status": "submitted",
      "amount_cents": 6400
    },
    "expires_at": "2026-10-28T00:52:38.591Z",
    "completed_at": "2026-10-28T00:22:38.637Z",
    "created_at": "2026-10-28T00:22:38.591Z"
  }
}

POST /v1/checkout-sessions/{id}/cancel

Cancel an open checkout session

Secret key

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

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`200`	Checkout session (`CheckoutSession`)
`404`	Error — error shape and codes
`409`	Error — error shape and codes

Fields of `data` (200)

The same fields as under createCheckoutSession.

Example

Cancel an open session

POST /v1/checkout-sessions/cs_0426a0788d9146648a15cd1da2c1227b/cancel

curl -X POST https://sandbox.socialmatterspay.com/v1/checkout-sessions/cs_0426a0788d9146648a15cd1da2c1227b/cancel \
  -H 'Authorization: Bearer sk_sandbox_…'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "cs_0426a0788d9146648a15cd1da2c1227b",
    "object": "checkout_session",
    "status": "cancelled",
    "amount_cents": 450000,
    "currency": "USD",
    "payer_email": "taylor.reed@example.com",
    "payer_name": "Taylor Reed",
    "allowed_origin": "https://northwind.example",
    "statement_descriptor": null,
    "external_order_id": "order_10512",
    "metadata": {
      "cart_id": "c_7791"
    },
    "site_id": null,
    "client_secret": "cs_0426a0788d9146648a15cd1da2c1227b_secret_…",
    "payment": null,
    "last_attempt": {
      "id": "56648fef-8a63-4df6-8a51-64f6c64452fd",
      "status": "declined",
      "amount_cents": 450000
    },
    "expires_at": "2026-10-28T00:52:38.614Z",
    "completed_at": null,
    "created_at": "2026-10-28T00:22:38.614Z"
  }
}

POST /browser/v1/checkout-sessions/{id}/link-token

The button opens the payer's bank sign-in

Client secret · session's origin only

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

Called by smp.js from the payer's browser, never with an API key. private_relay is true when the payer's IP is an iCloud Private Relay address, which some banks' sign-in pages block. In the sandbox without Plaid keys, sandbox_link is true and the button pays from the test bank account.

Parameters

Field	Notes
`id` requiredpath · string	—

Request body

Field	Notes
`client_secret` requiredstring	The session's client_secret

Responses

Status	Meaning
`200`	How to open the bank sign-in
`403`	Error — error shape and codes
`404`	Error — error shape and codes
`409`	Error — error shape and codes
`502`	Error — error shape and codes

Fields of `data` (200)

Field	Notes
`object`string = "link_token"	—
`sandbox_link`boolean	—
`link_token`string \| null	—
`private_relay`boolean \| null	—

Example

Open the bank sign-in (sandbox: the test bank account)

POST /browser/v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873/link-token

curl -X POST https://sandbox.socialmatterspay.com/browser/v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873/link-token \
  -H 'Origin: https://northwind.example' \
  -H 'Content-Type: application/json' \
  -d '{
  "client_secret": "cs_588577021eb7470daccc4a7a5d722873_secret_…"
}'

Response · 200

HTTP 200
Cache-Control: no-store
Access-Control-Allow-Origin: https://northwind.example

{
  "data": {
    "object": "link_token",
    "sandbox_link": true,
    "link_token": null,
    "private_relay": null
  }
}

OPTIONS /browser/v1/checkout-sessions/{id}/link-token

CORS preflight, allowed only from the session's origin

No auth

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

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`204`	Allowed; Access-Control-Allow-Origin is the session's origin
`403`	Error — error shape and codes

Examples (2)

Preflight from the session's origin

OPTIONS /browser/v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873/link-token

curl -X OPTIONS https://sandbox.socialmatterspay.com/browser/v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873/link-token \
  -H 'Origin: https://northwind.example' \
  -H 'Access-Control-Request-Method: POST' \
  -H 'Access-Control-Request-Headers: content-type'

Response · 204

HTTP 204
Access-Control-Allow-Origin: https://northwind.example
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Content-Type
Access-Control-Max-Age: 600

Preflight from any other origin is refused

OPTIONS /browser/v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873/link-token

curl -X OPTIONS https://sandbox.socialmatterspay.com/browser/v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873/link-token \
  -H 'Origin: https://elsewhere.example' \
  -H 'Access-Control-Request-Method: POST' \
  -H 'Access-Control-Request-Headers: content-type'

Response · 403

HTTP 403

POST /browser/v1/checkout-sessions/{id}/link

The payer picked an account; link it and get the words to show them

Client secret · session's origin only

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

Links the account from Plaid Link (or, in the sandbox without Plaid keys, the test bank account) to the session and answers with authorization: the exact words the payer agrees to and their SHA-256. Nothing is debited. smp.js shows the words on a card with its own Pay by bank button; pressing it calls complete.

Parameters

Field	Notes
`id` requiredpath · string	—

Request body

Field	Notes
`client_secret` requiredstring	The session's client_secret
`public_token`string	From Plaid Link's onSuccess
`account_id`string	From Plaid Link's onSuccess
`sandbox_link`boolean	Sandbox only — link the test bank account

Responses

Status	Meaning
`200`	The session and the authorization words for the linked account
`400`	Error — error shape and codes
`403`	Error — error shape and codes
`404`	Error — error shape and codes
`409`	Error — error shape and codes
`502`	Error — error shape and codes

Fields of `data` (200)

Field Notes

idstring —

objectstring = "checkout_session" —

statusenum one of open, processing, complete, expired, cancelled

amount_centsinteger —

currencystring = "USD" —

merchant_namestring | null —

paymentobject | null

2 child fields

idstring —

statusenum Forward only. declined, returned, voided and refunded are terminal. A payment SMP holds for review before any debit (a merchant whose return rates are at the critical level, above $200) is answered 201 and stays pending_authorization until SMP approves it (payment.authorized follows) or declines it (payment.declined). one of pending_authorization, authorized, submitted, settled, released, paid_out, declined, returned, voided, refunded

expires_atstring (date-time) —

messagestring On a decline, what to tell the payer

authorizationobject

5 child fields

objectstring = "payment_authorization_text" —

textstring —

text_sha256string pattern ^[0-9a-f]{64}$

amount_descriptionstring —

bank_accountobject

2 child fields

`bank_name`string	—
`last_four`string	—

Example

Link the account the payer picked (sandbox: the test bank account)

POST /browser/v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873/link

curl -X POST https://sandbox.socialmatterspay.com/browser/v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873/link \
  -H 'Origin: https://northwind.example' \
  -H 'Content-Type: application/json' \
  -d '{
  "client_secret": "cs_588577021eb7470daccc4a7a5d722873_secret_…",
  "sandbox_link": true
}'

Response · 200

HTTP 200
Cache-Control: no-store
Access-Control-Allow-Origin: https://northwind.example

{
  "data": {
    "id": "cs_588577021eb7470daccc4a7a5d722873",
    "object": "checkout_session",
    "status": "open",
    "amount_cents": 6400,
    "currency": "USD",
    "merchant_name": "Northwind Supply",
    "payment": null,
    "expires_at": "2026-10-28T00:52:38.591Z",
    "authorization": {
      "object": "payment_authorization_text",
      "text": "By completing this payment, you authorize Northwind Supply to initiate a one-time electronic debit of $64.00 from your bank account ending in 9606. You may revoke this authorization at any time by contacting Northwind Supply, with the understanding that it may take up to 3 business days to process.",
      "text_sha256": "38b512686fc013eda5ab39bc0813e78e9077bfcc71a44e4abe3f6547bc7c27d2",
      "amount_description": "$64.00",
      "bank_account": {
        "bank_name": "Plaid Checking (sandbox)",
        "last_four": "9606"
      }
    }
  }
}

OPTIONS /browser/v1/checkout-sessions/{id}/link

CORS preflight, allowed only from the session's origin

No auth

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

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`204`	Allowed; Access-Control-Allow-Origin is the session's origin
`403`	Error — error shape and codes

Example

Preflight from the session's origin

OPTIONS /browser/v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873/link

curl -X OPTIONS https://sandbox.socialmatterspay.com/browser/v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873/link \
  -H 'Origin: https://northwind.example' \
  -H 'Access-Control-Request-Method: POST' \
  -H 'Access-Control-Request-Headers: content-type'

Response · 204

HTTP 204
Access-Control-Allow-Origin: https://northwind.example
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Content-Type
Access-Control-Max-Age: 600

POST /browser/v1/checkout-sessions/{id}/authorization-text

The authorization words again for the account already linked to the session

Client secret · session's origin only

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

After complete answered 422 authorization_mismatch, show these words and ask the payer again.

Parameters

Field	Notes
`id` requiredpath · string	—

Request body

Field	Notes
`client_secret` requiredstring	The session's client_secret

Responses

Status	Meaning
`200`	The words and their SHA-256
`403`	Error — error shape and codes
`404`	Error — error shape and codes
`409`	Error — error shape and codes

Fields of `data` (200)

Field Notes

objectstring = "payment_authorization_text" —

textstring —

text_sha256string pattern ^[0-9a-f]{64}$

amount_descriptionstring —

bank_accountobject

2 child fields

`bank_name`string	—
`last_four`string	—

Example

The words again, to show the payer

POST /browser/v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873/authorization-text

curl -X POST https://sandbox.socialmatterspay.com/browser/v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873/authorization-text \
  -H 'Origin: https://northwind.example' \
  -H 'Content-Type: application/json' \
  -d '{
  "client_secret": "cs_588577021eb7470daccc4a7a5d722873_secret_…"
}'

Response · 200

HTTP 200
Cache-Control: no-store
Access-Control-Allow-Origin: https://northwind.example

{
  "data": {
    "object": "payment_authorization_text",
    "text": "By completing this payment, you authorize Northwind Supply to initiate a one-time electronic debit of $64.00 from your bank account ending in 9606. You may revoke this authorization at any time by contacting Northwind Supply, with the understanding that it may take up to 3 business days to process.",
    "text_sha256": "38b512686fc013eda5ab39bc0813e78e9077bfcc71a44e4abe3f6547bc7c27d2",
    "amount_description": "$64.00",
    "bank_account": {
      "bank_name": "Plaid Checking (sandbox)",
      "last_four": "9606"
    }
  }
}

OPTIONS /browser/v1/checkout-sessions/{id}/authorization-text

CORS preflight, allowed only from the session's origin

No auth

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

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`204`	Allowed; Access-Control-Allow-Origin is the session's origin
`403`	Error — error shape and codes

Example

Preflight from the session's origin

OPTIONS /browser/v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873/authorization-text

curl -X OPTIONS https://sandbox.socialmatterspay.com/browser/v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873/authorization-text \
  -H 'Origin: https://northwind.example' \
  -H 'Access-Control-Request-Method: POST' \
  -H 'Access-Control-Request-Headers: content-type'

Response · 204

HTTP 204
Access-Control-Allow-Origin: https://northwind.example
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Content-Type
Access-Control-Max-Age: 600

POST /browser/v1/checkout-sessions/{id}/complete

The payer pressed Pay by bank with the authorization words in front of them; debit

Client secret · session's origin only

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

Needs the account linked by link (409 bank_not_linked otherwise) and authorization_text_sha256, the SHA-256 of the words exactly as shown. 422 authorization_mismatch: the words changed — fetch them with authorization-text, show them, and ask again; nothing was charged. One request at a time per session (409 session_busy). The payer's IP and browser on this request are the WEB authorization record. A decline answers 200 with the session still open, its declined payment, and nothing charged; an approved payment answers 200 with the session complete. 422 relink_required: that bank account can no longer be debited.

Parameters

Field	Notes
`id` requiredpath · string	—

Request body

Field	Notes
`client_secret` requiredstring	The session's client_secret
`authorization_text_sha256` requiredstring	SHA-256 of the authorization words exactly as shown. pattern `^[0-9a-f]{64}$`

Responses

Status	Meaning
`200`	The checkout session as the payer's page sees it (`BrowserCheckoutSession`)
`400`	Error — error shape and codes
`403`	Error — error shape and codes
`404`	Error — error shape and codes
`409`	Error — error shape and codes
`422`	Error — error shape and codes
`502`	Error — error shape and codes

Fields of `data` (200)

Field Notes

idstring —

objectstring = "checkout_session" —

statusenum one of open, processing, complete, expired, cancelled

amount_centsinteger —

currencystring = "USD" —

merchant_namestring | null —

paymentobject | null

2 child fields

idstring —

expires_atstring (date-time) —

messagestring On a decline, what to tell the payer

Examples (2)

A declined attempt leaves the session open

POST /browser/v1/checkout-sessions/cs_0426a0788d9146648a15cd1da2c1227b/complete

curl -X POST https://sandbox.socialmatterspay.com/browser/v1/checkout-sessions/cs_0426a0788d9146648a15cd1da2c1227b/complete \
  -H 'Origin: https://northwind.example' \
  -H 'Content-Type: application/json' \
  -d '{
  "client_secret": "cs_0426a0788d9146648a15cd1da2c1227b_secret_…",
  "authorization_text_sha256": "d71890eb975236feca2c5b014148275b6dbfa64b305a2ff8ba7ad6e0d4ce8886"
}'

Response · 200

HTTP 200
Cache-Control: no-store
Access-Control-Allow-Origin: https://northwind.example

{
  "data": {
    "id": "cs_0426a0788d9146648a15cd1da2c1227b",
    "object": "checkout_session",
    "status": "open",
    "amount_cents": 450000,
    "currency": "USD",
    "merchant_name": "Northwind Supply",
    "payment": {
      "id": "56648fef-8a63-4df6-8a51-64f6c64452fd",
      "status": "declined"
    },
    "expires_at": "2026-10-28T00:52:38.614Z",
    "message": "Your bank payment wasn't approved, and nothing was charged. Choose another way to pay."
  }
}

The payer approves: the session is complete

POST /browser/v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873/complete

curl -X POST https://sandbox.socialmatterspay.com/browser/v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873/complete \
  -H 'Origin: https://northwind.example' \
  -H 'Content-Type: application/json' \
  -d '{
  "client_secret": "cs_588577021eb7470daccc4a7a5d722873_secret_…",
  "authorization_text_sha256": "38b512686fc013eda5ab39bc0813e78e9077bfcc71a44e4abe3f6547bc7c27d2"
}'

Response · 200

HTTP 200
Cache-Control: no-store
Access-Control-Allow-Origin: https://northwind.example

{
  "data": {
    "id": "cs_588577021eb7470daccc4a7a5d722873",
    "object": "checkout_session",
    "status": "complete",
    "amount_cents": 6400,
    "currency": "USD",
    "merchant_name": "Northwind Supply",
    "payment": {
      "id": "87cd9c43-25f8-4e35-96e4-7d42f84e286a",
      "status": "submitted"
    },
    "expires_at": "2026-10-28T00:52:38.591Z"
  }
}

OPTIONS /browser/v1/checkout-sessions/{id}/complete

CORS preflight, allowed only from the session's origin

No auth

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

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`204`	Allowed; Access-Control-Allow-Origin is the session's origin
`403`	Error — error shape and codes

Example

Preflight from the session's origin

OPTIONS /browser/v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873/complete

curl -X OPTIONS https://sandbox.socialmatterspay.com/browser/v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873/complete \
  -H 'Origin: https://northwind.example' \
  -H 'Access-Control-Request-Method: POST' \
  -H 'Access-Control-Request-Headers: content-type'

Response · 204

HTTP 204
Access-Control-Allow-Origin: https://northwind.example
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Content-Type
Access-Control-Max-Age: 600

POST /browser/v1/checkout-sessions/{id}/status

The session as the payer's page may see it

Client secret · session's origin only

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

Parameters

Field	Notes
`id` requiredpath · string	—

Request body

Field	Notes
`client_secret` requiredstring	The session's client_secret

Responses

Status	Meaning
`200`	The checkout session as the payer's page sees it (`BrowserCheckoutSession`)
`403`	Error — error shape and codes
`404`	Error — error shape and codes

Fields of `data` (200)

The same fields as under browserCheckoutComplete.

Example

The session as the page sees it

POST /browser/v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873/status

curl -X POST https://sandbox.socialmatterspay.com/browser/v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873/status \
  -H 'Origin: https://northwind.example' \
  -H 'Content-Type: application/json' \
  -d '{
  "client_secret": "cs_588577021eb7470daccc4a7a5d722873_secret_…"
}'

Response · 200

HTTP 200
Cache-Control: no-store
Access-Control-Allow-Origin: https://northwind.example

{
  "data": {
    "id": "cs_588577021eb7470daccc4a7a5d722873",
    "object": "checkout_session",
    "status": "open",
    "amount_cents": 6400,
    "currency": "USD",
    "merchant_name": "Northwind Supply",
    "payment": null,
    "expires_at": "2026-10-28T00:52:38.591Z"
  }
}

OPTIONS /browser/v1/checkout-sessions/{id}/status

CORS preflight, allowed only from the session's origin

No auth

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

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`204`	Allowed; Access-Control-Allow-Origin is the session's origin
`403`	Error — error shape and codes

Example

Preflight from the session's origin

OPTIONS /browser/v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873/status

curl -X OPTIONS https://sandbox.socialmatterspay.com/browser/v1/checkout-sessions/cs_588577021eb7470daccc4a7a5d722873/status \
  -H 'Origin: https://northwind.example' \
  -H 'Access-Control-Request-Method: POST' \
  -H 'Access-Control-Request-Headers: content-type'

Response · 204

HTTP 204
Access-Control-Allow-Origin: https://northwind.example
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Content-Type
Access-Control-Max-Age: 600

GET /js/v1/smp.js

The drop-in Pay by bank button

No auth

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

Load it with <script src="https://api.socialmatterspay.com/js/v1/smp.js"></script>, then call SMP.mount({ container, sessionId, clientSecret, onSuccess, onDecline, onExit, onError }). Public and cacheable; it holds no secret.

Responses

Status	Meaning
`200`	The script

Example

The drop-in script

GET /js/v1/smp.js

curl https://sandbox.socialmatterspay.com/js/v1/smp.js

Response · 200

HTTP 200
Content-Type: text/javascript; charset=utf-8
Cache-Control: public, max-age=300
Access-Control-Allow-Origin: *

/*!
 * Social Matter Payments — Pay by bank button for any website. v1.1.0
 *
 *   <div id="pay-by-bank"></div>
 *   <script src="https://api.socialmatterspay.com/js/v1/smp.js"></script>
 *   <script>
 *     SMP.mount({
 *       container: '#pay-by-bank',
 *       sessionId: 'cs_…',            // from POST /v1/checkout-sessions on your server
 *       clientSecret: 'cs_…_secret_…', // from the same response; never your secret API key
 *       onSuccess: function (session) {},  // session.payment.status: authorized / submitted / settled
 *       onDecline: function (session) {},  // nothing was charged; the payer may try another bank or method
 *       onExit: function () {},            // the payer closed their bank's sign-in
 *       onError: function (error) {}
… 316 more lines

Open a checkout session for the drop-in Pay by bank button

Parameters

Request body

Responses

Fields of data (200)

Get a checkout session

Parameters

Responses

Fields of data (200)

Cancel an open checkout session

Parameters

Responses

Fields of data (200)

The button opens the payer's bank sign-in

Parameters

Request body

Responses

Fields of data (200)

CORS preflight, allowed only from the session's origin

Parameters

Responses

The payer picked an account; link it and get the words to show them

Parameters

Request body

Responses

Fields of data (200)

CORS preflight, allowed only from the session's origin

Parameters

Responses

The authorization words again for the account already linked to the session

Parameters

Request body

Responses

Fields of data (200)

CORS preflight, allowed only from the session's origin

Parameters

Responses

The payer pressed Pay by bank with the authorization words in front of them; debit

Parameters

Request body

Responses

Fields of data (200)

CORS preflight, allowed only from the session's origin

Parameters

Responses

The session as the payer's page may see it

Parameters

Request body

Responses

Fields of data (200)

CORS preflight, allowed only from the session's origin

Parameters

Responses

The drop-in Pay by bank button

Responses

Fields of `data` (200)

Fields of `data` (200)

Fields of `data` (200)

Fields of `data` (200)

Fields of `data` (200)

Fields of `data` (200)

Fields of `data` (200)

Fields of `data` (200)