Agent portal · Social Matter Payments API

GET /v1/agent/me

The agent account

Agent session

Host https://partners.socialmatterspay.com

Responses

Status	Meaning
`200`	OK
`401`	Error — error shape and codes

Fields of the response (200)

Field Notes

idstring —

partner_idstring —

partner_namestring The partner's display name.

namestring —

emailstring —

statusenum The agent portal only admits an active agent, so a signed-in call sees active. one of invited, active, deactivated

cut_bpsinteger The agent's share of the commission pool, in basis points.

payout_account_on_fileboolean —

payout_account_last4string | null —

payout_account_typeenum one of checking, savings,

tax_id_on_fileboolean —

tax_id_last4string | null —

tax_form_statusenum one of not_received, received, verified

payout_hold_reasonsarray of enum Why this recipient's commission payouts are held now, in the order the payout run applies them; empty when nothing holds them. Commission keeps accruing meanwhile. one of recipient_suspended, missing_payout_account, missing_tax_id, tax_form_not_received

partnershipobject

2 child fields

`ends_on`string \| null (date)	The date the partnership ends (UTC); from that date the partner and its agents earn no commission. Null while none is set.
`ended`boolean	True once the end date has come.

Example

The signed-in agent

GET /v1/agent/me

curl https://partners.socialmatterspay.com/v1/agent/me \
  -H 'Authorization: Bearer agent_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "id": "62a14022-b94b-4d55-b7d7-bd0eb19611c2",
  "partner_id": "1506590a-fda8-428f-8ed1-cf5a8e52f8f5",
  "partner_name": "Ridgeline",
  "name": "Sam Ortiz",
  "email": "sam@ridgeline.example",
  "status": "active",
  "cut_bps": 4000,
  "payout_hold_reasons": [
    "missing_payout_account",
    "missing_tax_id",
    "tax_form_not_received"
  ],
  "payout_account_on_file": false,
  "payout_account_last4": null,
  "payout_account_type": null,
  "tax_id_on_file": false,
  "tax_id_last4": null,
  "tax_form_status": "not_received",
  "partnership": {
    "ends_on": null,
    "ended": false
  }
}

PUT /v1/agent/payout-account

Set the bank account the agent is paid to (sealed at rest)

Agent session

Host https://partners.socialmatterspay.com

Request body

Field	Notes
`account_number` requiredstring	—
`routing_number` requiredstring	—
`account_type` requiredenum	one of `checking`, `savings`
`account_holder_name` requiredstring	—

Responses

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

Fields of the response (200)

Field	Notes
`payout_account_on_file`boolean = true	—
`payout_account_last4`string	—
`payout_account_type`enum	one of `checking`, `savings`

Example

Set the agent's payout account

PUT /v1/agent/payout-account

curl -X PUT https://partners.socialmatterspay.com/v1/agent/payout-account \
  -H 'Authorization: Bearer agent_session_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "account_number": "5566778899",
  "routing_number": "110000000",
  "account_type": "checking",
  "account_holder_name": "Sam Ortiz"
}'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "payout_account_on_file": true,
  "payout_account_last4": "8899",
  "payout_account_type": "checking"
}

PUT /v1/agent/tax-id

Set the agent's tax ID (sealed at rest; required before any payout)

Agent session

Host https://partners.socialmatterspay.com

Request body

Field	Notes
`tax_id` requiredstring	—

Responses

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

Fields of the response (200)

Field	Notes
`tax_id_on_file`boolean = true	—
`tax_id_last4`string	—

Example

Record the agent's tax ID

PUT /v1/agent/tax-id

curl -X PUT https://partners.socialmatterspay.com/v1/agent/tax-id \
  -H 'Authorization: Bearer agent_session_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "tax_id": "123-45-6789"
}'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "tax_id_on_file": true,
  "tax_id_last4": "6789"
}

GET /v1/agent/links

The agent's referral links

Agent session

Host https://partners.socialmatterspay.com

Responses

Status	Meaning
`200`	OK
`401`	Error — error shape and codes

Fields of the response (200)

Field Notes

linksarray of object

7 child fields

`id`string	—
`code`string	The referral code in the link's /r/ path.
`label`string \| null	—
`status`enum	one of `active`, `disabled`
`click_count`integer	—
`created_at`string (date-time)	—
`merchants`integer	Merchants attributed through the link.

