Collections

Create and manage payment collections from customers.

Authentication Collections Payouts Customers Balances Webhooks Products Disputes FX Rates

POST/v1/collections

Create a new payment collection

Parameters

Name	Type	In	Required	Description
`amount`	`integer`	body	Required	Amount in smallest currency unit (e.g., cents)
`currency`	`string`	body	Required	ISO 4217 currency code
`customer_id`	`string`	body	Optional	Existing customer ID
`payment_method`	`string`	body	Required	Payment method type: card, bank_transfer, stablecoin
`description`	`string`	body	Optional	Internal description for this collection
`metadata`	`object`	body	Optional	Key-value pairs for your reference
`idempotency_key`	`string`	header	Required	Unique key to prevent duplicate charges

Response Codes

201Collection created400Invalid parameters402Payment failed409Duplicate idempotency key422Unprocessable payment method

1{
2  "id": "col_a1b2c3d4",
3  "object": "collection",
4  "amount": 5000,
5  "currency": "USD",
6  "status": "pending",
7  "customer_id": "cus_8a3b7c9d",
8  "payment_method": "card",
9  "description": "Monthly subscription - Pro plan",
10  "metadata": {
11    "order_id": "ord_12345",
12    "plan": "pro"
13  },
14  "created_at": "2026-05-01T14:30:00Z",
15  "client_secret": "col_a1b2c3d4_secret_xyz..."
16}

GET/v1/collections/{id}

Retrieve a collection by ID

Parameters

Name	Type	In	Required	Description
`id`	`string`	path	Required	Collection ID

Response Codes

200Collection retrieved404Collection not found

1{
2  "id": "col_a1b2c3d4",
3  "object": "collection",
4  "amount": 5000,
5  "currency": "USD",
6  "status": "succeeded",
7  "customer_id": "cus_8a3b7c9d",
8  "payment_method": "card",
9  "captured_at": "2026-05-01T14:30:05Z",
10  "created_at": "2026-05-01T14:30:00Z"
11}

GET/v1/collections

List all collections with pagination and filters

Parameters

Name	Type	In	Required	Description
`limit`	`integer`	query	Optional	Number of results (1-100, default 25)
`starting_after`	`string`	query	Optional	Cursor for pagination
`status`	`string`	query	Optional	Filter by status: pending, succeeded, failed, refunded
`created_gte`	`string`	query	Optional	Filter by creation date (ISO 8601)
`created_lte`	`string`	query	Optional	Filter by creation date (ISO 8601)

Response Codes

200List of collections

1{
2  "object": "list",
3  "data": [
4    {
5      "id": "col_a1b2c3d4",
6      "object": "collection",
7      "amount": 5000,
8      "currency": "USD",
9      "status": "succeeded",
10      "created_at": "2026-05-01T14:30:00Z"
11    }
12  ],
13  "has_more": true,
14  "next_cursor": "col_e5f6g7h8"
15}

POST/v1/collections/{id}/capture

Capture a previously authorized collection

Parameters

Name	Type	In	Required	Description
`id`	`string`	path	Required	Collection ID
`amount`	`integer`	body	Optional	Amount to capture. Defaults to full authorized amount

Response Codes

200Collection captured400Collection not in capturable state404Collection not found

1{
2  "id": "col_a1b2c3d4",
3  "object": "collection",
4  "amount": 4500,
5  "currency": "USD",
6  "status": "succeeded",
7  "captured_at": "2026-05-01T14:35:00Z"
8}