openapi: 3.0.0
info:
  title: Virtual Accounts
  description: >-
    Assembly (formely PromisePay) is a powerful payments engine custom-built for
    platforms and marketplaces.
  contact:
    url: 'http://docs.assemblypayments.com/'
    email: support@assemblypayments.com
  version: 0.5-external
servers:
  - url: 'https://sandbox.au-0000.api.assemblypay.com'
    description: Sandbox (Pre-live) server and API
  - url : 'https://au-0000.api.assemblypay.com'
    description: Production server and API
  # Added by API Auto Mocking Plugin
  - url: https://virtserver.swaggerhub.com/AssemblyPlatforms/VirtualAccounts/0.5-external
    description: SwaggerHub API Auto Mocking
x-explorer-enabled: false
x-samples-languages:
  - curl
  - ruby
  - php
  - javascript
  - csharp
  - go
paths:
  /wallet_accounts/{id}/virtual_accounts:
    post:
      tags:
      - "Virtual Accounts"
      summary: "Create Virtual Account"
      description: "Starting October 18 2021, this API will accept the Virtual account creation request and process it asynchronously thereby returning HTTP 202 response code only. The virtual account will be in `pending_activation` status initially. Once the virtual account is created successfully, the VA status will transition from `pending_activation` -> `active`. If due to some reason, the virtual account creation fails, the VA status will transition from `pending_activation` -> `activation_failed`. You will be updated about the VA status change via a webhook notification, however,
        in order to fetch additional details for a virtual account, you should be able to
        query the virtual account request using the id returned by calling the **Show Virtual Account** API"
      operationId: "createVirtualAccount"
      parameters:
      - name: "id"
        in: "path"
        description: "Wallet Account ID"
        required: true
        style: "simple"
        explode: false
        schema:
          type: "string"
          format: "uuid"
          default: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
        example: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
      responses:
        "201":
          description: "Created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/virtual_account"
              examples:
                response:
                  value:
                    id: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
                    routing_number: 123456
                    account_number: 100000017
                    currency: "AUD"
                    wallet_account_id: "ae07556e-22ef-11eb-adc1-0242ac120002"
                    status: "active"
                    created_at: "2020-04-27T20:28:22.378Z"
                    updated_at: "2020-04-27T20:28:22.378Z"
        "202":
          description: "Accepted"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/virtual_account"
              examples:
                response:
                  value:
                    id: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
                    routing_number: 123456
                    account_number: 100000017
                    currency: "AUD"
                    wallet_account_id: "ae07556e-22ef-11eb-adc1-0242ac120002"
                    status: "pending_activation"
                    created_at: "2020-04-27T20:28:22.378Z"
                    updated_at: "2020-04-27T20:28:22.378Z"
        "400":
          description: "Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_400"
        "401":
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_401"
        "403":
          description: "Forbidden"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_403"
        "404":
          description: "Not Found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/wallet_account_not_found"
        "409":
          description: "Conflict"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_409"
        "500":
          description: "Internal Server Error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_500"
        "515":
          description: "Service Temporarily Unavailable"
          headers:
            Retry-After:
              schema:
                type: "integer"
              description: "Time in seconds to wait before retrying."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_515"
    get:
      tags:
      - "Virtual Accounts"
      summary: "List Virtual Accounts for a given Wallet Account"
      description: "List **Virtual Accounts** for a given Wallet Account"
      operationId: "listVirtualAccountByWalletAccount"
      parameters:
      - name: "id"
        in: "path"
        description: "Wallet Account ID"
        required: true
        style: "simple"
        explode: false
        schema:
          type: "string"
          format: "uuid"
          default: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
        example: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/virtual_accounts_list"
              examples:
                response:
                  value:
                    virtual_accounts:
                    - id: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
                      routing_number: 123456
                      account_number: 100000017
                      wallet_account_id: "ae07556e-22ef-11eb-adc1-0242ac120002"
                      currency: "AUD"
                      status: "active"
                      created_at: "2020-04-27T20:28:22.378Z"
                      updated_at: "2020-04-27T20:28:22.378Z"
                    - id: "aaaaaaaa-cccc-dddd-eeee-ffffffffffff"
                      routing_number: 123456
                      account_number: 100000025
                      currency: "AUD"
                      wallet_account_id: "ae07556e-22ef-11eb-adc1-0242ac120002"
                      status: "pending_activation"
                      created_at: "2020-04-27T20:28:22.378Z"
                      updated_at: "2020-04-27T20:28:22.378Z"
                    meta:
                      total: 2
        "400":
          description: "Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_400"
        "401":
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_401"
        "403":
          description: "Forbidden"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_403"
        "404":
          description: "Not Found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/wallet_account_not_found"
        "500":
          description: "Internal Server Error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_500"
  /virtual_accounts/{id}:
    get:
      tags:
      - "Virtual Accounts"
      summary: "Show Virtual Account"
      description: "Show details of a specific **Virtual Account** using a given `:id`."
      operationId: "showVirtualAccount"
      parameters:
      - name: "id"
        in: "path"
        description: "Virtual Account ID"
        required: true
        style: "simple"
        explode: false
        schema:
          type: "string"
          format: "uuid"
          default: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
        example: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/virtual_account"
              examples:
                response:
                  value:
                    id: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
                    routing_number: 123456
                    account_number: 100000017
                    currency: "AUD"
                    wallet_account_id: "ae07556e-22ef-11eb-adc1-0242ac120002"
                    status: "active"
                    created_at: "2020-04-27T20:28:22.378Z"
                    updated_at: "2020-04-27T20:28:22.378Z"
        "400":
          description: "Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_400"
        "401":
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_401"
        "403":
          description: "Forbidden"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_403"
        "404":
          description: "Not Found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/virtual_account_not_found"
        "500":
          description: "Internal Server Error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_500"
  '/transactions/{id}/supplementary_data':
    get:
      tags:
        - Transaction supplementary data
      summary: Show Transaction Supplementary Data
      operationId: showTransactionSupplementaryData
      description: |
        Show supplementary data of a specific **Transaction** using a given `:id`.
      parameters:
        - in: path
          name: id
          description: Transaction ID
          required: true
          explode: false
          style: simple
          schema:
            type: string
            format: uuid
          example: '49f1cb10-0202-0138-225b-028e897a70a5'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupplementaryData'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: string
                    example: 'Invalid format for url param: id'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: string
                    example: 'Invalid or missing authorisation token' 
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: string
                    example: Transaction data not found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: string
                    example: >-
                      An error occurred processing your request. Please try again.