Example

The agent's links

GET /v1/agent/links

curl https://partners.socialmatterspay.com/v1/agent/links \
  -H 'Authorization: Bearer agent_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "links": [
    {
      "id": "ad78c3b9-8360-4dc1-8712-c5c8257e7ca0",
      "code": "z8cg3sg5mr",
      "label": "Sam — webinars",
      "status": "active",
      "click_count": 0,
      "created_at": "2026-10-28T00:22:38.109Z",
      "merchants": 0
    }
  ]
}

GET /v1/agent/merchants

Merchants the agent referred

Agent session

Host https://partners.socialmatterspay.com

Responses

Status	Meaning
`200`	OK
`401`	Error — error shape and codes

Fields of the response (200)

Field Notes

merchantsarray of object

15 child fields

`merchant_id`string	—
`merchant_name`string	—
`merchant_status`enum	one of `application_pending`, `under_review`, `approved`, `active`, `suspended`, `terminated`
`agent_id`string \| null	—
`agent_name`string \| null	—
`referral_code`string	—
`pool_bps`integer	—
`window_months`integer	—
`attributed_at`string (date-time)	—
`window_starts_at`string \| null (date-time)	—
`window_ends_at`string \| null (date-time)	—
`settled_payments`integer	—
`settled_volume_cents`integer	—
`smp_fee_cents`integer	—
`agent_commission_cents`integer	—

Example

Merchants the agent brought

GET /v1/agent/merchants

curl https://partners.socialmatterspay.com/v1/agent/merchants \
  -H 'Authorization: Bearer agent_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "merchants": [
    {
      "merchant_id": "42391a6e-dbb3-463f-9b96-da46e2cee6a4",
      "merchant_name": "Cedar Lane Bakery",
      "merchant_status": "active",
      "agent_id": "62a14022-b94b-4d55-b7d7-bd0eb19611c2",
      "agent_name": "Sam Ortiz",
      "referral_code": "z8cg3sg5mr",
      "pool_bps": 2500,
      "window_months": 24,
      "attributed_at": "2026-10-28T00:22:38.120Z",
      "window_starts_at": null,
      "window_ends_at": null,
      "settled_payments": 1,
      "settled_volume_cents": 12000,
      "smp_fee_cents": 145,
      "agent_commission_cents": 0
    }
  ]
}

GET /v1/agent/earnings

The agent's commission ledger for a date range

Agent session

Host https://partners.socialmatterspay.com

Parameters

Field	Notes
`from`query · string	—
`to`query · string	—

Responses

Status	Meaning
`200`	OK
`401`	Error — error shape and codes

Fields of the response (200)

Field Notes

summaryobject

Commission totals in cents. earned + clawback - voided = paid + payable.

5 child fields

`earned_cents`integer	Commission entries earned, including those later voided.
`voided_cents`integer	Commission entries that were clawed back before being paid.
`clawback_cents`integer	Clawback entries (negative amounts).
`paid_cents`integer	—
`payable_cents`integer	Accrued and not yet paid.

entriesarray of object

The agent's entries earned in the range, newest first.

22 child fields

`id`string	—
`entry_kind`enum	one of `commission`, `clawback`
`payment_id`string \| null	—
`fee_assessment_id`string \| null	—
`merchant_id`string	—
`merchant_name`string	—
`recipient_type`string = "agent"	—
`recipient_id`string	—
`agent_id`string \| null	—
`smp_fee_cents`integer	—
`pool_bps`integer	—
`agent_cut_bps`integer	—
`pool_cents`integer	—
`agent_cents`integer	—
`amount_cents`integer	What this entry pays the agent; negative on a clawback.
`status`enum	one of `accrued`, `clawed_back`, `paid`
`reverses_entry_id`string \| null	—
`payout_id`string \| null	—
`earned_at`string (date-time)	—
`created_at`string (date-time)	—
`clawed_back_at`string \| null (date-time)	—
`paid_at`string \| null (date-time)	—

Example

The agent's earnings

GET /v1/agent/earnings

curl https://partners.socialmatterspay.com/v1/agent/earnings?from=2026-10-01&to=2026-10-28 \
  -H 'Authorization: Bearer agent_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "summary": {
    "earned_cents": 0,
    "voided_cents": 0,
    "clawback_cents": 0,
    "paid_cents": 0,
    "payable_cents": 0
  },
  "entries": []
}

