Entitlements
Entitlements represent an approval for a customer to transact on the Stables platform.
In order for an entitlement to be granted, the necessary verification data must be submitted via the Customers API.
Entitlement Types
Below are the entitlements that can be requested when creating a customer
| Entitlement | Description | Required Verification Level | Notes / Additional Info |
|---|---|---|---|
base_payout | Allows users to initiate payouts in a variety of fiat currencies, supporting both SWIFT and local payment methods. | individual_base or business_base | Standard entitlement for both individuals and businesses. |
virtual_account | Allows users to create and receive funds into a virtual account. | individual_base or business_base | Standard entitlement for both individuals and businesses |
base_pay_in | Allows a business to open a SWIFT collection account and be paid out its deposits. | business_base (approved before an account can be opened) | SWIFT collection accounts are for business customers only. |
cny_unionpay | Allows an individual to send CNY UnionPay payouts (destination.network: "unionpay"): personal remittance to an individual's bank account in mainland China. | individual_base (approved before the entitlement can be requested) | Individual customers only. Request it with the Entitlements API below; requirements.missing lists any sender details still needed, such as source of funds. |
Additional entitlements exist for specific payment rails and currencies (for example,
aed_local) and can be requested independently of customer creation using the Entitlements API described below.
Requesting an Entitlement
Entitlements can also be requested independently of customer creation, for example to add a new product or rail to an existing, already-verified customer.
1. Check available products
Check which entitlements are currently available for the customer to request.
GET /api/v1/customers/{customer_id}/entitlements/available2. Request an entitlement
POST /api/v1/customers/{customer_id}/entitlements
Content-Type: application/json
Authorization: Bearer <your-token>
{
"entitlements": ["aed_local"]
}3. Submit additional requirements
If Stables needs further verification data before the entitlement can be granted, submit it via:
PATCH /api/v1/customers/{customer_id}/entitlements/{entitlement}/requirementsWhat is still needed is listed on the entitlement as requirements.missing and requirements.issues. Two cases come up often for USD accounts:
Tax ID and tax residence. The tax ID in financial_profile.tax_id_number is checked against the format of the customer's nationality. When the customer is tax resident in another country, send that country as financial_profile.tax_residence_country (ISO 3166-1 alpha-2) and the tax ID is checked against that country's format instead. A customer with a United States address or nationality is always asked for an SSN or ITIN. A tax ID that cannot pass is refused with 400 and code INVALID_FIELDS.
PATCH /api/v1/customers/{customer_id}/entitlements/usd_virtual_account/requirements
Content-Type: application/json
Authorization: Bearer <your-token>
{
"financial_profile": {
"tax_id_number": "1100701234567",
"tax_residence_country": "TH"
}
}Proof of source of funds and source of wealth. The USD partner can ask an individual for a proof of source of funds, a source of wealth, or both. When requirements.missing lists proof_of_source_of_funds or source_of_wealth, send each document in its own field in the same request. See SOF & SOW for what is accepted.
{
"proof_of_source_of_funds_documents": [
{ "front_image_data": "data:application/pdf;base64,JVBERi0xLjQK...", "country": "TH" }
],
"source_of_wealth_documents": [
{ "front_image_data": "data:application/pdf;base64,JVBERi0xLjQK...", "country": "TH" }
]
}You can also send either document before it is asked for, with the rest of the application. Both are optional up front: the application does not wait for them. When requirements.actions carries a verification_link for the requirement, you can send that link to the customer instead of uploading the document yourself.
Integrations that send the proof of source of funds as source_of_wealth_documents keep working: when no proof of source of funds is on file, the source of wealth document is sent to the partner as one. Use proof_of_source_of_funds_documents so each document is filed under the type the partner asked for.
4. Check the entitlement phase
GET /api/v1/customers/{customer_id}Each entitlement carries a phase. requires_action means it is waiting on you or your customer, and requirements says for what. ready means it can be used.
Get All Customers returns the same detail (phase, requirements and onboarding) for every customer with an entitlement that has been requested and is not yet approved or rejected, so you can find the customers waiting on you from the list. Other customers carry each entitlement's name and status only.
Payment routes and virtual accounts should only be created once the entitlement's phase is ready. Attempting to create them earlier may fail.
Existing customer create and update requests that include an entitlements array will continue to work during the transition to this dedicated Entitlements API.