Onboarding · Social Matter Payments API

POST /v1/merchants/apply

Apply as a merchant

No auth

Host https://onboard.socialmatterspay.com

EIN, SSN and the payout account are sealed before storage. In the sandbox the merchant is approved and activated at once; in production the application waits for SMP's review. The API key is shown once.

Request body

Field Notes

legal_name requiredstring —

dba_namestring —

ein requiredstring pattern ^\d{2}-?\d{7}$

owner_name requiredstring —

owner_ssn requiredstring pattern ^\d{3}-?\d{2}-?\d{4}$

owner_dob requiredstring (date) —

owner_address requiredstring —

business_address requiredstring —

business_type requiredstring —

website_url requiredstring pattern ^https://

description requiredstring —

estimated_monthly_volume_cents requiredinteger at least 0

category requiredstring —

statement_descriptor requiredstring pattern ^[A-Za-z0-9 .&-]{1,12}$

payout_account requiredobject

4 child fields

`account_number` requiredstring	pattern `^\d{4,17}$`
`routing_number` requiredstring	Must pass the ABA checksum. pattern `^\d{9}$`
`account_type` requiredenum	one of `checking`, `savings`
`account_holder_name` requiredstring	—

Responses

Status	Meaning
`201`	Application received
`400`	Error — error shape and codes

Fields of `data` (201)

Field	Notes
`object`string = "merchant_application"	—
`merchant_id`string	—
`status`string	—
`ofac_status`string	—
`api_key`string	Shown once
`message`string	—
`sanctions_screening_id`string	The screening of this application against the sanctions lists
`referral`enum	The referral code sent: none sent, held while the application is reviewed as a possible duplicate, attributed to its partner, or not a code that exists. one of `none`, `pending_review`, `attributed`, `invalid`

Examples (2)

Apply as a merchant (sandbox)

POST /v1/merchants/apply

curl -X POST https://onboard.socialmatterspay.com/v1/merchants/apply \
  -H 'Content-Type: application/json' \
  -d '{
  "legal_name": "Northwind Supply LLC",
  "dba_name": "Northwind Supply",
  "ein": "12-3456789",
  "owner_name": "Jordan Rivera",
  "owner_ssn": "123-45-6789",
  "owner_dob": "1984-03-14",
  "owner_address": "200 Example Ave, Sheridan WY 82801",
  "business_address": "200 Example Ave, Sheridan WY 82801",
  "business_type": "llc",
  "website_url": "https://northwind.example",
  "description": "Sells shop supplies to small businesses",
  "estimated_monthly_volume_cents": 5000000,
  "category": "retail",
  "statement_descriptor": "NORTHWIND",
  "payout_account": {
    "account_number": "4433221100",
    "routing_number": "110000000",
    "account_type": "checking",
    "account_holder_name": "Northwind Supply LLC"
  }
}'

Response · 201

HTTP 201
Cache-Control: no-store

{
  "data": {
    "object": "merchant_application",
    "merchant_id": "a5fc4446-e0a0-4260-ac10-e06060393364",
    "status": "active",
    "ofac_status": "clear",
    "sanctions_screening_id": "7de0e613-98d8-4682-baab-139f204bc455",
    "referral": "none",
    "api_key": "sk_sandbox_…",
    "message": "Sandbox merchant is active. The API key is shown once: store it now."
  }
}

Apply as a merchant (production: waits for review)

POST /v1/merchants/apply

curl -X POST https://onboard.socialmatterspay.com/v1/merchants/apply \
  -H 'Content-Type: application/json' \
  -d '{
  "legal_name": "Harbor Goods LLC",
  "dba_name": "Harbor Goods",
  "ein": "23-4567890",
  "owner_name": "Sam Ortiz",
  "owner_ssn": "234-56-7890",
  "owner_dob": "1975-05-30",
  "owner_address": "200 Example Ave, Sheridan WY 82801",
  "business_address": "200 Example Ave, Sheridan WY 82801",
  "business_type": "llc",
  "website_url": "https://harbor.example",
  "description": "Sells shop supplies to small businesses",
  "estimated_monthly_volume_cents": 5000000,
  "category": "retail",
  "statement_descriptor": "HARBOR",
  "payout_account": {
    "account_number": "4433221100",
    "routing_number": "110000000",
    "account_type": "checking",
    "account_holder_name": "Harbor Goods LLC"
  }
}'

