Astrada subaccounts API

openapi: 3.2.0
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:
    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==
    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
  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:
    create-subaccount-configurations:
      type: object
      additionalProperties: false
      description: 'Subaccount network and regional configurations which determine the available networks and geographies during card enrollment.


        The `countries` property for each network accepts either:

        - An array of ISO 3166 alpha-3 country codes (e.g. `["USA", "CAN"]`)

        - The string `"*"` to inherit all countries from the parent account''s capabilities for that network


        When `"*"` is used, the subaccount automatically reflects the parent account''s current country list. If the parent account''s capabilities change, subaccounts using `"*"` will inherit the updated countries. API responses always return the resolved country list, never the `"*"` literal.


        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.

        '
      properties:
        VISA:
          type: object
          additionalProperties: false
          properties:
            countries:
              oneOf:
              - 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
              - type: string
                enum:
                - '*'
                description: 'Wildcard value that inherits all countries from the parent account''s VISA capabilities.

                  '
            single-enrollment:
              type: object
              additionalProperties: false
              properties:
                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
            bulk-enrollment:
              type: object
              additionalProperties: false
              properties:
                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
        MASTERCARD:
          type: object
          additionalProperties: false
          properties:
            countries:
              oneOf:
              - 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
              - type: string
                enum:
                - '*'
                description: 'Wildcard value that inherits all countries from the parent account''s MASTERCARD capabilities.

                  '
            single-enrollment:
              type: object
              additionalProperties: false
              properties:
                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
            bulk-enrollment:
              type: object
              additionalProperties: false
              properties:
                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
        AMEX:
          type: object
          additionalProperties: false
          properties:
            countries:
              oneOf:
              - 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
              - type: string
                enum:
                - '*'
                description: 'Wildcard value that inherits all countries from the parent account''s AMEX capabilities.

                  '
            single-enrollment:
              type: object
              additionalProperties: false
              properties:
                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
            bulk-enrollment:
              type: object
              additionalProperties: false
              properties:
                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
      example:
        VISA:
          countries:
          - USA
          - CAN
          single-enrollment:
            blockedCardTypes:
            - CONSUMER
            blockedFundingCardTypes:
            - DEBIT
          bulk-enrollment:
            blockedCardTypes:
            - CONSUMER
            blockedFundingCardTypes:
            - DEBIT
        MASTERCARD:
          countries:
          - USA
          single-enrollment:
            blockedCardTypes:
            - CONSUMER
            blockedFundingCardTypes:
            - DEBIT
          bulk-enrollment:
            blockedCardTypes:
            - CONSUMER
            blockedFundingCardTypes:
            - DEBIT
        AMEX:
          countries:
          - ITA
          single-enrollment:
            blockedCardTypes:
            - CONSUMER
            blockedFundingCardTypes:
            - DEBIT
          bulk-enrollment:
            blockedCardTypes:
            - CONSUMER
            blockedFundingCardTypes:
            - DEBIT
    link:
      type: object
      properties:
        href:
          type: string
        templated:
          type: boolean
        type:
          type: string
        deprecation:
          type: string
        name:
          type: string
        profile:
          type: string
        title:
          type: string
        hreflang:
          type: string
      required:
      - href
    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
          - 'null'
          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
          - 'null'
          deprecated: true
          description: '**Deprecated:** superseded by the `bulkEnrollment` tri-state rail (the SDK maps

            `true` to `suggested`, `false` to `off`, and prefers the tri-state when present).


            Whether the unified enrollment SDK offers bulk-enrollment steering (BIN eligibility

            check + bulk feed wizard) for this account/subaccount. `false` = the SDK skips the

            eligibility check entirely and opens the card form directly (American Express cards

            pivot to the bank-linking flow). Absent / `null` = not configured — the SDK falls

            back to the host page''s client configuration, then its card-only default (bulk off).


            Resolution: plain override-fallback — a subaccount value overrides the account value

            when set (no master gate; unlike `spinwheelEnabled`). An explicit `bulkEnrollment`

            flag in the SDK''s `open()` config wins over this policy.

            '
        cardEnrollment:
          type:
          - boolean
          - 'null'
          description: 'Unified-SDK rail: offer manual card enrollment (PAN entry + 3DS verification).

            Resolution: live per-field override-fallback (subaccount value if set, else account).

            '
        bankEnrollment:
          type:
          - string
          - 'null'
          enum:
          - 'off'
          - amex-only
          - 'on'
          description: 'Unified-SDK rail: offer bank linking. `on` = first-class (chooser tile, any-order

            linking); `amex-only` = reachable only via the American Express pivot from card

            entry; `off` = disabled. Resolution: live per-field override-fallback.

            '
        bulkEnrollment:
          type:
          - string
          - 'null'
          enum:
          - 'off'
          - suggested
          - forced
          description: 'Unified-SDK rail: offer network bulk-feed enrollment for bulk-capable programs.

            `suggested` = bulk wizard with a link-just-this-card escape; `forced` = the wizard

            is the only path for bulk-capable cards; `off` = no bulk routing (direct card

            form). Supersedes the deprecated `bulkEnrollmentEnabled` boolean; when both are

            set, the SDK prefers this field. Resolution: live per-field override-fallback.

            '
        programBins:
          type:
          - array
          - 'null'
          items:
            type: string
            pattern: ^\d{6,8}$
          description: 'The customer''s card-program BIN prefixes (tier-2 manual registry), used to match cards to

            the program during enrollment-option resolution. 6–8 digit numeric strings — both legacy

            6-digit and ISO 8-digit prefixes are accepted. Managed via customer onboarding; returned

            as stored on the subaccount (not resolved against the account).

            '
    subaccount:
      type: object
      properties:
        _links:
          type: object
          required:
          - self
          properties:
            self:
              $ref: '#/components/schemas/link'
        accountId:
          type: string
          format: uuid
          description: The unique identifier of the account related to this entity.
        id:
          type: string
          format: uuid
          description: The unique identifier of this subaccount entity.
        name:
          type: string
          description: The name of this subaccount entity.
        createdAt:
          type: string
          format: date-time
          description: Date and time when this resource was created, in UTC, following ISO 8601 format.
        updatedA

# --- 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