OpenAPI Specification
openapi: 3.0.3
info:
title: Astrada bank-accounts subaccounts API
version: '2024-02-28'
contact:
email: developer@astrada.co
description: 'Welcome to our API Reference. 👋
'
servers:
- url: https://api.astrada.co
security: null
tags:
- name: subaccounts
description: Subaccount resource
paths:
/subaccounts:
post:
tags:
- subaccounts
summary: Create subaccount
description: 'Creates a new subaccount, allowing you to set network and regional configurations.
Each network''s `countries` can be set to either an array of specific ISO 3166 alpha-3 country codes, or the string `"*"` to inherit all countries from the parent account''s capabilities for that network.
When using `"*"`, the subaccount will automatically reflect the parent account''s current country list. If the parent account''s capabilities change, subaccounts configured with `"*"` will inherit the updated countries.
The single and bulk enrollment configurations are not required when creating a subaccount, but if not provided they will default to the same country list as the main `countries` property for that network.
The supported card types for single and bulk enrollment is CONSUMER, while the supported funding card types is DEBIT. If not provided, the block rules for both card types will default to the parent account''s default block rule for that network and enrollment level.
To set the default rule on the parent account, please reach out to your account manager or support.
'
operationId: CreateSubaccount
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the subaccount
configurations:
$ref: '#/components/schemas/create-subaccount-configurations'
required:
- name
- configurations
examples:
Specific countries:
value:
name: Subaccount A
configurations:
VISA:
countries:
- USA
- CAN
MASTERCARD:
countries:
- USA
Wildcard countries:
value:
name: Subaccount B
configurations:
VISA:
countries: '*'
MASTERCARD:
countries: '*'
security:
- main-auth:
- subaccounts:write
responses:
'201':
description: New subaccount created successfully
content:
application/hal+json:
schema:
$ref: '#/components/schemas/subaccount'
examples:
Example Create Subaccount Response:
$ref: '#/components/examples/subaccount'
'400':
$ref: '#/components/responses/bad-request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/server-error'
get:
tags:
- subaccounts
summary: List subaccounts
description: 'Returns a list of all subaccounts associated with the account.
This endpoint supports [cursor-based pagination](https://docs.astrada.co/reference/pagination).
'
operationId: GetSubaccounts
parameters:
- $ref: '#/components/parameters/cursor'
- $ref: '#/components/parameters/limit'
security:
- main-auth:
- subaccounts:read
responses:
'200':
description: Subaccounts list retrieved successfully
content:
application/hal+json:
schema:
type: object
properties:
_embedded:
type: object
required:
- subaccounts
properties:
subaccounts:
type: array
items:
$ref: '#/components/schemas/subaccount'
_links:
type: object
properties:
self:
$ref: '#/components/schemas/link'
next:
$ref: '#/components/schemas/link'
required:
- self
required:
- _embedded
- _links
examples:
Example List Subaccounts Response:
value:
_links:
self:
href: /subaccounts
_embedded:
subaccounts:
- _links:
self:
href: /subaccounts/81e7c267-0927-4234-a2bd-78cef799de54
accountId: 073fe1bb-3350-46ad-b3a6-32afb3780994
id: 81e7c267-0927-4234-a2bd-78cef799de54
name: Subaccount A
createdAt: '2024-05-01T17:08:43.810Z'
updatedAt: '2024-05-01T17:08:43.810Z'
configurations:
VISA:
countries:
- USA
- CAN
single-enrollment:
countries:
- USA
- CAN
blockedCardTypes:
- CONSUMER
blockedFundingCardTypes:
- DEBIT
bulk-enrollment:
countries:
- USA
- CAN
blockedCardTypes:
- CONSUMER
blockedFundingCardTypes:
- DEBIT
MASTERCARD:
countries:
- USA
single-enrollment:
countries:
- USA
blockedCardTypes: []
blockedFundingCardTypes: []
bulk-enrollment:
countries:
- USA
blockedCardTypes: []
blockedFundingCardTypes: []
- _links:
self:
href: /subaccounts/3788493c-49f5-4f5e-9152-56abc2a4e153
accountId: 073fe1bb-3350-46ad-b3a6-32afb3780994
id: 3788493c-49f5-4f5e-9152-56abc2a4e153
name: Subaccount B
createdAt: '2024-05-01T17:08:43.810Z'
updatedAt: '2024-05-01T17:08:43.810Z'
configurations:
VISA:
countries:
- USA
- CAN
single-enrollment:
countries:
- USA
- CAN
blockedCardTypes: []
blockedFundingCardTypes:
- DEBIT
bulk-enrollment:
countries:
- USA
- CAN
blockedCardTypes: []
blockedFundingCardTypes: []
MASTERCARD:
countries:
- USA
single-enrollment:
countries:
- USA
blockedCardTypes:
- CONSUMER
blockedFundingCardTypes: []
bulk-enrollment:
countries:
- USA
blockedCardTypes: []
blockedFundingCardTypes: []
Example no Subaccounts found:
value:
_links:
self:
href: /subaccounts
_embedded:
subaccounts: []
'400':
$ref: '#/components/responses/bad-request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not-found'
'500':
$ref: '#/components/responses/server-error'
/subaccounts/{subaccountId}:
parameters:
- $ref: '#/components/parameters/subaccount-id-2'
get:
tags:
- subaccounts
summary: Retrieve subaccount
description: Returns detailed information about a specific subaccount by its identifier, including configuration details and associated data.
operationId: GetSubaccount
security:
- main-auth:
- subaccounts:read
responses:
'200':
description: Details of the subaccount giving the accountId and subaccountId
content:
application/hal+json:
schema:
$ref: '#/components/schemas/subaccount'
examples:
Example Get Subaccount Response:
$ref: '#/components/examples/subaccount'
'400':
$ref: '#/components/responses/bad-request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not-found'
'500':
$ref: '#/components/responses/server-error'
patch:
tags:
- subaccounts
summary: Update subaccount configurations
description: 'Update a subaccount name and configurations.
All updated configurations are validated against the capabilities of the main account to ensure compliance.
It is possible to add new networks and/or regions but it is not possible to remove any configurations that were previously set.
Each network''s `countries` can be set to either an array of specific ISO 3166 alpha-3 country codes, or the string `"*"` to inherit all countries from the parent account''s capabilities for that network.
When using `"*"`, the subaccount will automatically reflect the parent account''s current country list. If the parent account''s capabilities change, subaccounts configured with `"*"` will inherit the updated countries.
The single and bulk enrollment configurations are not required when creating a subaccount, but if not provided they will default to the same country list as the main countries property for that network. The supported card types for single and bulk enrollment is CONSUMER, while the supported funding card types is DEBIT. If not provided, the block rules for both card types will default to the parent account''s default block rule for that network and enrollment level.
To set the default rule on the parent account, please reach out to your account manager or support.
'
operationId: UpdateSubaccount
security:
- main-auth:
- subaccounts:write
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
configurations:
$ref: '#/components/schemas/create-subaccount-configurations'
name:
type: string
verificationPolicy:
description: 'Set or clear the subaccount''s card verification policy. Customers may set any
level above LOW (MEDIUM, HIGH, HIGHEST), send a null level to clear the
override, and toggle the `sandbox` test flag. LOW is internal-only and is
rejected on this endpoint.
'
allOf:
- $ref: '#/components/schemas/verification-policy'
enrollmentPolicy:
$ref: '#/components/schemas/customer-enrollment-policy'
responses:
'200':
description: Specified subaccount updated successfully
content:
application/hal+json:
schema:
$ref: '#/components/schemas/subaccount'
examples:
Example Update Subaccount Response:
$ref: '#/components/examples/subaccount'
'400':
$ref: '#/components/responses/bad-request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not-found'
'500':
$ref: '#/components/responses/server-error'
components:
parameters:
subaccount-id-2:
in: path
name: subaccountId
required: true
schema:
type: string
format: uuid
example: 24c4f90d-ab3b-4f6e-8a1d-d251a4fcf34c
limit:
in: query
name: limit
description: Maximum number of items to return
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 25
example: 25
cursor:
in: query
name: cursor
required: false
description: The cursor to use for pagination. Identifies your place on the list
schema:
type: string
format: byte
example: ZXhhbXBsZQ==
examples:
subaccount:
description: Example of Subaccount resource
value:
_links:
self:
href: /subaccounts/81e7c267-0927-4234-a2bd-78cef799de54
accountId: 073fe1bb-3350-46ad-b3a6-32afb3780994
id: 81e7c267-0927-4234-a2bd-78cef799de54
name: Subaccount A
createdAt: '2024-05-01T17:08:43.810Z'
updatedAt: '2024-05-01T17:08:43.810Z'
configurations:
VISA:
countries:
- USA
- CAN
single-enrollment:
countries:
- USA
blockedCardTypes:
- CONSUMER
blockedFundingCardTypes:
- DEBIT
bulk-enrollment:
countries:
- CAN
blockedCardTypes:
- CONSUMER
blockedFundingCardTypes:
- DEBIT
MASTERCARD:
countries:
- USA
single-enrollment:
countries:
- USA
blockedCardTypes:
- CONSUMER
blockedFundingCardTypes:
- DEBIT
bulk-enrollment:
countries:
- GBR
blockedCardTypes:
- CONSUMER
blockedFundingCardTypes:
- DEBIT
AMEX:
countries:
- ITA
single-enrollment:
countries:
- ITA
blockedCardTypes:
- CONSUMER
blockedFundingCardTypes:
- DEBIT
bulk-enrollment:
countries:
- SWE
blockedCardTypes:
- CONSUMER
blockedFundingCardTypes:
- DEBIT
schemas:
subaccount-configuration:
type: object
additionalProperties: false
description: Subaccount network and regional configurations which determine the available networks and geographies during card enrollment.
properties:
VISA:
type: object
additionalProperties: false
properties:
countries:
type: array
description: List of contracted regional areas for Visa
uniqueItems: true
items:
type: string
enum:
- USA
- CAN
- IRL
- DEU
- CZE
- SWE
- NLD
- LTU
- GBR
- SVN
- LUX
- POL
- SVK
- HUN
- ITA
- ROU
- FIN
- DNK
- MLT
- LVA
- GRC
- AUT
- HRV
- CHE
- NOR
- ISL
- FRA
- ESP
- ISR
- SMR
- VAT
- AND
- GIB
- AUS
- NZL
- PRT
- BEL
description: Country Code following ISO 3166 alpha-3
single-enrollment:
type: object
additionalProperties: false
properties:
countries:
type: array
description: List of countries supported for Visa single enrollment
uniqueItems: true
items:
type: string
enum:
- USA
- CAN
- IRL
- DEU
- CZE
- SWE
- NLD
- LTU
- GBR
- SVN
- LUX
- POL
- SVK
- HUN
- ITA
- ROU
- FIN
- DNK
- MLT
- LVA
- GRC
- AUT
- HRV
- CHE
- NOR
- ISL
- FRA
- ESP
- ISR
- SMR
- VAT
- AND
- GIB
- PRT
- BEL
description: Country Code following ISO 3166 alpha-3
blockedCardTypes:
type: array
description: Card types blocked for Visa single enrollment
uniqueItems: true
items:
type: string
enum:
- CONSUMER
blockedFundingCardTypes:
type: array
description: Funding card types blocked for Visa single enrollment
uniqueItems: true
items:
type: string
enum:
- DEBIT
required:
- countries
- blockedCardTypes
- blockedFundingCardTypes
bulk-enrollment:
type: object
additionalProperties: false
properties:
countries:
type: array
description: List of countries supported for Visa bulk enrollment
uniqueItems: true
items:
type: string
enum:
- USA
- CAN
- IRL
- DEU
- CZE
- SWE
- NLD
- GBR
- SVN
- LUX
- POL
- SVK
- HUN
- ITA
- ROU
- FIN
- MLT
- AUT
- FRA
- ESP
- NOR
- CHE
- AUS
- NZL
- PRT
- BEL
description: Country Code following ISO 3166 alpha-3
blockedCardTypes:
type: array
description: Card types blocked for Visa bulk enrollment
uniqueItems: true
items:
type: string
enum:
- CONSUMER
blockedFundingCardTypes:
type: array
description: Funding card types blocked for Visa bulk enrollment
uniqueItems: true
items:
type: string
enum:
- DEBIT
required:
- countries
- blockedCardTypes
- blockedFundingCardTypes
required:
- countries
- single-enrollment
- bulk-enrollment
MASTERCARD:
type: object
additionalProperties: false
properties:
countries:
type: array
description: List of contracted regional areas for Mastercard
uniqueItems: true
items:
type: string
enum:
- USA
- CAN
- GBR
- IRL
- SWE
- DEU
- NLD
- DNK
- ITA
- POL
- FIN
- BEL
- ESP
- FRA
- PRT
- AUT
- GRC
- MLT
- NOR
- CHE
- ISR
- AUS
- NZL
description: Country Code following ISO 3166 alpha-3
single-enrollment:
type: object
additionalProperties: false
properties:
countries:
type: array
description: List of countries supported for Mastercard single enrollment
uniqueItems: true
items:
type: string
enum:
- USA
- CAN
- GBR
- IRL
- SWE
- DEU
- NLD
- DNK
- ITA
- POL
- FIN
- BEL
- ESP
- FRA
- PRT
- AUT
- GRC
- MLT
- NOR
- CHE
- ISR
- AUS
- NZL
description: Country Code following ISO 3166 alpha-3
blockedCardTypes:
type: array
description: Card types blocked for Mastercard single enrollment
uniqueItems: true
items:
type: string
enum:
- CONSUMER
blockedFundingCardTypes:
type: array
description: Funding card types blocked for Mastercard single enrollment
uniqueItems: true
items:
type: string
enum:
- DEBIT
required:
- countries
- blockedCardTypes
- blockedFundingCardTypes
bulk-enrollment:
type: object
additionalProperties: false
properties:
countries:
type: array
description: List of countries supported for Mastercard bulk enrollment
uniqueItems: true
items:
type: string
enum:
- USA
- CAN
- GBR
- IRL
- SWE
- DEU
- NLD
- DNK
- ITA
- POL
- FIN
- BEL
- ESP
- FRA
- AUT
- NOR
- CHE
- ISR
- AUS
- NZL
description: Country Code following ISO 3166 alpha-3
blockedCardTypes:
type: array
description: Card types blocked for Mastercard bulk enrollment
uniqueItems: true
items:
type: string
enum:
- CONSUMER
blockedFundingCardTypes:
type: array
description: Funding card types blocked for Mastercard bulk enrollment
uniqueItems: true
items:
type: string
enum:
- DEBIT
required:
- countries
- blockedCardTypes
- blockedFundingCardTypes
required:
- countries
- single-enrollment
- bulk-enrollment
AMEX:
type: object
additionalProperties: false
properties:
countries:
type: array
description: List of contracted regional areas for American Express
uniqueItems: true
items:
type: string
enum:
- USA
- CAN
- GBR
- ITA
- SWE
- AUS
- NZL
description: Country Code following ISO 3166 alpha-3
single-enrollment:
type: object
additionalProperties: false
properties:
countries:
type: array
description: List of countries supported for AMEX single enrollment
uniqueItems: true
items:
type: string
enum:
- USA
- CAN
- GBR
- ITA
- SWE
description: Country Code following ISO 3166 alpha-3
blockedCardTypes:
type: array
description: Card types blocked for AMEX single enrollment
uniqueItems: true
items:
type: string
enum:
- CONSUMER
blockedFundingCardTypes:
type: array
description: Funding card types blocked for AMEX single enrollment
uniqueItems: true
items:
type: string
enum:
- DEBIT
required:
- countries
- blockedCardTypes
- blockedFundingCardTypes
bulk-enrollment:
type: object
additionalProperties: false
properties:
countries:
type: array
description: List of countries supported for AMEX bulk enrollment
uniqueItems: true
items:
type: string
enum:
- USA
- CAN
- GBR
- ITA
- SWE
- AUS
- NZL
description: Country Code following ISO 3166 alpha-3
blockedCardTypes:
type: array
description: Card types blocked for AMEX bulk enrollment
uniqueItems: true
items:
type: string
enum:
- CONSUMER
blockedFundingCardTypes:
type: array
description: Funding card types blocked for AMEX bulk enrollment
uniqueItems: true
items:
type: string
enum:
- DEBIT
required:
- countries
- blockedCardTypes
- blockedFundingCardTypes
required:
- countries
- single-enrollment
- bulk-enrollment
example:
VISA:
countries:
- USA
- CAN
single-enrollment:
countries:
- USA
blockedCardTypes:
- CONSUMER
blockedFundingCardTypes:
- DEBIT
bulk-enrollment:
countries:
- CAN
blockedCardTypes:
- CONSUMER
blockedFundingCardTypes:
- DEBIT
MASTERCARD:
countries:
- USA
single-enrollment:
countries:
- USA
blockedCardTypes:
- CONSUMER
blockedFundingCardTypes:
- DEBIT
bulk-enrollment:
countries:
- GBR
blockedCardTypes:
- CONSUMER
blockedFundingCardTypes:
- DEBIT
AMEX:
countries:
- ITA
single-enrollment:
countries:
- ITA
blockedCardTypes:
- CONSUMER
blockedFundingCardTypes:
- DEBIT
bulk-enrollment:
countries:
- SWE
blockedCardTypes:
- CONSUMER
blockedFundingCardTypes:
- DEBIT
enrollment-policy:
type: object
description: 'Enrollment policy for an account or subaccount. Two groups of fields:
**Unified-SDK rails** (`cardEnrollment`, `bankEnrollment`, `bulkEnrollment`) — which
enrollment options the unified SDK renders. Customer-writable per subaccount via
`PATCH /subaccounts/{subaccountId}`; account-level defaults are admin-managed. Rails
resolve live per field (subaccount value if set, else account) and reads are SPARSE:
only explicitly-configured rail fields are returned — an absent field means "not
configured here" and the SDK falls back to the host page''s client configuration, then
its card-only default.
**Admin fields** (`spinwheelEnabled`, `programBins`) — whether the Spinwheel enrollment
option is offered, and which card-program BINs identify the customer''s program.
Managed only on the internal enrollment-policy endpoints.
Fields are optional and nullable; absent fields leave the current value unchanged, explicit
`null` clears a field.
'
properties:
spinwheelEnabled:
type: boolean
nullable: true
description: 'Master gate for offering Spinwheel enrollment. Absent / `null` / `false` → disabled.
Resolution: the account-level value is the master switch. A subaccount''s stored value only
takes effect while the account''s is also `true` — subaccount GETs return this **effective**
value, not the stored one. Disabling at the account level is non-destructive: stored
subaccount values are unchanged, so re-enabling the account automatically restores
subaccounts whose stored value is `true`.
Setting `true` on a subaccount while the parent account''s gate is off is rejected with
`400` (no escalation past the account).
'
bulkEnrollmentEnabled:
type: boolean
n
# --- truncated at 32 KB (61 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/astrada/refs/heads/main/openapi/astrada-subaccounts-api-openapi.yml