GET /v1/agent/payouts

The agent's commission payouts

Agent session

Host https://partners.socialmatterspay.com

Responses

Status	Meaning
`200`	OK
`401`	Error — error shape and codes

Fields of the response (200)

Field Notes

payoutsarray of object

15 child fields

`id`string	—
`recipient_type`enum	one of `partner`, `agent`
`recipient_id`string	—
`gross_cents`integer	The commission entries reserved for this payout.
`fees_netted_cents`integer	SMP fees taken off the payout.
`amount_cents`integer	gross_cents minus fees_netted_cents.
`entries_count`integer	—
`status`enum	one of `pending`, `submitted`, `failed`
`bank_reference`string \| null	The bank's reference; set once the payout is submitted.
`statement_descriptor`string	What appears on the recipient's bank statement.
`period_end`string (date-time)	The start of the month after the one paid for (exclusive end of the period).
`failure_reason`string \| null	—
`created_at`string (date-time)	—
`submitted_at`string \| null (date-time)	—
`failed_at`string \| null (date-time)	—

Example

The agent's payouts

GET /v1/agent/payouts

curl https://partners.socialmatterspay.com/v1/agent/payouts \
  -H 'Authorization: Bearer agent_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "payouts": []
}

GET /v1/agent/statements/{period}

Monthly statement (period = YYYY-MM)

Agent session

Host https://partners.socialmatterspay.com

Parameters

Field	Notes
`period` requiredpath · string	—

Responses

Status	Meaning
`200`	OK
`401`	Error — error shape and codes

Fields of the response (200)

Field Notes

periodobject

3 child fields

`label`string	The month, YYYY-MM.
`start`string (date-time)	The first instant of the month (UTC).
`end`string (date-time)	The first instant of the next month (UTC); the period excludes it.

merchantsarray of object

7 child fields

`merchant_id`string	—
`merchant_name`string	—
`payments`integer	—
`volume_cents`integer	—
`smp_fee_cents`integer	—
`agent_cents`integer	—
`voided_cents`integer	—

clawbacksarray of object

8 child fields

`id`string	—
`payment_id`string \| null	—
`merchant_id`string	—
`recipient_type`enum	one of `partner`, `agent`
`recipient_id`string	—
`amount_cents`integer	Negative.
`status`enum	one of `accrued`, `paid`
`created_at`string (date-time)	—

payoutsarray of object

8 child fields

`id`string	—
`recipient_type`enum	one of `partner`, `agent`
`recipient_id`string	—
`amount_cents`integer	—
`status`enum	one of `pending`, `submitted`, `failed`
`bank_reference`string \| null	—
`created_at`string (date-time)	—
`submitted_at`string \| null (date-time)	—

feesarray of object

SMP fees on the agent for the month.

9 child fields

`id`string	—
`code`string	The fee code, such as `partner.monthly` or `agent.monthly`.
`amount_cents`integer	—
`period`string \| null	The month (YYYY-MM) of a monthly fee. Null for a one-time fee.
`subject_agent_id`string \| null	The agent an agent fee is for (charged to the partner).
`status`enum	`netted`: taken off a commission payout. `collected`: settled by a fee collection. `open`: not yet settled. one of `open`, `netted`, `collected`
`netted_payout_id`string \| null	—
`collection_id`string \| null	—
`assessed_at`string (date-time)	—

fee_collectionsarray of object

Always empty for an agent; SMP debits only the partner.

9 child fields

`id`string	—
`fees_cents`integer	—
`commissions_applied_cents`integer	—
`debit_cents`integer	What is debited from the partner's bank account. 0 when commissions covered the fees.
`entry_code`enum	The Nacha entry class of the debit. Null when there is none. one of `CCD`, `PPD`,
`status`enum	one of `netted`, `debit_scheduled`, `debit_submitted`, `debit_settled`, `debit_returned`, `debit_failed`
`debit_scheduled_for`string \| null (date-time)	—
`return_code`string \| null	The Nacha return code of a returned debit.
`created_at`string (date-time)	—

totalsobject

Totals in cents for the month.

8 child fields

