Payments

The Payments API allows you to create, list, and manage payouts to recipients.

Payment States

Payments transition through these states:

CREATED → VALIDATED → QUEUED → PROCESSING → SENT → COMPLETED
    ↓         ↓          ↓          ↓         ↓
  FAILED   FAILED    FAILED     FAILED   RETURNED

Create Payment

POST /api/v1/payments

Create a new payment to a recipient.

curl -X POST https://api.paystream.fi/api/v1/payments \
  -H "Authorization: Bearer psk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientId": "rec_abc123",
    "amount": 10000,
    "currency": "usd",
    "rail": "standard",
    "description": "Weekly payout"
  }'

Request Body

Field	Type	Required	Description
recipientId	string	Yes	Recipient ID
amount	integer	Yes	Amount in cents (e.g., 10000 = $100.00)
currency	string	No	Currency code (default: usd)
rail	string	No	Payment rail: standard, same_day_ach, rtp, instant
urgency	boolean	No	Request instant processing
description	string	No	Payment description
metadata	object	No	Custom metadata

Response

{
  "data": {
    "id": "pay_xyz789",
    "recipientId": "rec_abc123",
    "amount": 10000,
    "currency": "usd",
    "rail": "standard",
    "status": "created",
    "description": "Weekly payout",
    "createdAt": "2026-02-19T00:00:00Z"
  }
}

List Payments

GET /api/v1/payments

List all payments with optional filters.

curl -X GET "https://api.paystream.fi/api/v1/payments?status=completed&limit=50" \
  -H "Authorization: Bearer psk_test_xxx"

Query Parameters

Parameter	Type	Description
status	string	Filter by status
recipientId	string	Filter by recipient
startDate	string	Filter from date (ISO 8601)
endDate	string	Filter to date (ISO 8601)
limit	integer	Results per page (default: 50)
cursor	string	Pagination cursor

Get Payment

GET /api/v1/payments/:id

Get details of a specific payment.

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

Cancel Payment

POST /api/v1/payments/:id/cancel

Cancel a payment that hasn't been sent yet.

curl -X POST https://api.paystream.fi/api/v1/payments/pay_xyz789/cancel \
  -H "Authorization: Bearer psk_test_xxx"

Retry Payment

POST /api/v1/payments/:id/retry

Retry a failed payment.

curl -X POST https://api.paystream.fi/api/v1/payments/pay_xyz789/retry \
  -H "Authorization: Bearer psk_test_xxx"

Payment Rails

Rail	Speed	Cost	Use Case
standard	2-3 business days	Free	Regular payouts
same_day_ach	Same business day	$1.00	Urgent ACH
rtp	~30 seconds	1.5% (min $1, max $30)	Instant bank transfer
instant	~30 seconds	2% (min $1.50, max $50)	Push-to-card