AMCS Group Disbursements API

openapi: 3.2.0
info:
  title: Core AccessGroup Disbursements API
  version: core
servers:
- url: https://rstapi-sbx-svc-core.amcsplatform.com/erp/api/integrator/erp
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: Disbursements
paths:
  /disbursement/AddSupplier:
    post:
      tags:
      - Disbursements
      summary: Add Supplier
      description: This endpoint is used to add supplier of disbursements.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AMCSPayDisbursementAddSupplierRequest'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AMCSPayDisbursementAddSupplierResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AMCSPayErrorResponse'
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AMCSPayErrorResponse'
  /disbursement/GetSupplier:
    post:
      tags:
      - Disbursements
      summary: Get Supplier
      description: This endpoint is used to get supplier of disbursements.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AMCSPayDisbursementGetSupplierRequest'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AMCSPayDisbursementGetSupplierResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AMCSPayErrorResponse'
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AMCSPayErrorResponse'
  /disbursement/AddDisbursement:
    post:
      tags:
      - Disbursements
      summary: Add Disbursement
      description: This endpoint is used add disbursement to an account using ACH, CARD, or CHEQUE.
      security: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AMCSPayDisbursementAddDisbursementRequest'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AMCSPayDisbursementAddDisbursementResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AMCSPayErrorResponse'
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AMCSPayErrorResponse'
  /pay/AptPay/GetIdentity:
    post:
      tags:
      - Disbursements
      summary: Get Identity
      description: This endpoint is used to get identity of a supplier.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AMCSAptPayGetIdentityRequest'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AMCSAptPayGetIdentityResponse'
        '401':
          description: Unauthorized
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AMCSPayErrorContentResponse'
  /pay/AptPay/GetTransactionStatus:
    post:
      tags:
      - Disbursements
      summary: Get Transaction Status
      description: This endpoint is used to get transaction status of an disbursements.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AMCSAptPayGetTranStatusRequest'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AMCSAptPayGetTranStatusResponse'
        '401':
          description: Unauthorized
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AMCSPayErrorContentResponse'
  /pay/AptPay/CheckAccount:
    post:
      tags:
      - Disbursements
      summary: Check Account
      description: This endpoint is used to check if a card is eligible to receive funds.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AMCSPayCheckAccountRequest'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AMCSPayCheckAccountResponse'
        '401':
          description: Unauthorized