`earned_cents`integer	Commission earned in the month, including entries later voided.
`voided_cents`integer	—
`clawback_cents`integer	Clawbacks created in the month (negative).
`paid_out_cents`integer	Payouts for the month that were submitted to the bank.
`fees_cents`integer	SMP fees assessed for the month.
`fees_netted_from_payouts_cents`integer	—
`fees_collected_cents`integer	—
`fees_open_cents`integer	—

Example

The agent's monthly statement

GET /v1/agent/statements/2026-10

curl https://partners.socialmatterspay.com/v1/agent/statements/2026-10 \
  -H 'Authorization: Bearer agent_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "period": {
    "label": "2026-10",
    "start": "2026-10-01T00:00:00.000Z",
    "end": "2026-11-01T00:00:00.000Z"
  },
  "merchants": [
    {
      "merchant_id": "42391a6e-dbb3-463f-9b96-da46e2cee6a4",
      "merchant_name": "Cedar Lane Bakery",
      "payments": 1,
      "volume_cents": 12000,
      "smp_fee_cents": 145,
      "agent_cents": 20,
      "voided_cents": 0
    }
  ],
  "clawbacks": [],
  "payouts": [],
  "fees": [],
  "fee_collections": [],
  "totals": {
    "earned_cents": 20,
    "voided_cents": 0,
    "clawback_cents": 0,
    "paid_out_cents": 0,
    "fees_cents": 0,
    "fees_netted_from_payouts_cents": 0,
    "fees_collected_cents": 0,
    "fees_open_cents": 0
  }
}

GET /v1/agent/bank

The connected payout bank (name and last four), the ways to connect one, and SMP's ACH Company ID

Agent session

Host https://partners.socialmatterspay.com

Responses

Status	Meaning
`200`	OK
`401`	Error — error shape and codes

Fields of `data` (200)

Field Notes

objectstring = "payout_bank" —

connectionobject | null

The payout bank connected now. Null when none is connected.

8 child fields

objectstring = "payout_bank_connection" —

idstring —

link_methodenum one of sandbox, plaid

bank_namestring —

account_last4string —

connected_atstring (date-time) —

connected_emailstring The login email that confirmed the connection.

authorizationobject | null

The signed authorization to debit the partner's bank account for fees its commissions do not cover. Null when none is in force. The sealed account numbers are never returned.

15 child fields

`id`string	—
`object`string = "fee_debit_authorization"	—
`status`enum	`revoked` once a newer authorization replaced it; the authorization read on its own is always the one in force. one of `in_force`, `revoked`
`entry_code`enum	The Nacha entry class of the debit, set by the partner's entity type (CCD for a business, PPD for an individual). one of `CCD`, `PPD`
`authorization_text`string	The exact words the signer accepted.
`text_sha256`string	SHA-256 of the authorization text.
`account_last4`string	—
`account_type`enum	one of `checking`, `savings`
`account_holder_name`string	—
`signer_name`string	—
`signer_title`string \| null	—
`accepted_at`string (date-time)	—
`revoked_at`string \| null (date-time)	—
`revoked_reason`string \| null	—
`retain_until`string \| null (date-time)	The date until which a revoked authorization is kept on record.

fee_debit_authorizationobject | null The signed authorization to debit the partner's bank account for fees its commissions do not cover. Null when none is in force. The sealed account numbers are never returned. Its fields are listed under agentPayoutBank · connection.authorization.

payout_account_on_fileboolean Whether account numbers are on file, typed or connected.

methodsarray of enum The ways a bank can be connected here. The test bank exists outside production only; Plaid only where it is configured. one of sandbox, plaid

ach_company_idstring | null SMP's 10-character ACH Company ID. Null until the sponsor bank assigns one.

environmentenum one of production, sandbox

Example

Where the agent's commissions are paid

GET /v1/agent/bank

curl https://partners.socialmatterspay.com/v1/agent/bank \
  -H 'Authorization: Bearer agent_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "payout_bank",
    "connection": null,
    "fee_debit_authorization": null,
    "payout_account_on_file": true,
    "methods": [
      "sandbox"
    ],
    "ach_company_id": null,
    "environment": "sandbox"
  }
}

POST /v1/agent/bank/link-token

A Plaid Link token for connecting the payout bank

Agent session

Host https://partners.socialmatterspay.com

Responses

Status	Meaning
`201`	OK
`401`	Error — error shape and codes
`502`	Error — error shape and codes
`503`	Error — error shape and codes

Fields of `data` (201)

