Payout Links

Send money with a claim link the recipient opens.

A payout link hands the recipient a hosted page where they choose the debit card the money lands on — you never touch their card details. Available on Paysio Debit & Payouts workspaces only (other workspaces receive a 400), and enabled per mode like the rest of Debit & Payouts. Two types:

Directed — a fixed amount sent to a specific recipient_email. Creating it holds amount + fee against your spendable balance and emails the recipient a claim link. Fee-exclusive: the recipient receives the full amount and you pay the fee.
Request — a reusable form anyone can open and submit a payout request on. No amount and no hold up front; money only moves when you approve a submission (see Payout Requests below).

Lifecycle and webhooks

A directed link moves pending → claiming → paid (or cancelled / expired / failed). When the recipient claims, the underlying payout fires the usual payout.created → payout.paid / payout.failed webhooks — each carrying payout_link_id (and payout_request_id for approved requests) so you can correlate the payout back to the link, exactly like checkout_session_id on payment.completed.

Create Payout Link

Create a payout link. type defaults to 'directed' (requires amount + recipient_email); pass type: 'request' for a reusable request form. Creating a directed link holds amount + fee against your balance and emails the recipient a claim link.

POSThttps://paysio.com/api/v1/payout-links

Authorizations

Authorizationstringheaderrequired

Secret key (sk_*). Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Body

typestring

"directed" (default) or "request"

amountintegerrequired

Directed only. Amount in cents the recipient receives (you also pay the fee — the link holds amount + fee)

recipient_emailstringrequired

Directed only. The link is locked to this email; the recipient verifies it to claim

currencystring

Only "USD" is supported (default: USD)

notestring

Message shown to the recipient (max 300 chars)

allowed_railsarray

Rails offered on the claim page. Default ["card"]

custom_fieldsarray

Checkout-style fields to collect from the recipient: { label, type (text|textarea|number|select|checkbox), required?, options? }

expires_in_daysinteger

Directed only. 1–90, default 7. Request links never expire

restrict_to_existing_customersboolean

Request only. Reject submissions from emails that are not already your customer

max_request_amountinteger

Request only. Cents. The most a requester may ask for on this link. Omit or null for no limit

slugstring

Optional custom URL slug. Auto-generated (unguessable) when omitted

metadataobject

Arbitrary key-value metadata stored on the link

Example request — cURL

curl -X POST https://paysio.com/api/v1/payout-links \
  -H "Authorization: Bearer sk_test_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 0,
  "recipient_email": "..."
}'

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/payout-links", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "amount": 0,
    "recipient_email": "..."
  }),
})
const data = await res.json()

Example response (200)

{
  "data": {
    "id": "uuid",
    "object": "payout_link",
    "payout_link_number": 1,
    "payout_link_label": "#00001",
    "type": "directed",
    "slug": "k3f9d2a1b",
    "url": "https://paysio.com/payout/k3f9d2a1b",
    "amount": 5000,
    "currency": "USD",
    "recipient_email": "[email protected]",
    "note": "Your refund",
    "allowed_rails": ["card"],
    "custom_fields": [],
    "restrict_to_existing_customers": false,
    "max_request_amount": null,
    "status": "pending",
    "payout_id": null,
    "expires_at": "2026-01-22T10:30:00.000Z",
    "metadata": {},
    "sandbox": true,
    "created_at": "2026-01-15T10:30:00.000Z"
  }
}

Example response (400)

{
  "error": "Invalid request parameters",
  "type": "invalid_request_error",
  "code": "parameter_invalid"
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

List Payout Links

List payout links, most recent first. Sandbox-aware: test keys only see sandbox links.

GEThttps://paysio.com/api/v1/payout-links

Authorizations

Authorizationstringheaderrequired

Any API key. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Query parameters

limitinteger

1-100, default 10

starting_afterstring

Cursor for pagination (the id of the last item on the previous page)

typestring

Filter by "directed" or "request"

statusstring

Filter by status (pending, claiming, paid, active, cancelled, expired, failed)

Example request — cURL

curl -X GET https://paysio.com/api/v1/payout-links \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/payout-links", {
  method: "GET",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "data": [
    {
      "id": "uuid",
      "object": "payout_link",
      "type": "directed",
      "slug": "k3f9d2a1b",
      "url": "https://paysio.com/payout/k3f9d2a1b",
      "amount": 5000,
      "currency": "USD",
      "recipient_email": "[email protected]",
      "status": "paid",
      "payout_id": "payout-uuid",
      "created_at": "2026-01-15T10:30:00.000Z"
    }
  ],
  "has_more": false
}

Example response (400)

