Docs / Core Guides / Hosted Payout Links

Hosted Payout Links

Hosted Payout Links allow you to pay recipients without collecting or storing their sensitive bank account details.

You generate a payment link on your server, send the URL to the recipient (via SMS, email, or your app), and the recipient securely enters their own banking information on an Avvio-hosted payment page.

text

Your Backend
    ↓ (POST /payout-links)
Avvio Generates Single-Use Signed URL
    ↓
Recipient Opens URL in Browser
    ↓
Avvio Collects Bank Details & Debits Your Balance
    ↓
Payout Executes & Settles

Why Use Payout Links#

Zero Banking Data Touch: Bank account and routing numbers never touch your servers, keeping them completely outside your compliance and security surface.
Automatic Form Updates: When banking corridors update their required fields, Avvio updates the hosted form dynamically with zero changes required in your codebase.
Single-Use Signed Tokens: Permanent API credentials and private keys are never exposed to the client or recipient browser.

1. Create a Payout Link#

Call POST /payments/organizations/{orgId}/payout-links from your secure backend:

http

POST /payments/organizations/{orgId}/payout-links
Idempotency-Key: 3f81e921-bc01-447a-9a11-0982716a5b42
Content-Type: application/json

{
  "amount": "75.00",
  "destinationCurrency": "MXN",
  "endUserId": "employee_42",
  "reference": "ZZ-WAGE-1",
  "expiresInMinutes": 60
}

Response:

json

{
  "payoutLinkId": "plink_991823ab",
  "url": "https://pay.avvio.xyz/l/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2026-08-17T05:28:39.569Z",
  "status": "pending"
}

NOTE

Your Idempotency-Key is attached to the link record. Minting the link twice cannot result in double payouts even if a user attempts to submit multiple times.

2. Recipient Endpoints#

The hosted page communicates with two public endpoints using the single-use signed token embedded in the URL:

http

GET  /payout-links/{token}
POST /payout-links/{token}/submit

Security & Privacy Protections#

Data Minimization: The GET /payout-links/{token} response returns only the payout amount, destination currency, and required input fields. It never reveals your internal orgId, endUserId, or previously entered bank details.
Double-Tap Protection: Submitting the form twice returns the original payout record with status: "already_submitted", ensuring mobile connections with duplicate taps do not produce duplicate payouts.
Validation Retry: Form validation errors (e.g. mistyped account digits) keep the token active so the recipient can correct their input.
Constant 404 on Invalid Tokens: Expired, spent, revoked, or tampered tokens return a uniform 404 Not Found to prevent timing probes.