Field	Notes
`object`string = "link_token"	—
`link_token`string	The token that opens Plaid Link.
`expiration`string (date-time)	—

Example

status 503 in this build: Plaid keys are not configured.

Start a Plaid bank sign-in for the payout account

POST /v1/agent/bank/link-token

curl -X POST https://partners.socialmatterspay.com/v1/agent/bank/link-token \
  -H 'Authorization: Bearer agent_session_token'

Response · 503

HTTP 503
Cache-Control: no-store

{
  "error": "plaid_not_configured",
  "message": "Connecting a bank through Plaid is not available here yet"
}

POST /v1/agent/bank/intents

Resolve the account (Plaid or the sandbox test bank) and fix the debit authorization words

Agent session

Host https://partners.socialmatterspay.com

Request body

Field	Notes
`method` requiredenum	one of `sandbox`, `plaid`
`public_token`string	Plaid Link's public token (method plaid)
`account_id`string	The Plaid account picked in Link (method plaid)

Responses

Status	Meaning
`201`	OK
`400`	Error — error shape and codes
`401`	Error — error shape and codes
`422`	Error — error shape and codes
`502`	Error — error shape and codes
`503`	Error — error shape and codes

Fields of `data` (201)

Field	Notes
`object`string = "bank_link_intent"	—
`id`string	—
`link_method`enum	one of `sandbox`, `plaid`
`bank_name`string	—
`account_last4`string	—
`account_holder_name`string	The agent's name.
`entry_code`null	Always null; an agent signs no fee debit authorization.
`authorization_text`null	Always null for an agent.
`text_sha256`null	Always null for an agent.
`expires_at`string (date-time)	30 minutes after the intent is created.
`suggested_signer`string	The agent's name.

Example

Change the payout bank (an agent signs no debit authorization)

POST /v1/agent/bank/intents

curl -X POST https://partners.socialmatterspay.com/v1/agent/bank/intents \
  -H 'Authorization: Bearer agent_session_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "method": "sandbox"
}'

Response · 201

HTTP 201
Cache-Control: no-store

{
  "data": {
    "object": "bank_link_intent",
    "id": "e702801f-2fad-49ea-949c-75fd3e018f41",
    "link_method": "sandbox",
    "bank_name": "Sandbox test bank",
    "account_last4": "9606",
    "account_holder_name": "Sam Ortiz",
    "entry_code": null,
    "authorization_text": null,
    "text_sha256": null,
    "expires_at": "2026-10-28T00:52:38.289Z",
    "suggested_signer": "Sam Ortiz"
  }
}

GET /v1/agent/bank/intents/{id}

An open bank connection intent: the account and the exact authorization words, until it is confirmed or expires

Agent session

Host https://partners.socialmatterspay.com

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

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

Fields of `data` (200)

Field	Notes
`object`string = "bank_link_intent"	—
`id`string	—
`link_method`enum	one of `sandbox`, `plaid`
`bank_name`string	—
`account_last4`string	—
`account_holder_name`string	The partner's legal name, or the agent's name.
`entry_code`enum	The Nacha entry class of the fee debit the partner will authorize. Null for an agent, who signs no authorization. one of `CCD`, `PPD`,
`authorization_text`string \| null	The exact words the signer must accept. Null for an agent.
`text_sha256`string \| null	SHA-256 of the authorization text, echoed back on confirm. Null for an agent.
`expires_at`string (date-time)	—

Example

The change again (a reload of the review step)

GET /v1/agent/bank/intents/e702801f-2fad-49ea-949c-75fd3e018f41

curl https://partners.socialmatterspay.com/v1/agent/bank/intents/e702801f-2fad-49ea-949c-75fd3e018f41 \
  -H 'Authorization: Bearer agent_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "bank_link_intent",
    "id": "e702801f-2fad-49ea-949c-75fd3e018f41",
    "link_method": "sandbox",
    "bank_name": "Sandbox test bank",
    "account_last4": "9606",
    "account_holder_name": "Sam Ortiz",
    "entry_code": null,
    "authorization_text": null,
    "text_sha256": null,
    "expires_at": "2026-10-28T00:52:38.289Z"
  }
}

POST /v1/agent/bank/intents/{id}/confirm

Agree to the exact words and make the bank the payout account

Agent session

Host https://partners.socialmatterspay.com

Parameters

