Recipients

Recipients are the people or businesses you send payments to.

Create Recipient

POST /api/v1/recipients

Create a new recipient. Optionally provide identity and bank account information inline to enable payouts immediately.

Basic Creation

curl -X POST https://api.paystream.fi/api/v1/recipients \
  -H "Authorization: Bearer psk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Driver",
    "email": "john@example.com",
    "externalId": "DRV001"
  }'

With Inline Identity & Bank Account

Submit identity and bank account in a single call for instant payout readiness:

curl -X POST https://api.paystream.fi/api/v1/recipients \
  -H "Authorization: Bearer psk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Driver",
    "email": "john@example.com",
    "externalId": "DRV001",
    "identity": {
      "firstName": "John",
      "lastName": "Driver",
      "dateOfBirth": "1990-06-15",
      "ssnLast4": "1234",
      "address": {
        "line1": "456 Oak Ave",
        "city": "Austin",
        "state": "TX",
        "postalCode": "78701",
        "country": "US"
      },
      "tosAcceptance": {
        "date": "2026-02-25",
        "ip": "203.0.113.1"
      }
    },
    "bankAccount": {
      "accountNumber": "4242424242",
      "routingNumber": "123456789",
      "accountHolderName": "John Driver",
      "accountHolderType": "individual",
      "accountType": "checking"
    }
  }'

Request Body

Field	Type	Required	Description
name	string	Yes	Full name
email	string	Yes	Email address
externalId	string	No	Your reference ID
identity	object	No	Inline identity for KYC
bankAccount	object	No	Inline bank account

Identity Fields

Field	Type	Required	Description
firstName	string	Yes	Legal first name
lastName	string	Yes	Legal last name
dateOfBirth	string	Yes	YYYY-MM-DD format
ssnLast4	string	Conditional	Last 4 digits of SSN
ssnFull	string	Conditional	Full 9-digit SSN (never stored)
address	object	Yes	US address
tosAcceptance	object	No	Terms of service acceptance

Either ssnLast4 or ssnFull is required. Full SSN is passed directly to the payment provider and never stored.

Response with Inline Fields

{
  "data": {
    "id": "rec_abc123",
    "name": "John Driver",
    "email": "john@example.com",
    "status": "active"
  },
  "meta": {
    "identity": "submitted",
    "bankAccount": "created"
  }
}

If provider submission fails, the recipient is still created and warnings are returned:

{
  "meta": {
    "identityWarning": "Provider submission failed - recipient created without identity",
    "bankAccountWarning": "Bank account creation failed - add manually later"
  }
}

List Recipients

GET /api/v1/recipients

curl -X GET https://api.paystream.fi/api/v1/recipients \
  -H "Authorization: Bearer psk_test_xxx"

Query Parameters

Parameter	Type	Description
status	string	Filter: invited, registered, verified, active, suspended
kycStatus	string	Filter: pending, verified, failed
search	string	Search by name or email
limit	integer	Results per page (default: 50)
cursor	string	Pagination cursor

Get Recipient

GET /api/v1/recipients/:id

Update Recipient

PATCH /api/v1/recipients/:id

Delete Recipient

DELETE /api/v1/recipients/:id

Export Recipients

GET /api/v1/recipients/export

Export recipients as CSV.

Payment Methods

See Payment Methods for managing recipient bank accounts and cards.

Recipient Balances

See Recipient Balances for balance management and withdrawals.