The partner program API · Social Matter Payments API

How partners earn

A partner brings merchants to Social Matter Payments, directly or through agents the partner invites. SMP underwrites and contracts every merchant; partners never handle applications or merchant money.

Each referred merchant carries a pool of 25% of SMP's fee for 24 months, counted from that merchant's first settled payment.
The partner sets each agent's cut of the pool and keeps the rest. A merchant the partner brings without an agent leaves the whole pool to the partner.
Commissions are paid monthly, on the 1st, for the month before, from SMP's own fee revenue. They are never taken from merchant funds.
A payout needs a payout bank account and a tax ID on file. Change the bank from the portal: POST /v1/partner/bank/intents fixes the exact words for the new account, and POST /v1/partner/bank/intents/{id}/confirm signs them with your password, re-entered. An agent changes theirs the same way, without signing a debit authorization.
A deactivated agent keeps what they already earned; after that the partner receives the full pool. A suspended partner keeps earning, but payouts are held until the partner is reinstated.

The arithmetic

In whole cents, on every fee SMP keeps: pool = floor(fee × 25%), agent = floor(pool × agent's cut), partner = pool − agent. Rounding never pays out more than the pool.

Applying

An application names the bank account SMP may debit for partner fees your commissions don't cover, and accepts the exact authorization words for it: get them from POST /v1/partners/fee-debit-authorization/preview, show them to the signer, and send their text_sha256 with POST /v1/partners/apply. The answer carries the application fee and its checkout_url, where the applicant pays by card on the payment provider's page; SMP never sees the card. An application is reviewed once the provider confirms the payment.

Apply as a partner

The response · 201

Response · 201

HTTP 201
Cache-Control: no-store

{
  "partner_id": "1506590a-fda8-428f-8ed1-cf5a8e52f8f5",
  "status": "pending",
  "application_fee": {
    "provider": "whop",
    "amount_cents": 29900,
    "currency": "USD",
    "status": "awaiting_payment",
    "checkout_url": "https://whop.com/checkout/ch_e2e000001",
    "paid_at": null
  },
  "fee_debit_authorization": {
    "entry_code": "CCD",
    "account_last4": "3444",
    "text_sha256": "e34143589ec46d06db50db75854f9699b7e796f6db518f607ed6da17da6aa42f"
  }
}

What SMP charges partners

Besides the application fee, a partner pays a monthly fee and a monthly fee for each agent who accepted an invite; GET /v1/partner/fees shows each one and how it was settled. A month's fees come off that month's commission payout. What the commissions don't cover is debited from the authorized account: as a business debit (CCD) right away, or as a personal debit (PPD) after ten days' notice. A returned fee debit makes those fees owed again and suspends the partner. Partner fees never count toward the 25% pool.

Move fee debits to another account with PUT /v1/partner/fee-debit-authorization, accepting the words for that account; the old authorization ends and is kept for two years.

SMP's fees on the partner and how they were settled

The response · 200

Response · 200

HTTP 200
Cache-Control: no-store

{
  "application_fee": {
    "provider": "whop",
    "amount_cents": 29900,
    "status": "paid",
    "paid_at": "2026-10-28T00:22:37.983Z"
  },
  "fees": [
    {
      "id": "pfa:agent.monthly:62a14022-b94b-4d55-b7d7-bd0eb19611c2:2026-10",
      "code": "agent.monthly",
      "amount_cents": 5000,
      "period": "2026-10",
      "subject_agent_id": "62a14022-b94b-4d55-b7d7-bd0eb19611c2",
      "agent_name": "Sam Ortiz",
      "status": "collected",
      "netted_payout_id": null,
      "collection_id": "pfc_2e37e987-24f4-40c2-8048-bf454f2d6faf",
      "assessed_at": "2026-11-01T00:00:00.000Z"
    },
    {
      "id": "pfa:partner.monthly:1506590a-fda8-428f-8ed1-cf5a8e52f8f5:2026-10",
      "code": "partner.monthly",
      "amount_cents": 9900,
      "period": "2026-10",
      "subject_agent_id": null,
      "agent_name": null,
      "status": "collected",
      "netted_payout_id": null,
      "collection_id": "pfc_2e37e987-24f4-40c2-8048-bf454f2d6faf",
      "assessed_at": "2026-11-01T00:00:00.000Z"
    }
  ],
  "collections": [
    {
      "id": "pfc_2e37e987-24f4-40c2-8048-bf454f2d6faf",
      "period_end": "2026-11-01T00:00:00.000Z",
      "fees_cents": 14900,
      "commissions_applied_cents": 26,
      "debit_cents": 14874,
      "entry_code": "CCD",
      "status": "debit_submitted",
      "debit_scheduled_for": "2026-10-28T00:22:38.192Z",
      "return_code": null,
      "created_at": "2026-10-28T00:22:38.192Z",
      "submitted_at": "2026-10-28T00:22:38.194Z",
      "settled_at": null,
      "returned_at": null
    }
  ]
}

Partner owners and agents sign in the same way, in two steps. POST /v1/partners/login takes the email and password and answers with a challenge; POST /v1/partners/login/verify takes the challenge and a current code from an authenticator app (or a backup code) within 10 minutes, and answers with the token you send as Authorization: Bearer …. The first sign-in enrols the authenticator: its answer carries the secret and an otpauth:// address for the app, and the second step returns 10 backup codes, shown once. A session lasts 12 hours. Five wrong passwords in a row lock the login for 15 minutes.

Partner sign-in, step 1: the password (the first time, an authenticator is enrolled)

The response · 200

Response · 200

HTTP 200
Cache-Control: no-store

{
  "object": "sign_in_challenge",
  "challenge": "sign_in_challenge",
  "step": "enroll",
  "expires_at": "2026-10-28T00:32:38.030Z",
  "secret": "authenticator_secret",
  "otpauth_uri": "otpauth://totp/Social%20Matter%20Payments%3Amorgan%40ridgeline.example?secret=authenticator_secret&issuer=Social%20Matter%20Payments&algorithm=SHA1&digits=6&period=30",
  "role": "owner"
}

Partner sign-in, step 2: the authenticator code

The response · 200

Response · 200

HTTP 200
Cache-Control: no-store

{
  "token": "partner_session_token",
  "expires_at": "2026-10-28T12:22:38.033Z",
  "role": "owner",
  "partner_id": "1506590a-fda8-428f-8ed1-cf5a8e52f8f5",
  "agent_id": null,
  "backup_codes": [
    "backup_code_11",
    "backup_code_12",
    … 8 more
  ]
}

A forgotten password gets an emailed link (POST /v1/partners/password/forgot, the same answer for any address), and POST /v1/partners/password/reset sets a new one; it ends the login's sessions.

Agents

Invite an agent with a cut in basis points, from 0 to 10000 (10000 is the whole pool). The invite carries a one-time link, valid for 7 days; the agent opens it and sets a password with POST /v1/agents/accept-invite, whose answer enrols their authenticator, and finishes with the first code. Change a cut with PATCH /v1/partner/agents/{id}; it applies to commissions from then on.

Invite an agent at a 40% cut

POST /v1/partner/agents

curl -X POST https://partners.socialmatterspay.com/v1/partner/agents \
  -H 'Authorization: Bearer partner_session_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Sam Ortiz",
  "email": "sam@ridgeline.example",
  "cut_bps": 4000
}'

