Recipients API
The Recipients API allows you to manage bank account destinations for transfers. Recipients represent verified bank accounts that can receive payouts from your Omise balance.
Overviewโ
Recipients enable you to:
- Store bank account details securely for repeated transfers
- Verify account ownership to prevent fraud and errors
- Manage payees for marketplace sellers, vendors, and affiliates
- Support multiple banks across different countries
- Track recipient metadata for categorization and reporting
Recipient Typesโ
Individual Recipientsโ
Personal bank accounts for individuals. Requires:
- Full name (matching bank account)
- Bank account details
- Email address (optional but recommended)
Corporation Recipientsโ
Business or corporate bank accounts. Requires:
- Company name (matching bank account)
- Tax ID or registration number
- Bank account details
- Email address
Recipient Lifecycleโ
- Create - Add a new recipient with bank account details
- Verify - Verify account ownership (automatic or manual)
- Active - Recipient can receive transfers
- Update - Modify recipient details or metadata
- Delete - Remove recipient (cannot be used for transfers)
Bank Account Informationโ
Recipients require bank account details:
- Bank brand - Bank code (bbl, scb, kbank, ktb, bay, etc.)
- Account number - Full bank account number
- Account name - Account holder name (must match bank records)
- Branch (optional) - Bank branch for some countries
Supported Banks (Thailand)โ
| Bank Code | Bank Name |
|---|---|
| bbl | Bangkok Bank |
| kbank | Kasikornbank |
| scb | Siam Commercial Bank |
| ktb | Krung Thai Bank |
| bay | Bank of Ayudhya (Krungsri) |
| tmb | TMB Bank |
| citi | Citibank |
| smbc | Sumitomo Mitsui Banking Corporation |
| sc | Standard Chartered |
Verification Processโ
Recipients must be verified before receiving transfers:
Automatic Verificationโ
- Omise verifies account details with the bank
- Usually completes within minutes
- Recipient status changes to
verified: true
Manual Verificationโ
- For complex cases or certain bank types
- May require additional documentation
- Contact support for manual verification
Verification Statusesโ
verified: false- Pending verificationverified: true- Verified and ready for transfers- Failed verification results in error during transfer creation
Authenticationโ
All recipient endpoints require your secret key for authentication. Never expose your secret key in client-side code.
Available Endpointsโ
| Method | Endpoint | Description |
|---|---|---|
| POST | /recipients | Create a new recipient |
| GET | /recipients/:id | Retrieve a specific recipient |
| GET | /recipients | List all recipients |
| PATCH | /recipients/:id | Update recipient details |
| DELETE | /recipients/:id | Delete a recipient |
| PATCH | /recipients/:id/verify | Verify recipient account |
Common Use Casesโ
Marketplace Payoutsโ
Create recipient accounts for each seller and process periodic payouts based on sales.
Vendor Managementโ
Store vendor bank accounts for automated invoice payments and expense reimbursements.
Affiliate Programsโ
Manage affiliate partner bank accounts for commission payouts.
Employee Reimbursementsโ
Store employee bank accounts for expense reimbursements and salary payments.
Multi-Currency Payoutsโ
Support international recipients with different currencies and banking systems.
Best Practicesโ
- Verify recipients immediately after creation
- Store recipient IDs in your database
- Use descriptive names for easy identification
- Add email addresses for notification and verification
- Use metadata for categorization (vendor_type, region, etc.)
- Handle verification failures gracefully
- Test with small amounts before large transfers
- Keep recipient information updated (notify when bank details change)
Security Considerationsโ
- PCI compliance - Bank account data is encrypted at rest
- Account verification - Prevents fraudulent transfers
- Access control - Use secret key authentication
- Audit trails - Track all recipient modifications
- Data retention - Recipients can be deleted when no longer needed
Related Resourcesโ
- Transfers API - Send funds to recipients
- Balance API - Check available balance
- Transactions API - View transfer transactions
- Webhooks - Receive recipient verification events
Need help? Contact support@omise.co for bank account verification, supported banks, or integration assistance.