Response · 201

HTTP 201
Cache-Control: no-store

{
  "data": {
    "object": "merchant_application",
    "merchant_id": "1ef360db-ff5e-4b2d-b079-0ae77ebb10a6",
    "status": "under_review",
    "ofac_status": "clear",
    "sanctions_screening_id": "6c3d2c9f-6a1f-49c6-a7a9-584ccb73017f",
    "referral": "none",
    "api_key": "sk_live_…",
    "message": "Application received for review. The API key is shown once and works once the account is active."
  }
}

POST /v1/merchants/{id}/documents

Upload a KYB document (the merchant's own key, 10 MB maximum)

Secret key

Host https://onboard.socialmatterspay.com

Parameters

Field	Notes
`id` requiredpath · string	—

Request body (multipart/form-data)

Field	Notes
`file` requiredstring (binary)	—
`type` requiredenum	one of `ein_letter`, `photo_id`, `bank_statement`, `operating_agreement`, `other`

Responses

Status	Meaning
`201`	Stored
`400`	Error — error shape and codes
`403`	Error — error shape and codes

Fields of `data` (201)

Field	Notes
`object`string = "document"	—
`sha256`string	SHA-256 of the stored file. pattern `^[0-9a-f]{64}$`
`key`string	—
`type`string	—
`bytes`integer	—

Example

Upload a KYB document

POST /v1/merchants/a5fc4446-e0a0-4260-ac10-e06060393364/documents

curl -X POST https://onboard.socialmatterspay.com/v1/merchants/a5fc4446-e0a0-4260-ac10-e06060393364/documents \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -F 'type=ein_letter' \
  -F 'file=@ein-letter.pdf'

Response · 201

HTTP 201

{
  "data": {
    "object": "document",
    "key": "merchants/a5fc4446-e0a0-4260-ac10-e06060393364/ein_letter/f2d5d65f-dc24-4ae3-889c-2040ec886488-ein-letter.pdf",
    "type": "ein_letter",
    "bytes": 16,
    "sha256": "9879a54b23a427f0572f379114a4a2419a93acbda87f7755682b5149174e37eb"
  }
}

POST /v1/merchants/{id}/review

SMP staff decision on an application

SMP staff token

Host https://onboard.socialmatterspay.com

Parameters

Field	Notes
`id` requiredpath · string	—

Request body

Field	Notes
`decision` requiredenum	one of `approved`, `terminated`
`reason` requiredstring	—
`reviewed_by` requiredstring	—
`risk_tier`enum	one of `low`, `standard`, `elevated`, `high`
`duplicate_acknowledged`boolean	Required (true) to approve an application flagged as matching an existing merchant (409 duplicate_review_open otherwise)

Responses

Status	Meaning
`200`	Merchant state (`MerchantState`)
`401`	Error — error shape and codes
`409`	Error — error shape and codes

Fields of `data` (200)

Field	Notes
`object`string = "merchant"	—
`merchant_id`string	—
`status`string	—

Examples (2)

Approve an application (SMP staff)

POST /v1/merchants/1ef360db-ff5e-4b2d-b079-0ae77ebb10a6/review

curl -X POST https://onboard.socialmatterspay.com/v1/merchants/1ef360db-ff5e-4b2d-b079-0ae77ebb10a6/review \
  -H 'Authorization: Bearer smp_staff_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "decision": "approved",
  "reason": "KYB documents verified",
  "reviewed_by": "underwriting",
  "risk_tier": "standard"
}'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "merchant",
    "merchant_id": "1ef360db-ff5e-4b2d-b079-0ae77ebb10a6",
    "status": "approved"
  }
}

Approving a match needs duplicate_acknowledged (SMP staff)

POST /v1/merchants/76d35f7a-f7f5-4695-adeb-4bf750ddbc4e/review

curl -X POST https://onboard.socialmatterspay.com/v1/merchants/76d35f7a-f7f5-4695-adeb-4bf750ddbc4e/review \
  -H 'Authorization: Bearer smp_staff_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "decision": "approved",
  "reason": "KYB documents verified",
  "reviewed_by": "underwriting"
}'