The response · 201

Response · 201

HTTP 201
Cache-Control: no-store

{
  "agent_id": "62a14022-b94b-4d55-b7d7-bd0eb19611c2",
  "status": "invited",
  "cut_bps": 4000,
  "invite_token": "agent_invite_token",
  "invite_expires_at": "2026-11-04T00:22:38.047Z",
  "invite_url": "https://partners.socialmatterspay.test/accept-invite?token=agent_invite_token"
}

Referral links

Create a link for yourself or for one of your agents. When a merchant follows it, the link sets a cookie that credits you for 30 days and sends them to the merchant application with the code attached.

Create a referral link for the agent

The response · 201

Response · 201

HTTP 201
Cache-Control: no-store

{
  "link_id": "ad78c3b9-8360-4dc1-8712-c5c8257e7ca0",
  "code": "z8cg3sg5mr",
  "path": "/r/z8cg3sg5mr"
}

A merchant follows the link

GET /r/z8cg3sg5mr

curl https://partners.socialmatterspay.com/r/z8cg3sg5mr

The response · 302

Response · 302

HTTP 302
Location: https://socialmatterspay.test/apply?ref=z8cg3sg5mr
Set-Cookie: smp_ref=z8cg3sg5mr; Max-Age=2592000; Path=/; Secure; SameSite=Lax
Cache-Control: no-store

