openapi: 3.0.0
info:
  description: |
    This swagger lists all APIs to provide additional details about a payment.
    * Transaction Supplementary Data API - This API provides additional details for successfully reconciled NPP and DE payments.
    * Failed NPP Payment Details - This API provides details for failed  NPP PayTo payments.
  version: 0.3-external
  title: Supplementary Data APIs
  contact:
    email: support@assemblypayments.com
    url: 'http://docs.assemblypayments.com/'
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
  - url: "https://virtserver.swaggerhub.com/AssemblyPlatforms/SupplementaryData/0.3-external"
    description: SwaggerHub API Auto Mocking
paths:
  '/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`.
      security:
        - bearerAuth: []
      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.
  '/payment_details/failed/{instructionId}':
    get:
      tags:
        - Failed NPP Payment Details
      summary: Failed NPP Payment Details
      description:
        Show details of a specific failed **PayTo Payment** using a given :instructionId. <br />
        This API would list pay-ins which failed to be reconciled on a user’s wallet along with failure details for it.
      operationId: getPayInsByInstructionId
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: instructionId
          description: instruction ID
          required: true
          explode: false
          style: simple
          schema:
            type: string
          example: '123567890'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paymentData'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: string
                    example: 'Missing url param: instructionId'
        '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: Payment details 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.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    supplementaryData:
      allOf:
        - $ref: '#/components/schemas/base'
        - type: object
          required:
            - npp_details
            - links
          properties:
            npp_details:
              type: object
              $ref: '#/components/schemas/nppDetails'
            links:
              type: object
              $ref: '#/components/schemas/links'
    paymentData:
      allOf:
        - $ref: '#/components/schemas/base'
        - type: object
          properties:
            error_message:
              type: string
              description: Explanation why payment failed! Only available for PayTo Payments
              enum:
                - Payment reconciliation failed on the user's wallet as the agreement associated with it is not active
                - Payment reconciliation failed on the user's wallet as the payment initiation request associated is in invalid status
                - Payment reconciliation failed on the user's wallet as the payment initiation request associated does not exist
                - Payment reconciliation failed on the user's wallet as the payment initiation request provided does not match with the payment initiation request associated with the agreement
                - Payment reconciliation failed on the user's wallet as PayTo feature is disabled for your platform. Please contact Zai support.
                - Payment reconciliation failed on the user's wallet due to some technical error. Please contact Zai support.
            npp_details:
              type: object
              $ref: '#/components/schemas/nppDetails'
            links:
              type: object
              $ref: '#/components/schemas/linksNpp'
    base:
      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
    links:
      type: object
      required:
        - 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/'
        agreements:
          type: string
          description: Only available for PayTo Payments!
          example: '/payto/agreements/46deb476-c1a6-41eb-8eb7-26a695bbe5bc'
    linksNpp:
      type: object
      required:
        - self
        - agreements
      properties:
        self:
          type: string
          example: '/payment_details/failed/123567890'
        agreements:
          type: string
          example: '/payto/agreements/46deb476-c1a6-41eb-8eb7-26a695bbe5bc'
    nppDetails:
      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
        instruction_id:
          type: "string"
          maxLength: 35
          minLength: 1
          description: Unique identifier for the payment request generated as per NPPA guidelines. Only available for PayTo Payments
          example: "BANKNTSTXXXI20180501000000000000010"
        agreement_id:
          type: "string"
          description: Unique agreement identifier generated by NPPA. Only available for PayTo Payments
          example: "ef0fcd9799431ef783204966f010603c"
        agreement_uuid:
          type: string
          description: Unique agreement identifier generated by Zai. Only available for PayTo Payments
          format: uuid
          example: 46deb476-c1a6-41eb-8eb7-26a695bbe5bc
x-explorer-enabled: false
x-samples-languages:
  - curl
  - c#
  - ruby
  - php
  - javascript
  - csharp
  - go