Field	Notes
`id` requiredpath · string	—

Request body

Field	Notes
`accepted`boolean = true	Both boxes ticked: the signer read and signs the words (not needed for an agent)
`signer_name`string	—
`signer_title`string	—
`text_sha256`string	SHA-256 of the authorization words shown (not needed for an agent)
`password` requiredstring	The login's password, re-entered

Responses

Status	Meaning
`201`	OK
`400`	Error — error shape and codes
`401`	Error — error shape and codes
`403`	Error — error shape and codes
`404`	Error — error shape and codes
`409`	Error — error shape and codes
`410`	Error — error shape and codes
`429`	Error — error shape and codes

Fields of `data` (201)

Field	Notes
`object`string = "payout_bank_connection"	—
`id`string	—
`link_method`enum	one of `sandbox`, `plaid`
`bank_name`string	—
`account_last4`string	—
`connected_at`string (date-time)	—
`connected_email`string	The login email that confirmed the connection.
`authorization`object \| null	The signed authorization to debit the partner's bank account for fees its commissions do not cover. Null when none is in force. The sealed account numbers are never returned. Its fields are listed under `agentPayoutBank · connection.authorization`.

Example

Confirm it with the password

POST /v1/agent/bank/intents/e702801f-2fad-49ea-949c-75fd3e018f41/confirm

curl -X POST https://partners.socialmatterspay.com/v1/agent/bank/intents/e702801f-2fad-49ea-949c-75fd3e018f41/confirm \
  -H 'Authorization: Bearer agent_session_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "password": "correct horse battery staple"
}'

Response · 201

HTTP 201
Cache-Control: no-store

{
  "data": {
    "object": "payout_bank_connection",
    "id": "66ce6a91-5a2f-42f4-8716-7d8d71c015b1",
    "link_method": "sandbox",
    "bank_name": "Sandbox test bank",
    "account_last4": "9606",
    "connected_at": "2026-10-28T00:22:38.331Z",
    "connected_email": "sam@ridgeline.example",
    "authorization": null
  }
}

GET /v1/agent/applications

The merchants this agent submitted or referred

Agent session

Host https://partners.socialmatterspay.com

Responses

Status	Meaning
`200`	Applications
`401`	Error — error shape and codes
`403`	Error — error shape and codes

Fields of the response (200)

Field Notes

applicationsarray of object

The merchant applications the agent started, newest first, at most 200.

20 child fields

`id`string	—
`reference`string	—
`status`enum	one of `draft`, `submitted`, `info_requested`, `approved`, `declined`
`legal_name`string \| null	—
`dba_name`string \| null	—
`contact_email`string	—
`started_by`enum	one of `applicant`, `partner`, `agent`
`referral_status`enum	one of `none`, `attributed`, `pending_review`, `invalid`, `withheld`, `rejected`
`proposed_bps`integer \| null	—
`proposed_fixed_cents`integer \| null	—
`proposed_cap_cents`integer \| null	—
`pricing_decision`enum	Whether SMP accepted the proposed price or changed it. Null until decided. one of `accepted`, `changed`,
`approved_bps`integer \| null	—
`approved_fixed_cents`integer \| null	—
`approved_cap_cents`integer \| null	—
`created_at`string (date-time)	—
`submitted_at`string \| null (date-time)	—
`decided_at`string \| null (date-time)	—
`proposed_pricing_text`string \| null	The proposed price in words: its percentage, its fixed part per payment, and its cap when it has one. Null when none was proposed.
`approved_pricing_text`string \| null	The price SMP set, in words. Null until one is set.

Example

The applications this agent started

GET /v1/agent/applications

curl https://partners.socialmatterspay.com/v1/agent/applications \
  -H 'Authorization: Bearer agent_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "applications": [
    {
      "id": "7f62bbbb-ff11-4aaa-8e19-8e34ef5b4df4",
      "reference": "SMP-B6XJ-XE34",
      "status": "draft",
      "legal_name": "Saltmarsh Supply LLC",
      "dba_name": "Saltmarsh Supply",
      "contact_email": "owner@saltmarsh.example",
      "started_by": "agent",
      "referral_status": "attributed",
      "proposed_bps": 125,
      "proposed_fixed_cents": 35,
      "proposed_cap_cents": 450,
      "pricing_decision": null,
      "approved_bps": null,
      "approved_fixed_cents": null,
      "approved_cap_cents": null,
      "created_at": "2026-10-28T00:22:38.334Z",
      "submitted_at": null,
      "decided_at": null,
      "proposed_pricing_text": "1.25% + $0.35 per payment, capped at $4.50",
      "approved_pricing_text": null
    }
  ]
}