Response · 409

HTTP 409
Cache-Control: no-store

{
  "error": "duplicate_review_open",
  "message": "This application matches an existing merchant; approve it with duplicate_acknowledged: true if it is a separate business",
  "duplicate_of_merchant_id": "1ef360db-ff5e-4b2d-b079-0ae77ebb10a6",
  "duplicate_match": [
    {
      "kind": "domain",
      "merchant_id": "1ef360db-ff5e-4b2d-b079-0ae77ebb10a6"
    },
    {
      "kind": "ein",
      "merchant_id": "1ef360db-ff5e-4b2d-b079-0ae77ebb10a6"
    },
    … 2 more
  ]
}

POST /v1/merchants/{id}/activate

SMP staff — open the bank sub-account and activate an approved merchant

SMP staff token

Host https://onboard.socialmatterspay.com

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`200`	Merchant state (`MerchantState`)
`401`	Error — error shape and codes
`404`	Error — error shape and codes
`409`	Error — error shape and codes

Fields of `data` (200)

Field	Notes
`object`string = "merchant"	—
`merchant_id`string	—
`status`string	—

Example

No captured example: a sandbox merchant is activated when approved (activate answers 409); production activation opens the merchant's account at the bank, and no bank is connected yet (answers 503 bank_not_connected).

GET /v1/merchants/{id}

SMP staff — an application as a reviewer needs it

SMP staff token

Host https://onboard.socialmatterspay.com

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

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

Fields of `data` (200)

Field Notes

objectstring = "merchant" —

idstring —

namestring —

legal_namestring —

statusstring —

risk_tierstring | null —

website_urlstring | null —

categorystring | null —

ofac_statusstring | null —

sanctions_screening_idstring | null —

limit_per_txn_centsinteger —

limit_daily_centsinteger —

limit_monthly_centsinteger —

duplicate_of_merchant_idstring | null The existing merchant this application matched

duplicate_matcharray of object

What matched, for the reviewer

2 child fields

`kind`string	—
`merchant_id`string	—

application_submitted_atstring | null (date-time) —

application_reviewed_atstring | null (date-time) —

application_reviewed_bystring | null —

created_atstring (date-time) —

Example

An application that matches an existing merchant (SMP staff)

GET /v1/merchants/76d35f7a-f7f5-4695-adeb-4bf750ddbc4e

curl https://onboard.socialmatterspay.com/v1/merchants/76d35f7a-f7f5-4695-adeb-4bf750ddbc4e \
  -H 'Authorization: Bearer smp_staff_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "merchant",
    "id": "76d35f7a-f7f5-4695-adeb-4bf750ddbc4e",
    "name": "Harbor Wholesale",
    "legal_name": "Harbor Goods Wholesale LLC",
    "status": "under_review",
    "risk_tier": "standard",
    "website_url": "https://harbor.example",
    "category": "retail",
    "ofac_status": "clear",
    "sanctions_screening_id": "20de39de-2894-4dfc-815d-56c5cf17322a",
    "limit_per_txn_cents": 300000,
    "limit_daily_cents": 5000000,
    "limit_monthly_cents": 50000000,
    "duplicate_of_merchant_id": "1ef360db-ff5e-4b2d-b079-0ae77ebb10a6",
    "duplicate_match": [
      {
        "kind": "domain",
        "merchant_id": "1ef360db-ff5e-4b2d-b079-0ae77ebb10a6"
      },
      {
        "kind": "ein",
        "merchant_id": "1ef360db-ff5e-4b2d-b079-0ae77ebb10a6"
      },
      … 2 more
    ],
    "application_submitted_at": "2026-10-28T00:22:34.432Z",
    "application_reviewed_at": null,
    "application_reviewed_by": null,
    "created_at": "2026-10-28T00:22:34.432Z"
  }
}

PATCH /v1/merchants/{id}/limits

SMP staff — raise or lower a merchant's limits, with the reason on record

SMP staff token

Host https://onboard.socialmatterspay.com

Effective on the merchant's next payment. The before and after values are in the audit log.

Parameters

