Onboard an end-customer
A customer is one of your end-users — the person you’re moving money on behalf of (e.g. a Pouch app user). You create the customer once, verify their identity, then issue them international accounts and send payouts attributed to them.
This page explains the onboarding flow and the decisions that matter. For request/response schemas, fields, and code samples, see the Customers API reference.
Where this fits
Create customer → Verify KYC → Issue collection account → Send payouts
(this page) (KYC guide) (VIBAN guide) (Payouts API)One customer per end-user
Pass your identifier for the user as customer_reference (e.g. your internal user UUID). It’s unique per merchant per env and it dedupes creates — calling create again with the same reference returns the existing customer rather than making a duplicate. See idempotency & retries.
The Swappr customer id (cus_...) is what you use on every nested call and when attributing a payout. The upstream banking partner’s own identifier is never exposed — we translate it server-side.
Identity fields are immutable once submitted
id_type, id_number, and the name fields cannot be corrected after submission. id_type is country-specific (e.g. NG individuals accept International Passport or Driver’s License, not the NIN slip). If verification rejects on any of these, you retry with a new customer_reference — the update endpoint only edits contact + address fields.
See the country + ID allowlist for what each country accepts.
id_expiry_date is required for individuals (YYYY-MM-DD, a future date). The banking partner needs it to provision the customer’s virtual account, and — like id_type/id_number — it cannot be added after the customer verifies. Omitting it creates a customer that can never receive a VBA and fails later with a misleading “missing ID Expiry Date” error. id_issue_date is optional but is likewise not updatable post-create, so set it now if you’ll ever need it.
PII at rest: KYC payloads (name, DOB, ID number, address, TIN) are AES-256-GCM encrypted in our database with a key Technest controls. For compliance review, request a pii_view on a specific customer through admin tooling.
Customer lifecycle
pending → (documents uploaded + verified by our regulated partner) → verified or rejected. Account provisioning and payouts both require verified. Subscribe to the customer.status_changed webhook for the transition.
Next
- Verify an end-customer → — upload documents + submit for review
- Customers API reference → — create / list / retrieve / update endpoints, fields, and errors