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

EntitlementDescriptionRequired Verification LevelNotes / Additional Info
base_payoutAllows users to initiate payouts in a variety of fiat currencies, supporting both SWIFT and local payment methods.individual_base or business_baseStandard entitlement for both individuals and businesses.
virtual_accountAllows users to create and receive funds into a virtual account.individual_base or business_baseStandard entitlement for both individuals and businesses

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/available

2. 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}/requirements

4. Check the entitlement phase

GET /api/v1/customers/{customer_id}

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.

On this page