security:
  - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    virtual_account:
      type: "object"
      properties:
        id:
          type: "string"
          format: "uuid"
          example: "46deb476-c1a6-41eb-8eb7-26a695bbe5bc"
        routing_number:
          type: "string"
          format: "numeric"
          minLength: 6
          maxLength: 6
          example: 123456
        account_number:
          type: "string"
          format: "numeric"
          minLength: 9
          maxLength: 9
          example: 100000017
        currency:
          type: "string"
          format: "alphabets"
          example: "AUD"
        wallet_account_id:
          type: "string"
          format: "uuid"
          example: "46deb476-c1a6-41eb-8eb7-26a695bbe5bc"
        status:
          type: "string"
          enum:
          - "active"
          - "pending_activation"
          - "activation_failed"
          - "disabled"
          - "closed"
          example: "active"
        created_at:
          type: "string"
          format: "date-time"
          example: "2020-04-27T20:28:22.378Z"
        updated_at:
          type: "string"
          format: "date-time"
          example: "2020-04-27T20:28:22.378Z"
    virtual_accounts_list:
      type: "object"
      properties:
        virtual_accounts:
          type: "array"
          items:
            $ref: "#/components/schemas/virtual_account"
    pay_id_request:
      required:
      - "pay_id"
      - "type"
      - "details"
      type: "object"
      properties:
        pay_id:
          type: "string"
          description: "The Pay ID that is being registered."
          format: "email"
          example: "jsmith@mydomain.com"
          maxLength: 256
        type:
          type: "string"
          description: "Type of the Pay ID being registered."
          enum:
          - "EMAIL"
        details:
          type: "object"
          properties:
            pay_id_name:
              type: "string"
              description: "Name that can be used to identify the entity registering\
                \ the Pay ID."
              example: "J Smith"
              minLength: 1
              maxLength: 140
            owner_legal_name:
              type: "string"
              description: "The full legal account name."
              example: "Mr John Smith"
              minLength: 1
              maxLength: 140
    pay_id:
      type: "object"
      properties:
        id:
          type: "string"
          format: "uuid"
          example: "46deb476-c1a6-41eb-8eb7-26a695bbe5bc"
        pay_id:
          type: "string"
          format: "email"
          example: "jsmith@mydomain.com"
        type:
          type: "string"
          enum:
          - "EMAIL"
          example: "EMAIL"
        status:
          type: "string"
          enum:
          - "active"
          - "deregistered"
          example: "active"
        created_at:
          type: "string"
          format: "date-time"
          example: "2020-04-27T20:28:22.378Z"
        updated_at:
          type: "string"
          format: "date-time"
          example: "2020-04-27T20:28:22.378Z"
        details:
          type: "object"
          properties:
            pay_id_name:
              type: "string"
              example: "J Smith"
            owner_legal_name:
              type: "string"
              example: "Mr John Smith"
        links:
          type: "object"
          properties:
            self:
              type: "string"
              example: "/pay_ids/46deb476-c1a6-41eb-8eb7-26a695bbe5bc"
            virtual_accounts:
              type: "string"
              example: "/virtual_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc"
    virtual_account_with_pay_id:
      type: "object"
      properties:
        id:
          type: "string"
          format: "uuid"
          example: "46deb476-c1a6-41eb-8eb7-26a695bbe5bc"
        routing_number:
          type: "string"
          format: "numeric"
          minLength: 6
          maxLength: 6
          example: 123456
        account_number:
          type: "string"
          format: "numeric"
          minLength: 9
          maxLength: 9
          example: 100000017
        currency:
          type: "string"
          format: "alphabets"
          example: "AUD"
        wallet_account_id:
          type: "string"
          format: "uuid"
          example: "46deb476-c1a6-41eb-8eb7-26a695bbe5bc"
        status:
          type: "string"
          enum:
          - "active"
          - "pending_activation"
          - "activation_failed"
          - "disabled"
          - "closed"
          example: "active"
        created_at:
          type: "string"
          format: "date-time"
          example: "2020-04-27T20:28:22.378Z"
        updated_at:
          type: "string"
          format: "date-time"
          example: "2020-04-27T20:28:22.378Z"
        pay_id:
          type: "object"
          properties:
            id:
              type: "string"
              format: "uuid"
              example: "46deb476-c1a6-41eb-8eb7-26a695bbe5bc"
            pay_id:
              type: "string"
              format: "email"
              example: "jsmith@mydomain.com"
            type:
              type: "string"
              enum:
              - "EMAIL"
              example: "EMAIL"
            status:
              type: "string"
              enum:
              - "active"
              - "deregistered"
              example: "active"
            created_at:
              type: "string"
              format: "date-time"
              example: "2020-04-27T20:28:22.378Z"
            updated_at:
              type: "string"
              format: "date-time"
              example: "2020-04-27T20:28:22.378Z"
            details:
              type: "object"
              properties:
                pay_id_name:
                  type: "string"
                  example: "J Smith"
                owner_legal_name:
                  type: "string"
                  example: "Mr John Smith"
      required:
      - "id"
      - "routing_number"
      - "account_number"
      - "currency"
      - "wallet_account_id"
      - "active"
      - "created_at"
      - "updated_at"
    inline_response_400:
      properties:
        errors:
          type: "string"
          example: "invalid format for url param: id"
    inline_response_400_1:
      properties:
        errors:
          type: "string"
          example: "pay_id should be a valid email address."
    inline_response_401:
      properties:
        errors:
          type: "string"
          example: "Invalid or missing authorisation token"
    inline_response_403:
      properties:
        errors:
          type: "object"
          properties:
            virtual_accounts:
              type: "array"
              items:
                type: "string"
                example: "Feature not available"
    wallet_account_not_found:
      properties:
        errors:
          type: "string"
          example: "Wallet Account does not exist."
    inline_response_409:
      properties:
        wallet_account_id:
          type: "string"
          example: "Provided wallet_account_id is already associated with an active\
            \ or pending activation virtual account"
    inline_response_409_1:
      properties:
        errors:
          type: "object"
          properties:
            pay_id:
              type: "string"
              example: "Provided pay_id is already active and associated with a virtual\
                \ account."
    inline_response_500:
      properties:
        errors:
          type: "string"
          example: "An error occurred processing your request. Please try again."
    inline_response_515:
      properties:
        errors:
          type: "string"
          example: "Unable to process your request. Please try again later."
    virtual_account_not_found:
      properties:
        errors:
          type: "string"
          example: "Virtual Account does not exist."
    SupplementaryData:
      type: object
      required:
        - id
        - debtor_name
        - debtor_bsb
        - debtor_account
        - creditor_account
        - creditor_name
        - remittance_information
        - type
        - type_method
      properties:
        id:
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
        debtor_name:
          type: string
          example: ASSEMBLY TEST
        debtor_bsb:
          type: string
          example: 098765
        debtor_account:
          type: string
          example: 09876512345678
        creditor_account:
          type: string
          example: 3389422762057
        creditor_name:
          type: string
          example: ACME Corp Pty Ltd
        remittance_information:
          type: string
          example: 100014014111111
        type:
          type: string
          example: deposit
        type_method:
          type: string
          example: npp_payin
        npp_details:
          description: |
            Details for the NPP payment.
            `npp_details` will only be present when `type_method` is `npp_payin`
          type: object
          required:
            - pay_id
            - pay_id_type
            - clearing_system_transaction_id
            - end_to_end_id
            - npp_payin_internal_id
            - cdtr_ref_inf
            - ultm_cdtr_id
            - ultmt_cdtr_schme_nm
            - ctgy_purp
            - debtor_legal_name
          properties:
            pay_id:
              type: string
              example: npp@assemblypayments.com
            pay_id_type:
              type: string
              example: "EMAIL"
            clearing_system_transaction_id:
              type: string
              example: CTBAAUSNXXXN20191216050126353211111
            end_to_end_id:
              type: string
            cdtr_ref_inf:
              type: string
            ultm_cdtr_id:
              type: string
            ultmt_cdtr_schme_nm:
              type: string
            ultm_cdtr_nm:
              type: string
              minLength: 0
              maxLength: 140
            ctgy_purp:
              type: string
            debtor_legal_name:
              type: string
        links:
          $ref: '#/components/schemas/Links'
    Links:
      type: object
      required:
        - links
        - self
        - users
        - wallet_accounts
        - virtual_accounts
        - marketplaces
        - transactions
      properties:
        self:
          type: string
          example: '/transactions/49f1cb10-0202-0138-225b-028e897a70a5/supplementary_data/'
        users:
          type: string
          example: '/transactions/49f1cb10-0202-0138-225b-028e897a70a5/users'
        wallet_accounts:
          type: string
          example: '/transactions/49f1cb10-0202-0138-225b-028e897a70a5/wallet_accounts'
        marketplaces:
          type: string
          example: '/transactions/49f1cb10-0202-0138-225b-028e897a70a5/marketplaces'
        transactions:
          type: string
          example: '/transactions/49f1cb10-0202-0138-225b-028e897a70a5/'