{
  "error": "Invalid request parameters",
  "type": "invalid_request_error",
  "code": "parameter_invalid"
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Get Payout Link

Retrieve a single payout link, including its current status and (once claimed) the linked payout id.

GEThttps://paysio.com/api/v1/payout-links/:id

Authorizations

Authorizationstringheaderrequired

Any API key. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Example request — cURL

curl -X GET https://paysio.com/api/v1/payout-links/:id \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/payout-links/:id", {
  method: "GET",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "data": {
    "id": "uuid",
    "object": "payout_link",
    "type": "directed",
    "slug": "k3f9d2a1b",
    "url": "https://paysio.com/payout/k3f9d2a1b",
    "amount": 5000,
    "currency": "USD",
    "recipient_email": "[email protected]",
    "status": "paid",
    "payout_id": "payout-uuid",
    "expires_at": "2026-01-22T10:30:00.000Z",
    "created_at": "2026-01-15T10:30:00.000Z"
  }
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (404)

{
  "error": "Resource not found",
  "type": "not_found_error",
  "code": "resource_missing"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Cancel Payout Link

Cancel a pending directed link (or an active request link) and release the held balance. Fails with 409 if the link has already been claimed or is otherwise no longer cancellable.

POSThttps://paysio.com/api/v1/payout-links/:id/cancel

Authorizations

Authorizationstringheaderrequired

Secret key (sk_*). Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Example request — cURL

curl -X POST https://paysio.com/api/v1/payout-links/:id/cancel \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/payout-links/:id/cancel", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "data": {
    "id": "uuid",
    "object": "payout_link",
    "status": "cancelled",
    "created_at": "2026-01-15T10:30:00.000Z"
  }
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (404)

{
  "error": "Resource not found",
  "type": "not_found_error",
  "code": "resource_missing"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Payout requests

Submissions made against a request-type payout link. Each submission captures the requester's debit card, so approving one simply runs the money-out to it. Approving checks your spendable balance at that moment (there is no up-front hold like directed links).

List Payout Requests

List payout requests (submissions) across your request links.

GEThttps://paysio.com/api/v1/payout-requests

Authorizations

Authorizationstringheaderrequired

Any API key. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Query parameters

limitinteger

1-100, default 10

starting_afterstring

Cursor for pagination

payout_link_idstring

Only requests submitted to this request link

statusstring

Filter by status: pending, approved, rejected, failed

Example request — cURL

curl -X GET https://paysio.com/api/v1/payout-requests \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/payout-requests", {
  method: "GET",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "data": [
    {
      "id": "uuid",
      "object": "payout_request",
      "payout_link_id": "link-uuid",
      "requester_email": "[email protected]",
      "requester_name": "Sam Lee",
      "amount": 2500,
      "requested_amount": null,
      "currency": "USD",
      "status": "pending",
      "card_last_four": "4242",
      "payout_id": null,
      "created_at": "2026-01-15T10:30:00.000Z"
    }
  ],
  "has_more": false
}

Example response (400)

{
  "error": "Invalid request parameters",
  "type": "invalid_request_error",
  "code": "parameter_invalid"
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Get Payout Request

Retrieve a single payout request.

GEThttps://paysio.com/api/v1/payout-requests/:id

Authorizations

Authorizationstringheaderrequired

Any API key. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Example request — cURL

curl -X GET https://paysio.com/api/v1/payout-requests/:id \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/payout-requests/:id", {
  method: "GET",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "data": {
    "id": "uuid",
    "object": "payout_request",
    "payout_link_id": "link-uuid",
    "requester_email": "[email protected]",
    "amount": 2500,
    "requested_amount": null,
    "currency": "USD",
    "status": "pending",
    "card_last_four": "4242",
    "payout_id": null,
    "created_at": "2026-01-15T10:30:00.000Z"
  }
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (404)

{
  "error": "Resource not found",
  "type": "not_found_error",
  "code": "resource_missing"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Approve Payout Request

Approve a pending request and pay the requester (runs the AptPay money-out to the card captured at submit time). Returns the request with status 'approved' and the resulting payout_id. 409 if it is no longer pending; 400 if your balance is insufficient (the request reverts to pending so you can retry).

POSThttps://paysio.com/api/v1/payout-requests/:id/approve

Authorizations

Authorizationstringheaderrequired

Secret key (sk_*). Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Body

amountinteger

Optional. Cents to send instead of what was asked for, e.g. the ask minus your own handling fee. Omit to pay the requested amount. The original ask is preserved as requested_amount

Example request — cURL

curl -X POST https://paysio.com/api/v1/payout-requests/:id/approve \
  -H "Authorization: Bearer sk_test_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 0
}'

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/payout-requests/:id/approve", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "amount": 0
  }),
})
const data = await res.json()

Example response (200)

{
  "data": {
    "id": "uuid",
    "object": "payout_request",
    "amount": 2000,
    "requested_amount": 2500,
    "status": "approved",
    "payout_id": "payout-uuid",
    "created_at": "2026-01-15T10:30:00.000Z"
  }
}

Example response (400)

{
  "error": "Invalid request parameters",
  "type": "invalid_request_error",
  "code": "parameter_invalid"
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (404)

{
  "error": "Resource not found",
  "type": "not_found_error",
  "code": "resource_missing"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Reject Payout Request

Reject a pending request. No money moves.

POSThttps://paysio.com/api/v1/payout-requests/:id/reject

Authorizations

Authorizationstringheaderrequired

Secret key (sk_*). Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Example request — cURL

curl -X POST https://paysio.com/api/v1/payout-requests/:id/reject \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/payout-requests/:id/reject", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "data": {
    "id": "uuid",
    "object": "payout_request",
    "status": "rejected",
    "created_at": "2026-01-15T10:30:00.000Z"
  }
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (404)

{
  "error": "Resource not found",
  "type": "not_found_error",
  "code": "resource_missing"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}