components:
  schemas:
    AMCSAptPayGetTranStatusBasicDataResponse:
      type: object
      properties:
        status:
          type: string
          description: Contains the status of the response
          example: SETTLED
        message:
          type: string
          description: Contains the detailed description of the response
          example: ''
    AMCSPayDisbursementAddSupplierRequest:
      type: object
      required:
      - provider
      - data
      properties:
        provider:
          type: string
          description: 'Provider to use to add supplier for disbursement.


            - AptPay'
          example: AptPay
        data:
          type: object
          description: Holds the request object depends on the provider.
          $ref: '#/components/schemas/AMCSAptPayAddIdentityRequest'
    AMCSAptPayGetTranStatusRequest:
      type: object
      required:
      - transactionId
      properties:
        transactionId:
          type: string
          description: The transaction id of the request
          example: mi5gkghovd-0119-qgdgtosuxd7ehxbe5h2oiwae
    AMCSPayCheckAccountResponseData:
      type: object
      properties:
        receiving:
          type: boolean
          example: true
          description: This indicates if the card is eligible to receive funds. This will return a value of either true or false.
        sending:
          type: boolean
          example: false
          description: This indicates if the card is eligible to send funds. This will return a value of either true or false.
        network:
          type: string
          example: MASTERCARD
          description: 'The network the transaction takes place over (example: MasterCard)'
        funds_availability:
          type: string
          example: IMMEDIATE
          description: The duration of time required to send funds to the Payee's account
        type:
          type: string
          example: DEBIT
          description: Type of card used for disbursement (ie., debit, credit, etc.)
        country:
          type: string
          example: CAN
          description: The country in which the card was issued
        currency:
          type: string
          example: CAD
          description: The currency available on the card.
    AMCSPayErrorContentResponse:
      type:
      - string
      - 'null'
    AMCSAptPayAddDisbursementDataResponse:
      type: object
      properties:
        id:
          type: string
          example: 6xxpsbbxjj-0119-hclhajwncvxejiefxgjatcen
          description: This is the transaction ID of the transaction
        status:
          type: string
          example: ACCEPTED
          description: This provides a message that describes the status of the transaction
        referenceId:
          type: string
          example: '23232131554'
          description: Reference transaction ID
    AMCSPayDisbursementGetSupplierResponse:
      type: object
      properties:
        result:
          type: object
          description: Holds the response object depends on the provider.
          $ref: '#/components/schemas/AMCSAptPayDisbursementGetSupplierDataResponse'
    AMCSAptPayAddDisbursementRequest:
      type: object
      required:
      - amount
      - currency
      - transactionType
      - referenceId
      properties:
        amount:
          type: number
          example: 12.01
          description: Provide the amount to be disbursed
        currency:
          type: string
          example: USD
          description: 'The currency being used for the transaction.

            This is expressed as a three-letter currency code (ie., CAD for Canadian dollars, USD for United States dollars, etc.).'
        transactionType:
          type: string
          example: CARD
          description: Provides a descriptor that expresses what kind of payment type is being processed. (ACH, CARD, or CHEQUE)
        program:
          type: string
          enum:
          - B2B
          - B2C
          - G2C
          - PayrollAndPension
          - RapidMerchantSettlement
          example: B2B
          description: Program ID. This is a code to denote the use case for product, ie., why are you using AptPay? The use case will determine what additional information will be needed in order to process the transaction.
        disbursementNumber:
          type: string
          example: '5454545454545454'
          description: 'Information inputted should be a Card or Personal Account Number (PAN) and must be 15-19 digits in length.<br/><span style=''color: rgb(212, 31, 28)''>This is required if: This is a push to card disbursement or if instrumentId is not defined.</span>'
        chequeNumber:
          type: integer
          example: 12345678
          description: 'The cheque number, <span style=''color: rgb(212, 31, 28)''>this is required for Transaction Type CHEQUE.</span>'
        bankNumber:
          type: string
          example: '123'
          description: 'Provide the bank number, this is a 3-digit number.<br/><span style=''color: rgb(212, 31, 28)''>This is required for EFT transfers.</span>'
        branchTransitNumber:
          type: string
          example: '123456789'
          description: 'ABA routing number

            ACH transfers: 9-digit number<br/><span style=''color: rgb(212, 31, 28)''>This is required for:- ACH transfers.</span>'
        accountNumber:
          type: string
          example: '123456789'
          description: 'Account number

            ACH transfers: 9 or 10 digit number<br/><span style=''color: rgb(212, 31, 28)''>This is required for:- ACH transfers</span>'
        instrumentId:
          type: string
          example: '12345'
          description: 'Provide the instrument ID. This is the ISIN and/or Common Code of the security that is the subject of the associated instruction.<br/><span style=''color: rgb(212, 31, 28)''>This is required if transactionNumber is not defined.</span>'
        expirationDate:
          type: string
          example: 2026-11
          description: 'Provide card expiration date. (Format: YYYY-MM)'
        identityId:
          type: string
          example: '762780560211'
          description: 'Optional for transaction type CHEQUE if First Name and Last Name is provided for Individual Identities or BusinessName for Business Entities.<br/><span style=''color: rgb(212, 31, 28)''>This is required for other transaction types. Identity Id must be greater than 0.</span>'
        referenceId:
          type: string
          example: AMCSPAYREF-a4121922-e796-4de0-9058-b0fb00e3a46e
          description: Reference transaction ID
        firstName:
          type: string
          example: Jane
          description: 'Provide the first name for the individual (max 50 characters).<br/><span style=''color: rgb(212, 31, 28)''>This is required for EFT/CHEQUE if identityId is not specified.<br/>This is a required field for individual identities.</span>'
        lastName:
          type: string
          example: Doe
          description: 'Provide the last name for the individual (max 50 characters).<br/><span style=''color: rgb(212, 31, 28)''>This is required for EFT/CHEQUE if identityId is not specified.<br/>This is a required field for individual identities.</span>'
        businessName:
          type: string
          example: JD Inc.
          description: 'Provide the business entity name.<br/><span style=''color: rgb(212, 31, 28)''>This is required for EFT/CHEQUE if identityId is not specified.<br/>This is required for business entities.</span>'
        supplierId:
          type: integer
          example: 123
          description: The id of the supplier that you are making the invoice payment for.
        supplierBills:
          type: string
          example: '[{"financialDocumentId":2496,"companyOutletId":1,"customerId":135,"ticketNumber":"CI1027","transactionDate":"2023-10-11T16:00:00.000Z","financialDocumentStatusId":1,"numberOfTickets":1,"customerName":"Testing supplier","amountDue":37,"currency":"$","maxCashPaymentAmount":null,"maxChequePaymentAmount":null,"tickets":[{"financialDocumentId":2496,"weighingId":75,"ticketNumber":"SWPS1039","transactionDate":"2023-10-11T16:00:00.000Z","materials":"Wood Packaging","taxAmount":6.17,"amountDue":37,"amountPaidByCash":null,"amountPaidByCheque":null,"currency":"$","exceptions":"","defaultImmediatePayablePaymentTypeId":2}]}]'
          description: List of supplier invoice tickets.
      additionalProperties: false
    AMCSPayDisbursementAddDisbursementResponse:
      type: object
      properties:
        result:
          type: object
          description: Holds the response object depends on the provider.
          $ref: '#/components/schemas/AMCSAptPayAddDisbursementDataResponse'
    AMCSAptPayDisbursementGetSupplierDataResponse:
      type: object
      properties:
        id:
          type: number
          example: '183867559356'
        firstName:
          type: string
          example: Steven
        middleName:
          type: string
          example: Oliver
        lastName:
          type: string
          example: Kyamko
        country:
          type: string
          example: CA
        dateOfBirth:
          type: string
          example: '2000-01-01'
        phone:
          type: string
          example: '+639201001111'
        occupation:
          type: string
          example: Janitor
        individual:
          type: boolean
          example: true
        clientId:
          type: string
          example: '12312'
        name:
          type: string
          example: TestStevenK
        email:
          type: string
          example: jametests@gmail.com
        status:
          type: string
          example: ACTIVE
        amlStatus:
          type: string
          example: PASSED
        businessTaxId:
          type: string
          example: '12312'
        street:
          type: string
          example: Street 1
        streetLine2:
          type: string
          example: Street 2
        city:
          type: string
          example: Toronto
        province:
          type: string
          example: 'ON'
        zip:
          type: string
          example: L4K 0J7
        dbaName:
          type: string
          example: Steven
        url:
          type: string
          example: sampleurl.com
        typeOfBusiness:
          type: string
          example: Corporation
        dateOfIncorporation:
          type: string
          example: '2000-01-01'
        countryOfRegistration:
          type: string
          example: CA
        provinceOfRegistration:
          type: string
          example: 'ON'
        selfVerify:
          type: boolean
          example: true
        nationalIdentityNumber:
          type: string
          example: ''
    AMCSPayCheckAccountResponse:
      type: object
      properties:
        Data:
          type: object
          $ref: '#/components/schemas/AMCSPayCheckAccountResponseData'
        Error:
          type:
          - array
          - 'null'
          description: Contains the error description of the response
          items:
            $ref: '#/components/schemas/AMCSAptPayErrorDataResponse'
        IsSuccess:
          type: boolean
          description: Returns true if it doesn't contains error; False if it contains error
    AMCSPayDisbursementAddSupplierResponse:
      type: object
      properties:
        result:
          type: object
          description: Holds the response object depends on the provider.
          $ref: '#/components/schemas/AMCSAptPayBasicDataResponse'
    AMCSAptPayGetIdentityResponse:
      type: object
      properties:
        Data:
          type:
          - object
          - 'null'
          $ref: '#/components/schemas/AMCSAptPayGetIdentityDataResponse'
        Error:
          type:
          - array
          - 'null'
          description: Contains the error description of the response
          items:
            $ref: '#/components/schemas/AMCSAptPayErrorDataResponse'
        IsSuccess:
          type: boolean
          description: Returns true if it doesn't contains error; False if it contains error
    AMCSPayDisbursementGetSupplierRequest:
      type: object
      required:
      - provider
      - data
      properties:
        provider:
          type: string
          description: 'Provider to use to get supplier for disbursement.


            - AptPay'
          example: AptPay
        data:
          type: object
          description: Holds the request object depends on the provider.
          $ref: '#/components/schemas/AMCSAptPayGetIdentityRequest'
    AMCSAptPayGetIdentityRequest:
      type: object
      required:
      - id
      properties:
        id:
          type: number
          description: The identity id of the request
          example: '123'
    AMCSPayErrorResponse:
      type: object
      properties:
        message:
          type:
          - string
          - 'null'
          example: error message
          description: The exception message.
        type:
          type:
          - string
          - 'null'
          example: error message
          description: The type of exception thrown.
        stackTrace:
          type:
          - string
          - 'null'
          example: error message
          description: The stack trace of the error encountered.
    AMCSAptPayGetIdentityDataResponse:
      properties:
        id:
          type: integer
        individual:
          type: boolean
        name:
          type:
          - string
          - 'null'
        firstName:
          type:
          - string
          - 'null'
        middleName:
          type:
          - string
          - 'null'
        lastName:
          type:
          - string
          - 'null'
        dateOfBirth:
          type:
          - string
          - 'null'
        phone:
          type:
          - string
          - 'null'
        occupation:
          type:
          - string
          - 'null'
        street:
          type:
          - string
          - 'null'
        streetLine2:
          type:
          - string
          - 'null'
        city:
          type:
          - string
          - 'null'
        zip:
          type:
          - string
          - 'null'
        country:
          type:
          - string
          - 'null'
        province:
          type:
          - string
          - 'null'
        email:
          minLength: 1
          type: string
        dbaName:
          type:
          - string
          - 'null'
        url:
          type:
          - string
          - 'null'
        typeOfBusiness:
          type:
          - string
          - 'null'
        dateOfIncorporation:
          type:
          - string
          - 'null'
        countryOfRegistration:
          type:
          - string
          - 'null'
        provinceOfRegistration:
          type:
          - string
          - 'null'
        businessTaxId:
          type:
          - string
          - 'null'
        clientId:
          minLength: 1
          type: string
        selfVerify:
          type:
          - boolean
          - 'null'
        nationalIdentityNumber:
          type:
          - string
          - 'null'
    AMCSPayCheckAccountRequest:
      type: object
      required:
      - amount
      - currency
      properties:
        amount:
          type: number
          example: 10
          description: Amount to be disbursed.
        currency:
          type: string
          example: CAD
          description: Currency to be used. This is expressed as a three-letter currency code (ie., CAD for Canadian dollars, USD for United States Dollars, etc.)
        disbursementNumber:
          type: string
          example: '5333619503715702'
          description: '<span style=''color: rgb(212, 31, 28)''>Required if instrumentId is not defined.</span> Card number or account number'
        instrumentId:
          type: string
          example: ''
          description: '<span style=''color: rgb(212, 31, 28)''>Required if disbursementNumber is not defined.</span> The Instrument ID'
        program:
          type: string
          enum:
          - B2B
          - B2C
          - G2C
          - PayrollAndPension
          - RapidMerchantSettlement
          example: ''
          description: <b>Optional.</b> Program ID. This is a code to denote the use case for product (B2B, B2C, G2C, PayrollAndPension, RapidMerchantSettlement)
        expirationDate:
          type: string
          example: null
          description: <b>Optional.</b> The card expiration date
    AMCSAptPayGetTranStatusResponse:
      type: object
      properties:
        Data:
          type:
          - object
          - 'null'
          $ref: '#/components/schemas/AMCSAptPayGetTranStatusBasicDataResponse'
        Error:
          type:
          - array
          - 'null'
          description: Contains the error description of the response
          items:
            $ref: '#/components/schemas/AMCSAptPayErrorDataResponse'
        IsSuccess:
          type: boolean
          description: Returns true if it doesn't contains error; False if it contains error
    AMCSAptPayBasicDataResponse:
      type: object
      properties:
        id:
          type: string
          description: Generated ID from the API
          example: '183867559356'
        status:
          type: string
          description: Contains the status of the request
          example: AML check in progress
    AMCSPayDisbursementAddDisbursementRequest:
      type: object
      required:
      - provider
      - data
      properties:
        provider:
          type: string
          description: 'Provider to use to add disbursement.


            - AptPay'
          example: AptPay
        data:
          type: object
          description: Holds the request object depends on the provider.
          $ref: '#/components/schemas/AMCSAptPayAddDisbursementRequest'
    AMCSAptPayAddIdentityRequest:
      type: object
      required:
      - individual
      - email
      - clientId
      properties:
        individual:
          type: boolean
          description: "If this is an individual, set this parameter to True. If this is a business entity, set this to False.\n Default = true"
          example: true
        name:
          type:
          - string
          - 'null'
          description: '<div class=''optional-required''>This is required if individual is set to false</div>


            The business entity name'
          example: TestStevenK
        firstName:
          type:
          - string
          - 'null'
          description: '<div class=''optional-required''>This is required if individual is set to true</div>


            The individual''s first name (max 50 characters)'
          example: Steven
        middleName:
          type:
          - string
          - 'null'
          description: The individual's middle name.
          example: Oliver
        lastName:
          type:
          - string
          - 'null'
          description: '<div class=''optional-required''>This is required if individual is set to true</div>


            The individual''s last name.'
          example: Kyamko
        dateOfBirth:
          type:
          - string
          - 'null'
          description: '<div class=''optional-required''>This is required if individual is set to true</div>


            The individual’s date of birth. This is represented as YYYY-MM-DD.'
          example: '2000-01-01'
        phone:
          type:
          - string
          - 'null'
          description: The contact's phone number.
          example: '+639201001111'
        occupation:
          type:
          - string
          - 'null'
          description: The occupation of the person or individual
          example: Janitor
        street:
          type:
          - string
          - 'null'
          description: The street address of the person or individual
          example: Street 1
        streetLine2:
          type:
          - string
          - 'null'
          description: The street line address of the person or individual
          example: Street 2
        city:
          type:
          - string
          - 'null'
          description: The city address of the person or individual
          example: Toronto
        zip:
          type:
          - string
          - 'null'
          description: The zip code or address of the person or individual
          example: L4K 0J7
        country:
          type: string
          description: '<div class=''optional-required''>This is required if individual is set to false</div>


            The country address of the person or individual'
          example: CA
        province:
          type:
          - string
          - 'null'
          description: '<div class=''optional-required''>This is required if individual is set to false</div>


            The province of the person or address'
          example: 'ON'
        email:
          type: string
          description: The email address of the person or individual
          example: jametests@gmail.com
        dbaName:
          type:
          - string
          - 'null'
          description: '<div class=''optional-required''>This is required if individual is set to false</div>


            The dba name'
          example: Steven
        url:
          type:
          - string
          - 'null'
          description: '<div class=''optional-required''>This is required if individual is set to false</div>


            The Website Address/URL, if applicable'
          example: sampleurl.com
        typeOfBusiness:
          type:
          - string
          - 'null'
          description: '<div class=''optional-required''>This is required if individual is set to false</div>


            The type of business this is. This will be defined as one of the following below:

            - Corporation

            - LLC

            - Sole Proprietorship

            - Medical or legal corporation

            - Association/Estate/Trust

            - Partnership

            - Tax Exempt Organization (501c)

            - Charity

            - International organization

            - Government/Municipality

            - Not for Profit

            - Trust

            - Professional Association'
          example: Corporation
        dateOfIncorporation:
          type:
          - string
          - 'null'
          description: '<div class=''optional-required''>This is required if individual is set to false</div>


            The date of incorporation'
          example: '2000-01-01'
        countryOfRegistration:
          type:
          - string
          - 'null'
          description: '<div class=''optional-required''>This is required if individual is set to false</div>


            The country of registration of the person or individual'
          example: CA
        provinceOfRegistration:
          type:
          - string
          - 'null'
          description: '<div class=''optional-required''>This is required if individual is set to false</div>


            The province of the person or individual'
          example: 'ON'
        businessTaxId:
          type:
          - string
          - 'null'
          description: The business Tax ID
          example: '12312'
        clientId:
          type: string
          description: The client ID
          example: '12312'
    AMCSAptPayErrorDataResponse:
      type: object
      properties:
        ErrorKey:
          type: string
          description: Contains error key
          example: ''
        ErrorMessage:
          type: string
          description: Contains the detailed error message
          example: ''