Field	Notes
`id` requiredpath · string	—

Request body

Field	Notes
`reason` requiredstring	up to 2000 characters
`changed_by` requiredstring	up to 200 characters
`per_transaction_cents`integer	1 to 100000000000
`daily_cents`integer	1 to 100000000000
`monthly_cents`integer	1 to 100000000000

Responses

Status	Meaning
`200`	The limits now in force
`400`	Error — error shape and codes
`401`	Error — error shape and codes
`404`	Error — error shape and codes

Fields of `data` (200)

Field	Notes
`object`string = "merchant_limits"	—
`merchant_id`string	—
`per_transaction_cents`integer	—
`daily_cents`integer	—
`monthly_cents`integer	—

Example

Raise a merchant's limits (SMP staff)

PATCH /v1/merchants/1ef360db-ff5e-4b2d-b079-0ae77ebb10a6/limits

curl -X PATCH https://onboard.socialmatterspay.com/v1/merchants/1ef360db-ff5e-4b2d-b079-0ae77ebb10a6/limits \
  -H 'Authorization: Bearer smp_staff_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "per_transaction_cents": 1000000,
  "daily_cents": 10000000,
  "reason": "Wholesale orders up to $10,000 approved",
  "changed_by": "underwriting"
}'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "merchant_limits",
    "merchant_id": "1ef360db-ff5e-4b2d-b079-0ae77ebb10a6",
    "per_transaction_cents": 1000000,
    "daily_cents": 10000000,
    "monthly_cents": 50000000
  }
}

GET /v1/admin/applications/{id}/certification

Machine to machine (the CRM): an application's certification, from the sandbox (production) or this database (sandbox, local); null data while it has no sandbox account

SMP staff token

Host https://onboard.socialmatterspay.com

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`200`	OK
`400`	Error — error shape and codes
`401`	Error — error shape and codes
`404`	Error — error shape and codes
`409`	Error — error shape and codes
`503`	Error — error shape and codes

Fields of `data` (200)

Field Notes

methodenum one of api, plugin, hosted

casesarray of object

4 child fields

`id`enum	one of `bank_linked`, `payment_settled`, `payment_declined`, `payment_returned`, `refund`, `void`, `webhook_delivered`, `webhook_signature`, `idempotent`
`passed`boolean	—
`evidence`array of string	—
`detail`string	—

passedinteger —

totalinteger —

readyboolean —

checked_atstring (date-time) —

Example

An application's certification (SMP staff)

GET /v1/admin/applications/8f67c6ec-bbf9-4630-bbc3-9c95203955fe/certification

curl https://onboard.socialmatterspay.com/v1/admin/applications/8f67c6ec-bbf9-4630-bbc3-9c95203955fe/certification \
  -H 'Authorization: Bearer smp_staff_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "method": "api",
    "cases": [
      {
        "id": "bank_linked",
        "passed": true,
        "evidence": [
          "62c83c4a-beaa-473e-81e3-4a0bddcd60f4",
          "5f56b123-e891-4bd8-9c17-59a85d555fb5"
        ],
        "detail": "a payer bank account linked through the sandbox"
      },
      {
        "id": "payment_settled",
        "passed": true,
        "evidence": [
          "0b50548d-71bf-440c-8064-47da5449aebc",
          "63be7384-a390-4f7f-bd27-c568476d597c"
        ],
        "detail": "a payment reached settled"
      },
      … 7 more
    ],
    "passed": 9,
    "total": 9,
    "ready": true,
    "checked_at": "2026-10-28T00:23:33.820Z"
  }
}

POST /internal/v1/developer-accounts

The sandbox deployment only, called by production's onboarding worker over its SANDBOX_ONBOARD binding: makes an application's sandbox account once (its one site, a sandbox key, an open sandbox sub-balance, a sandbox dashboard login). Anything else answers 404.

Developer program token

Host https://onboard.socialmatterspay.com

Responses

Status	Meaning
`200`	Made before: the same account
`201`	Made now
`400`	Error — error shape and codes
`401`	Error — error shape and codes
`404`	Error — error shape and codes
`409`	Error — error shape and codes
`503`	Error — error shape and codes

Fields of `data` (200)

Field Notes