POST /v1/agent/applications

Submit a merchant as an agent (attributed to the agent and its partner)

Agent session

Host https://partners.socialmatterspay.com

Request body

Field Notes

contact requiredobject

3 child fields

`email` requiredstring	—
`phone` requiredstring	—
`name`string	—

business requiredobject

3 child fields

`legal_name` requiredstring	—
`dba_name`string	—
`website_url` requiredstring	—

sales requiredobject

4 child fields

`monthly_volume_cents` requiredinteger	—
`avg_ticket_cents` requiredinteger	—
`max_ticket_cents` requiredinteger	—
`integration_types` requiredarray of string	—

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
`403`	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 —

statusstring = "draft" —

link_sent_tostring The merchant's email address with most of the name masked; the link to finish the application was sent there.

proposed_pricingobject

A price as a rate plus a fixed fee per payment, with an optional cap.

3 child fields

`bps`integer	The rate in basis points (100 = 1%).
`fixed_cents`integer	—
`cap_cents`integer \| null	The most the fee can be on one payment. Null for no cap.

proposed_pricing_textstring —

Example

Start a merchant's application as an agent

POST /v1/agent/applications

curl -X POST https://partners.socialmatterspay.com/v1/agent/applications \
  -H 'Authorization: Bearer agent_session_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "contact": {
    "email": "owner@saltmarsh.example",
    "phone": "(813) 555-0144",
    "name": "Jennifer Thompson"
  },
  "business": {
    "legal_name": "Saltmarsh Supply LLC",
    "dba_name": "Saltmarsh Supply",
    "website_url": "https://saltmarsh.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-6002",
      "address_line1": "9 Bay Rd",
      "address_city": "Tampa",
      "address_state": "FL",
      "address_postal_code": "33606",
      "email": "owner@saltmarsh.example"
    }
  ],
  "pricing": {
    "bps": 125,
    "fixed_cents": 35,
    "cap_cents": 450
  }
}'

Response · 201

HTTP 201
Cache-Control: no-store

{
  "data": {
    "object": "application",
    "id": "7f62bbbb-ff11-4aaa-8e19-8e34ef5b4df4",
    "reference": "SMP-B6XJ-XE34",
    "status": "draft",
    "link_sent_to": "o••••@saltmarsh.example",
    "proposed_pricing": {
      "bps": 125,
      "fixed_cents": 35,
      "cap_cents": 450
    },
    "proposed_pricing_text": "1.25% + $0.35 per payment, capped at $4.50"
  }
}

The agent account

Responses

Fields of the response (200)

Set the bank account the agent is paid to (sealed at rest)

Request body

Responses

Fields of the response (200)

Set the agent's tax ID (sealed at rest; required before any payout)

Request body

Responses

Fields of the response (200)

The agent's referral links

Responses

Fields of the response (200)

Merchants the agent referred

Responses

Fields of the response (200)

The agent's commission ledger for a date range

Parameters

Responses

Fields of the response (200)

The agent's commission payouts

Responses

Fields of the response (200)

Monthly statement (period = YYYY-MM)

Parameters

Responses

Fields of the response (200)

The connected payout bank (name and last four), the ways to connect one, and SMP's ACH Company ID

Responses

Fields of data (200)

A Plaid Link token for connecting the payout bank

Responses

Fields of data (201)

Resolve the account (Plaid or the sandbox test bank) and fix the debit authorization words

Request body

Responses

Fields of data (201)

An open bank connection intent: the account and the exact authorization words, until it is confirmed or expires

Parameters

Responses

Fields of data (200)

Agree to the exact words and make the bank the payout account

Parameters

Request body

Responses

Fields of data (201)

The merchants this agent submitted or referred

Responses

Fields of the response (200)

Submit a merchant as an agent (attributed to the agent and its partner)

Request body

Responses

Fields of data (201)

Fields of `data` (200)

Fields of `data` (201)

Fields of `data` (201)

Fields of `data` (200)

Fields of `data` (201)

Fields of `data` (201)