openapi: 3.2.0
info:
  title: Virtual Accounts Pay I Ds API
  description: 'Simplify payin reconciliations by creating a dedicated _Virtual Account_ for each user on your platform.


    Enhance the payments experience on your platform by registering a user friendly identifier, i.e. a _PayID_, for each user''s _Virtual Account_. Your users should then be able to address payins using _PayIDs_ which are easier to remember and use than a BSB and account number.


    This swagger document lists APIs for _Virtual Account_ and _PayID_ creation and management.

    '
  contact:
    url: https://developer.hellozai.com/reference/overview
    email: support@hellozai.com
  version: 0.12-external
servers:
- description: Zai Prelive API
  url: https://sandbox.au-0000.api.assemblypay.com
- description: Zai Production API
  url: https://au-0000.api.assemblypay.com
tags:
- name: PayIDs
paths:
  /virtual_accounts/{id}/pay_ids:
    post:
      tags:
      - PayIDs
      summary: Register PayID
      description: Register a _PayID_ for a given _Virtual Account_.
      operationId: registerPayID
      parameters:
      - name: id
        in: path
        description: _Virtual Account_ ID.
        required: true
        style: simple
        explode: false
        schema:
          type: string
          format: uuid
        example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/pay_id_request'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pay_id'
              example:
                id: 46deb476-c1a6-41eb-8eb7-26a695bbe5bc
                pay_id: jsmith@mydomain.com
                type: EMAIL
                status: pending_activation
                created_at: '2020-04-27T20:28:22.378Z'
                updated_at: '2020-04-27T20:28:22.378Z'
                details:
                  pay_id_name: J Smith
                  owner_legal_name: Mr John Smith
                links:
                  self: /pay_ids/46deb476-c1a6-41eb-8eb7-26a695bbe5bc
                  virtual_accounts: /virtual_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_400_1'
              examples:
                invalid_email_address:
                  value:
                    errors:
                      pay_id:
                      - pay_id should be a valid email address
                invalid_payid_domain:
                  value:
                    errors:
                      pay_id:
                      - invalid domain/sub-domain
                  description: Provided domain is not registered with the marketplace.
        '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_va'
              examples:
                Virtual Accounts unavailable:
                  value:
                    errors:
                      virtual_accounts:
                      - Feature not available
                PayID unavailable:
                  value:
                    errors:
                      payid_per_user:
                      - Feature not available
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/virtual_account_not_found'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_409_1'
              examples:
                Invalid Virtual Account Status:
                  value:
                    errors: Virtual account must be active to register payid
                Invalid PayID Status:
                  value:
                    errors: Provided PayID is either pending activation or active already and associated with a virtual account
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_500'
  /pay_ids/{id}/status:
    patch:
      tags:
      - PayIDs
      summary: Update PayID Status
      description: Update the status of the _PayID_.
      operationId: updatePayIdStatus
      parameters:
      - name: id
        in: path
        description: Id of the _PayID_ resource.
        required: true
        style: simple
        explode: false
        schema:
          type: string
          format: uuid
        example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  example: deregistered
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deregister_pay_id'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_400_1'
              examples:
                Invalid Id:
                  value:
                    errors: 'Invalid format for url parameter: id.'
                Invalid Status:
                  value:
                    errors:
                      status:
                      - must be a valid status value
        '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_va'
              examples:
                Virtual Accounts unavailable:
                  value:
                    errors:
                      virtual_accounts:
                      - Feature not available
                PayID unavailable:
                  value:
                    errors:
                      payid_per_user:
                      - Feature not available
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: string
                    example: PayID does not exist.
        '409':
          description: Conflict
          content:
            application/json:
              examples:
                In progress:
                  value:
                    errors: An update for this PayID is already in progress. Please try again later.
                Status not active:
                  value:
                    errors: PayID must be active to deregister.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_500'
  /pay_ids/{id}:
    get:
      tags:
      - PayIDs
      summary: Retrieve a PayID
      description: Retrieve the details of a specific _PayID_ using the unique id parameter `id`. Only one _PayID_ record is returned.
      operationId: getPayID
      parameters:
      - name: id
        in: path
        description: Id of the _PayID_ resource.
        required: true
        style: simple
        explode: false
        schema:
          type: string
          format: uuid
        example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pay_id'
        '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_pay_id'
              examples:
                PayID unavailable:
                  value:
                    errors:
                      payid_per_user:
                      - Feature not available
                Virtual Accounts unavailable:
                  value:
                    errors:
                      virtual_accounts:
                      - Feature not available
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_404_pay_id'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_500'
components:
  schemas:
    inline_response_404_pay_id:
      properties:
        errors:
          type: string
          example: PayID does not exist.
    inline_response_500:
      properties:
        errors:
          type: string
          example: An error occurred processing your request. Please try again.
    deregister_pay_id:
      type: object
      properties:
        id:
          description: Identifies the _PayID_.
          type: string
          format: uuid
          example: 46deb476-c1a6-41eb-8eb7-26a695bbe5bc
        message:
          type: string
          example: PayID deregistration has been accepted for processing
        links:
          type: object
          properties:
            self:
              type: string
              example: /pay_ids/46deb476-c1a6-41eb-8eb7-26a695bbe5bc
    virtual_account_not_found:
      properties:
        errors:
          type: string
          example: Virtual Account does not exist.
    inline_response_403_pay_id:
      properties:
        errors:
          type: object
          properties:
            payid_per_user:
              type: array
              items:
                type: string
                example: Feature not available
    pay_id_request:
      required:
      - pay_id
      - type
      - details
      type: object
      properties:
        pay_id:
          type: string
          description: The PayID that is being registered.
          format: email
          example: jsmith@mydomain.com
          maxLength: 256
        type:
          type: string
          description: The type of PayID 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 PayID.
              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
    inline_response_400_1:
      properties:
        errors:
          type: object
    inline_response_403_va:
      properties:
        errors:
          type: object
          properties:
            virtual_accounts:
              type: array
              items:
                type: string
                example: Feature not available
    inline_response_409_1:
      properties:
        errors:
          type: object
          properties:
            pay_id:
              type: string
              example: Provided PayID is either pending activation or active already and associated with a virtual account
    inline_response_401:
      properties:
        errors:
          type: string
          example: Invalid or missing authorisation token
    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
          - activation_failed
          - pending_activation
          - 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
    inline_response_400:
      properties:
        errors:
          type: string
          example: 'Invalid format for url parameter: id.'
x-explorer-enabled: false
x-samples-languages:
- curl
- c#
- ruby
- php
- javascript
- csharp
- go