merchant_idstring The sandbox account that this application already had.

createdboolean False on this response: the application already had an account, so no key and no dashboard link are returned.

keystring | null Always null here: the key was shown once, when the account was made.

key_prefixstring —

dashboardobject | null

Always null here.

2 child fields

`set_password_url`string	—
`expires_at`string (date-time)	—

Example

An application's sandbox account, made once (production's onboarding worker)

POST /internal/v1/developer-accounts

curl -X POST https://onboard.socialmatterspay.com/internal/v1/developer-accounts \
  -H 'Authorization: Bearer developer_program_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "application_ref": "app_example_0001",
  "reference": "SMP-EXAMPLE-0001",
  "legal_name": "Harbor Goods LLC",
  "contact_email": "owner@harbor.example",
  "target": {
    "kind": "website",
    "domain": "harbor.example",
    "method": "api"
  }
}'

Response · 201

HTTP 201
Cache-Control: no-store

{
  "data": {
    "merchant_id": "830b2533-7445-48f6-87b7-f3a06ea50d77",
    "created": true,
    "key": "sk_sandbox_…",
    "key_prefix": "sk_sandbox_5414",
    "dashboard": null
  }
}

GET /internal/v1/developer-accounts/{id}/certification

The sandbox deployment only (production's calls): a sandbox account's certification, by method (api, plugin, hosted)

Developer program token

Host https://onboard.socialmatterspay.com

Parameters

Field	Notes
`id` requiredpath · string	—
`method`query · string	one of `api`, `plugin`, `hosted`

Responses

Status	Meaning
`200`	OK
`400`	Error — error shape and codes
`401`	Error — error shape and codes
`404`	Error — error shape and codes
`409`	Error — error shape and codes
`503`	Error — error shape and codes

Fields of `data` (200)

Field Notes

methodenum How the business connects. Only api runs cases; plugin and hosted get the light review, so their cases list is empty and total is 0. one of api, plugin, hosted

casesarray of object

4 child fields

`id`enum	one of `bank_linked`, `payment_settled`, `payment_declined`, `payment_returned`, `refund`, `void`, `webhook_delivered`, `webhook_signature`, `idempotent`
`passed`boolean	—
`evidence`array of string	Up to 3 sandbox ids that show the case passed (payments, refunds, webhook deliveries, signature checks). Empty when it has not passed.
`detail`string	What the case needs when it has not passed, or what passing it showed.

passedinteger How many of the method's cases have passed.

totalinteger How many cases the method runs.

readyboolean All the cases the method runs have passed. The page check is a person's, so ready does not mean approved.

checked_atstring (date-time) —

Example

That sandbox account's certification (production's onboarding worker)

GET /internal/v1/developer-accounts/4cad9448-209c-48b5-9a1f-95c8585a2db7/certification

curl https://onboard.socialmatterspay.com/internal/v1/developer-accounts/4cad9448-209c-48b5-9a1f-95c8585a2db7/certification?method=api \
  -H 'Authorization: Bearer developer_program_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "method": "api",
    "cases": [
      {
        "id": "bank_linked",
        "passed": true,
        "evidence": [
          "62c83c4a-beaa-473e-81e3-4a0bddcd60f4",
          "5f56b123-e891-4bd8-9c17-59a85d555fb5"
        ],
        "detail": "a payer bank account linked through the sandbox"
      },
      {
        "id": "payment_settled",
        "passed": true,
        "evidence": [
          "0b50548d-71bf-440c-8064-47da5449aebc",
          "63be7384-a390-4f7f-bd27-c568476d597c"
        ],
        "detail": "a payment reached settled"
      },
      … 7 more
    ],
    "passed": 9,
    "total": 9,
    "ready": true,
    "checked_at": "2026-10-28T00:23:33.831Z"
  }
}

POST /internal/v1/developer-accounts/{id}/signature-check