Starting a merchant's application

A partner or an agent can start a merchant's application from the portal with POST /v1/partner/applications: the business, its owners and a proposed price. SMP emails the merchant a link to finish it, and GET /v1/partner/applications shows where each one stands. A proposed price can't be below SMP's floor (GET /v1/partner/pricing-floor); a link can carry one for the merchants who apply through it (PUT /v1/partner/links/{id}/pricing). SMP accepts or changes it when it reviews the application.

Start a merchant's application: the merchant is emailed a link to finish it

The response · 201

Response · 201

HTTP 201
Cache-Control: no-store

{
  "data": {
    "object": "application",
    "id": "75684289-bb07-4552-84ff-a5d3b4bca687",
    "reference": "SMP-8WKZ-14PC",
    "status": "draft",
    "link_sent_to": "o••••@tidewater.example",
    "proposed_pricing": {
      "bps": 125,
      "fixed_cents": 35,
      "cap_cents": 450
    },
    "proposed_pricing_text": "1.25% + $0.35 per payment, capped at $4.50"
  }
}

Earnings, payouts and statements

Read what you earned over any range with GET /v1/partner/earnings, your commission payouts with GET /v1/partner/payouts, and one month's statement, with every merchant, adjustment and payout, with GET /v1/partner/statements/{period}. Agents have the same three calls for their own share. The statement below counts one referred merchant's settled payment, the month's fees and how they were settled.

Monthly statement

The response · 200

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,
      "partner_cents": 26
    }
  ],
  "clawbacks": [],
  "payouts": [],
  "fees": [
    {
      "id": "pfa:agent.monthly:62a14022-b94b-4d55-b7d7-bd0eb19611c2:2026-10",
      "code": "agent.monthly",
      "amount_cents": 5000,
      "period": "2026-10",
      "subject_agent_id": "62a14022-b94b-4d55-b7d7-bd0eb19611c2",
      "status": "collected",
      "netted_payout_id": null,
      "collection_id": "pfc_2e37e987-24f4-40c2-8048-bf454f2d6faf",
      "assessed_at": "2026-11-01T00:00:00.000Z"
    },
    {
      "id": "pfa:partner.monthly:1506590a-fda8-428f-8ed1-cf5a8e52f8f5:2026-10",
      "code": "partner.monthly",
      "amount_cents": 9900,
      "period": "2026-10",
      "subject_agent_id": null,
      "status": "collected",
      "netted_payout_id": null,
      "collection_id": "pfc_2e37e987-24f4-40c2-8048-bf454f2d6faf",
      "assessed_at": "2026-11-01T00:00:00.000Z"
    }
  ],
  "fee_collections": [
    {
      "id": "pfc_2e37e987-24f4-40c2-8048-bf454f2d6faf",
      "fees_cents": 14900,
      "commissions_applied_cents": 26,
      "debit_cents": 14874,
      "entry_code": "CCD",
      "status": "debit_submitted",
      "debit_scheduled_for": "2026-10-28T00:22:38.192Z",
      "return_code": null,
      "created_at": "2026-10-28T00:22:38.192Z"
    }
  ],
  "totals": {
    "earned_cents": 46,
    "voided_cents": 0,
    "clawback_cents": 0,
    "paid_out_cents": 0,
    "fees_cents": 14900,
    "fees_netted_from_payouts_cents": 0,
    "fees_collected_cents": 14900,
    "fees_open_cents": 0
  }
}

How partners earn

The arithmetic

Applying

What SMP charges partners

Sign-in

Agents

Referral links

Starting a merchant's application

Earnings, payouts and statements