The sandbox deployment only (production's calls): sends the sandbox account's webhook endpoints one wrongly signed event and records each answer

Developer program token

Host https://onboard.socialmatterspay.com

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`200`	OK
`400`	Error — error shape and codes
`401`	Error — error shape and codes
`404`	Error — error shape and codes
`409`	Error — error shape and codes
`503`	Error — error shape and codes

Fields of each item of `data` (200)

Field	Notes
`url`string	The endpoint's URL.
`status_code`integer \| null	The HTTP status the endpoint answered; null when it could not be reached.
`error`string \| null	Why the request failed (a timeout, a refused connection), at most 200 characters; null when the endpoint answered.
`passed`boolean	True when the endpoint answered 4xx, refusing the forged event. A 2xx means it would take a forged event.

Example

Its signature check (production's onboarding worker)

POST /internal/v1/developer-accounts/4cad9448-209c-48b5-9a1f-95c8585a2db7/signature-check

curl -X POST https://onboard.socialmatterspay.com/internal/v1/developer-accounts/4cad9448-209c-48b5-9a1f-95c8585a2db7/signature-check \
  -H 'Authorization: Bearer developer_program_token' \
  -H 'Content-Type: application/json' \
  -d '{}'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": [
    {
      "url": "https://sunrise31.example/smp/webhooks",
      "status_code": 401,
      "error": null,
      "passed": true
    }
  ]
}

POST /internal/flush-email

Machine to machine: send the emails still queued in email_outbox (the CRM calls it after a change; a five-minute cron does the same)

SMP staff token

Host https://onboard.socialmatterspay.com

Responses

Status	Meaning
`200`	How many were sent, queued for a retry, failed for good, or skipped (no Resend key, or not due yet)
`401`	Error — error shape and codes

Fields of `data` (200)

Field	Notes
`sent`integer	—
`retry`integer	—
`failed`integer	—
`skipped`integer	—

Example

Send what the email outbox holds now (SMP staff)

POST /internal/flush-email

curl -X POST https://onboard.socialmatterspay.com/internal/flush-email \
  -H 'Authorization: Bearer smp_staff_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "sent": 0,
    "retry": 0,
    "failed": 0,
    "skipped": 8
  }
}

POST /internal/partner-drafts

Machine to machine: the partners worker’s merchant submissions (items 1–8 and the price proposal) become a draft; the merchant is emailed a link to finish it

SMP staff token

Host https://onboard.socialmatterspay.com

Request body

Field Notes

partner_id requiredstring —

agent_idstring —

partner_user_idstring —

started_byenum one of partner, agent

contact requiredobject

3 child fields

`email` requiredstring	—
`phone` requiredstring	A US phone number
`name`string	up to 120 characters

business requiredobject

3 child fields

`legal_name` requiredstring	up to 200 characters
`dba_name`string	up to 200 characters
`website_url` requiredstring	—

sales requiredobject

4 child fields

`monthly_volume_cents` requiredinteger	at least 0
`avg_ticket_cents` requiredinteger	at least 0
`max_ticket_cents` requiredinteger	Not less than avg_ticket_cents. at least 0
`integration_types` requiredarray of string	From the questionnaire's integration choices (its config)

owners requiredarray of object

Every owner of 25% or more and one control person. at least 1 item. at most 5 items

13 child fields

`full_name` requiredstring	The person's full legal name. up to 120 characters
`title`string	up to 80 characters
`ownership_pct` requirednumber	Kept to two decimals. 0 to 100
`is_control_person`boolean	true for the one person who controls the business
`dob` requiredstring (date)	—
`email`string	Where their own link to add their ID is sent
`phone`string	A US phone number
`address_line1` requiredstring	A street address, not a PO box. up to 200 characters
`address_line2`string	up to 200 characters
`address_city` requiredstring	up to 100 characters
`address_state` requiredstring	A US state's two-letter code
`address_postal_code` requiredstring	—
`ssn` requiredstring	Nine digits; sealed on arrival and never returned in full

pricing requiredobject

3 child fields

`bps` requiredinteger	0 to 10000
`fixed_cents` requiredinteger	at least 0
`cap_cents`integer \| null	at least 1

Responses

Status	Meaning
`201`	The draft
`400`	Error — error shape and codes
`401`	Error — error shape and codes
`409`	Error — error shape and codes
`503`	Error — error shape and codes

Fields of `data` (201)

Field Notes

objectstring = "application" —

idstring —

referencestring The application's reference.

statusstring = "draft" —

link_sent_tostring The merchant's contact email with most of the name before the @ hidden. The link to open the draft was emailed there.

proposed_pricingobject

The price the partner proposed, as it was saved.

3 child fields

`bps`integer	Rate in basis points.
`fixed_cents`integer	—
`cap_cents`integer \| null	Cap per payment, in cents. Null for no cap.

proposed_pricing_textstring The proposal in words: its percentage, its fixed part per payment, and its cap when it has one.

Example

A partner's draft application, as the partner portal's Worker files it (SMP staff token)

POST /internal/partner-drafts

curl -X POST https://onboard.socialmatterspay.com/internal/partner-drafts \
  -H 'Authorization: Bearer smp_staff_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "partner_id": "1506590a-fda8-428f-8ed1-cf5a8e52f8f5",
  "contact": {
    "email": "owner@kelpbay.example",
    "phone": "(813) 555-0144",
    "name": "Jennifer Thompson"
  },
  "business": {
    "legal_name": "Kelpbay Supply LLC",
    "dba_name": "Kelpbay Supply",
    "website_url": "https://kelpbay.example"
  },
  "sales": {
    "monthly_volume_cents": 4000000,
    "avg_ticket_cents": 12000,
    "max_ticket_cents": 90000,
    "integration_types": [
      "api"
    ]
  },
  "owners": [
    {
      "full_name": "Jennifer Thompson",
      "ownership_pct": 100,
      "is_control_person": true,
      "dob": "1980-01-01",
      "ssn": "123-45-6003",
      "address_line1": "9 Bay Rd",
      "address_city": "Tampa",
      "address_state": "FL",
      "address_postal_code": "33606",
      "email": "owner@kelpbay.example"
    }
  ],
  "pricing": {
    "bps": 125,
    "fixed_cents": 35,
    "cap_cents": 450
  }
}'

Response · 201

HTTP 201
Cache-Control: no-store

{
  "data": {
    "object": "application",
    "id": "57b01295-8ed8-4b19-b636-43ac8a6ce0b6",
    "reference": "SMP-MK47-4T9Q",
    "status": "draft",
    "link_sent_to": "o••••@kelpbay.example",
    "proposed_pricing": {
      "bps": 125,
      "fixed_cents": 35,
      "cap_cents": 450
    },
    "proposed_pricing_text": "1.25% + $0.35 per payment, capped at $4.50"
  }
}

Apply as a merchant

Request body

Responses

Fields of data (201)

Upload a KYB document (the merchant's own key, 10 MB maximum)

Parameters

Request body (multipart/form-data)

Responses

Fields of data (201)

SMP staff decision on an application

Parameters

Request body

Responses

Fields of data (200)

SMP staff — open the bank sub-account and activate an approved merchant

Parameters

Responses

Fields of data (200)

SMP staff — an application as a reviewer needs it

Parameters

Responses

Fields of data (200)

SMP staff — raise or lower a merchant's limits, with the reason on record

Parameters

Request body

Responses

Fields of data (200)

Machine to machine (the CRM): an application's certification, from the sandbox (production) or this database (sandbox, local); null data while it has no sandbox account

Parameters

Responses

Fields of data (200)

The sandbox deployment only, called by production's onboarding worker over its SANDBOX_ONBOARD binding: makes an application's sandbox account once (its one site, a sandbox key, an open sandbox sub-balance, a sandbox dashboard login). Anything else answers 404.

Responses

Fields of data (200)

The sandbox deployment only (production's calls): a sandbox account's certification, by method (api, plugin, hosted)

Parameters

Responses

Fields of data (200)

The sandbox deployment only (production's calls): sends the sandbox account's webhook endpoints one wrongly signed event and records each answer

Parameters

Responses

Fields of each item of data (200)

Machine to machine: send the emails still queued in email_outbox (the CRM calls it after a change; a five-minute cron does the same)

Responses

Fields of data (200)

Machine to machine: the partners worker’s merchant submissions (items 1–8 and the price proposal) become a draft; the merchant is emailed a link to finish it

Request body

Responses

Fields of data (201)

Fields of `data` (201)

Fields of `data` (201)

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 each item of `data` (200)

Fields of `data` (200)

Fields of `data` (201)