AZA Finance Payin Methods API

openapi: 3.0.2
info:
  title: TransferZero Account Debits Payin Methods API
  description: Reference documentation for the TransferZero API V1
  version: '1.0'
servers:
- url: https://api-sandbox.transferzero.com/v1
- url: https://api.transferzero.com/v1
security:
- AuthorizationKey: []
  AuthorizationNonce: []
  AuthorizationSignature: []
- AuthorizationKey: []
  AuthorizationSecret: []
tags:
- name: Payin Methods
paths:
  /payin_methods/{PayinMethod ID}:
    get:
      tags:
      - Payin Methods
      summary: Fetching a payin method
      description: Show a payin method by id
      operationId: get-payin-method
      parameters:
      - name: PayinMethod ID
        in: path
        description: 'ID of the payin method to get.


          Example: `/v1/payin_methods/bf9ff782-e182-45ac-abea-5bce83ad6670`'
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayinMethodResponse'
        '401':
          description: Authentication information is missing or invalid.
        '404':
          description: Resource Not Found.
        '500':
          description: Internal Server Error.
      x-group-parameters: true
    delete:
      tags:
      - Payin Methods
      summary: Deleting a payin method
      description: Initiates a cancellation request for the specified payin method
      operationId: delete-payin-method
      parameters:
      - name: PayinMethod ID
        in: path
        description: 'ID of the payin method to delete.


          Example: `/v1/payin_methods/bf9ff782-e182-45ac-abea-5bce83ad6670`'
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Details of deleted payin method
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayinMethodResponse'
        '401':
          description: Authentication information is missing or invalid.
        '404':
          description: Resource Not Found.
        '422':
          description: Invalid payin method object (includes errors object)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayinMethodResponse'
        '500':
          description: Internal Server Error.
    patch:
      tags:
      - Payin Methods
      summary: Updating a payin method
      description: Updates a single payin method by the Payin Method ID
      operationId: patch-payin-method
      parameters:
      - name: PayinMethod ID
        in: path
        description: 'ID of the payin method to get.


          Example: `/v1/payin_methods/bf9ff782-e182-45ac-abea-5bce83ad6670`'
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayinMethod'
        required: true
      responses:
        '200':
          description: Details of updated payin method
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayinMethodResponse'
        '401':
          description: Authentication information is missing or invalid.
        '404':
          description: Resource Not Found.
        '422':
          description: Invalid payin method object (includes errors object)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayinMethodResponse'
        '500':
          description: Internal Server Error.
  /payin_methods/{PayinMethod ID}/retry:
    post:
      tags:
      - Payin Methods
      summary: Retries PayinMethod
      description: 'Retries the collection process for the payin method.


        Please note only payin methods in `error` state can be retried.'
      operationId: retry-payin-method
      parameters:
      - name: PayinMethod ID
        in: path
        description: 'ID of the payin method whose collection process should be retried


          Example: `/v1/payin_methods/9d4d7b73-a94c-4979-ab57-09074fd55d33/retry`'
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayinMethodResponse'
        '401':
          description: Authentication information is missing or invalid.
        '404':
          description: Resource Not Found.
        '422':
          description: This operation is unavailable
        '500':
          description: Internal Server Error.
components:
  schemas:
    PayinMethod:
      type: object
      properties:
        type:
          type: string
          description: 'Describes how the payment should be requested from the sender.


            Possible values:

            - `GHS::Mobile`: GHS mobile collections

            - `UGX::Mobile`: UGX mobile collections

            - `XOF::Mobile`: XOF mobile collections

            - `NGN::Bank`: NGN bank collections

            - `EUR::Bank`: EUR IBAN collections

            - `GBP::Bank`: GBP IBAN collections

            '
          example: GHS::Mobile
        ux_flow:
          $ref: '#/components/schemas/PayinMethodUxFlow'
        in_details:
          $ref: '#/components/schemas/PayinMethodDetails'
        id:
          type: string
          format: uuid
          readOnly: true
          example: 97e79719-06e4-4794-aeeb-d2d9415d983a
        state:
          $ref: '#/components/schemas/PayinMethodState'
        state_reason_details:
          $ref: '#/components/schemas/StateReasonDetails'
        out_details:
          type: object
          description: This will contain the description on where to pay the funds. Please see the [Collections Details](https://docs.transferzero.com/docs/collection-details) in the API documentation on what to expect here.
          readOnly: true
        instructions:
          type: object
          description: This will contain the instructions on how to pay the funds. Please see the [Collections Details](https://docs.transferzero.com/docs/collection-details) in the API documentation on what to expect here.
          readOnly: true
        errors:
          additionalProperties:
            type: array
            readOnly: true
            items:
              $ref: '#/components/schemas/ValidationErrorDescription'
          description: The fields that have some problems and don't pass validation
          readOnly: true
          example:
            phone_number:
            - error: invalid
            documents:
            - error: blank
      description: This describes the specific details on how the funds should be collected from the sender.
      example:
        type: GHS::Mobile
        ux_flow: ussd_popup
        in_details:
          phone_number: '+233541299999'
          mobile_provider: vodafone
      externalDocs:
        description: Collections Details
        url: https://docs.transferzero.com/docs/collection-details
    PayinMethodDetailsBTC:
      type: object
      properties:
        refund_address:
          type: string
          description: Please make sure the refund_address is a valid BTC address belonging to the sender, as that is going to be used in case the transaction has to be refunded.
      description: "```JSON\n  \"details\": {\n    \"refund_address\": \"n4VQ5YdHf7hLQ2gWQYYrcxoE5B7nWuDFNF\"\n  }\n```"
    PayinMethodUxFlow:
      type: string
      description: 'Describes the collection experience that will be presented to

        the sender. Can be one of the following:


        * `ussd_popup`: Payment prompt is pushed to the sender''s phone. They can approve or decline. Supported for GHS::Mobile, UGX::Mobile

        * `ussd_voucher`: Sender has to request an authorization code via ussd of the mobile provider and then provide that code to initiate the transaction. Supported for XOF::Mobile(Orange)

        * `ussd_menu_approval`: Sender has to dial a USSD code and navigate to a list of payments to approve.

        * `otp_verified_ussd_popup`: Sender receives and validates an OTP then a payment prompt is pushed if the OTP they submit is valid.

        * `bank_transfer`: For bank collections. Sender should send funds to the bank account details specified in out_details. Supported for EUR::Bank, GBP::Bank

        * `http_redirect`: The sender will be redirected to a website where they can fill in their details to initiate the collection.'
      example: ussd_popup
      enum:
      - ussd_popup
      - ussd_voucher
      - ussd_menu_approval
      - otp_verified_ussd_popup
      - bank_transfer
      - http_redirect
      - blockchain
      - unknown
    ValidationErrorDescription:
      type: object
      properties:
        error:
          type: string
          description: Describes what the problem is with the field
          readOnly: true
          example: invalid
      description: The description of the error
      readOnly: true
      example:
        error: invalid
    PayoutMethodCountryEnum:
      type: string
      description: 'The country for the pickup or mobile payout.


        For USD cash pickup in Nigeria, valid options are:

        - `NG`: Nigeria


        For XOF cash pickup, valid options are:

        - `CI`: Ivory Coast

        - `ML`: Mali

        - `SN`: Senegal


        For XOF mobile payout, valid options are:

        - `BJ`: Benin

        - `BF`: Burkina Faso

        - `CI`: Ivory Coast

        - `ML`: Mali

        - `SN`: Senegal

        - `TG`: Togo


        For XAF mobile payout, valid options are:

        - `CG`: Congo

        - `CM`: Cameroon

        - `GA`: Gabon

        - `TD`: Chad'
      example: SN
      enum:
      - AF
      - AL
      - DZ
      - AS
      - AD
      - AO
      - AI
      - AQ
      - AG
      - AR
      - AM
      - AW
      - AX
      - AU
      - AT
      - AZ
      - BS
      - BH
      - BD
      - BB
      - BY
      - BE
      - BZ
      - BJ
      - BM
      - BT
      - BO
      - BA
      - BW
      - BV
      - BR
      - IO
      - BN
      - BG
      - BF
      - BI
      - KH
      - CM
      - CA
      - CV
      - KY
      - CF
      - TD
      - CL
      - CN
      - CX
      - CC
      - CO
      - KM
      - CG
      - CD
      - CK
      - CR
      - CI
      - HR
      - CU
      - CY
      - CZ
      - DK
      - DJ
      - DM
      - DO
      - TP
      - EC
      - EG
      - SV
      - GQ
      - ER
      - EE
      - ET
      - FK
      - FO
      - FJ
      - FI
      - FR
      - GF
      - PF
      - TF
      - GA
      - GM
      - GE
      - DE
      - GH
      - GI
      - GR
      - GL
      - GD
      - GP
      - GU
      - GT
      - GN
      - GW
      - GY
      - HT
      - HM
      - VA
      - HN
      - HK
      - HU
      - IS
      - IN
      - ID
      - IR
      - IQ
      - IE
      - IL
      - IT
      - JM
      - JP
      - JO
      - KZ
      - KE
      - KI
      - KP
      - KR
      - KV
      - KW
      - KG
      - LA
      - LV
      - LB
      - LS
      - LR
      - LY
      - LI
      - LT
      - LU
      - MO
      - MK
      - MG
      - MW
      - MY
      - MV
      - ML
      - MT
      - MH
      - MQ
      - MR
      - MU
      - YT
      - MX
      - FM
      - MD
      - MC
      - MN
      - MS
      - ME
      - MA
      - MZ
      - MM
      - NA
      - NR
      - NP
      - NL
      - AN
      - NC
      - NZ
      - NI
      - NE
      - NG
      - NU
      - NF
      - MP
      - 'NO'
      - OM
      - PK
      - PW
      - PS
      - PA
      - PG
      - PY
      - PE
      - PH
      - PN
      - PL
      - PT
      - PR
      - QA
      - RE
      - RO
      - RU
      - RW
      - SH
      - KN
      - LC
      - PM
      - VC
      - WS
      - SM
      - ST
      - SA
      - SN
      - RS
      - SC
      - SL
      - SG
      - SK
      - SI
      - SB
      - SO
      - ZA
      - GS
      - ES
      - LK
      - SD
      - SR
      - SJ
      - SZ
      - SE
      - CH
      - SY
      - TW
      - TJ
      - TZ
      - TH
      - TG
      - TK
      - TO
      - TT
      - TN
      - TR
      - TM
      - TC
      - TV
      - UG
      - UA
      - AE
      - GB
      - US
      - UM
      - UY
      - UZ
      - VU
      - VE
      - VN
      - VG
      - VI
      - WF
      - EH
      - YE
      - ZM
    PayinMethodState:
      type: string
      description: 'The state of the payin method, which can be one of the following:


        * `incomplete`: Some fields need to be filled in in_details before we can initiate the collection request.

        * `initial`: All required fields in in_details are present and collection process with the sender will start.

        * `pending`: Collection process has been started, waiting for sender to send funds.

        * `success`: Collection succeeded and funds have been cleared.

        * `processing`: Collection succeeded but waiting for funds to fully clear.

        * `error`: Collection failed. No funds received from sender. You can update or retry the PayinMethod.

        * `mispaid`: Collection succeeded but sender sent the wrong amount.

        * `canceled`: The transaction has been canceled and we will refund the sender soon.

        * `refunded`: The sender has been refunded the amount they sent in.

        * `exception`: An exception happened during processing of the collection. Please contact support.'
      readOnly: true
      example: initial
      enum:
      - incomplete
      - initial
      - pending
      - success
      - processing
      - error
      - mispaid
      - canceled
      - refunded
      - exception
    PayinMethodDetailsNGNBank:
      type: object
      properties:
        phone_number:
          type: string
          description: Sender's phone number
          example: '+2348187221236'
        account_name:
          type: string
          description: Merchant's virtual account name
          example: Test Merchant
        account_number:
          type: string
          description: Merchant's virtual account number
          example: '1234567890'
      description: "```JSON\n  \"details\": {\n    \"phone_number\": \"+2348187221236\",\n    \"account_name\": \"Test Merchant\",\n    \"account_number\": \"1234567890\"\n  }\n```"
    PayinMethodDetails:
      description: 'Fields needed by the payment processor. Depends on the chose payin type.


        See the appropriate model details for more info:


        - `NGN::Bank`: see [`PayinMethodDetailsNGNBank`](#model-PayinMethodDetailsNGNBank)

        - `GHS::Mobile`: see [`PayinMethodDetailsMobile`](#model-PayinMethodDetailsMobile)

        - `UGX::Mobile`: see [`PayinMethodDetailsMobile`](#model-PayinMethodDetailsMobile)


        Note that some payin processors don''t require additional input, these include `lhv` through `EUR::Bank` and `GBP::Bank`.

        Some providers like `providus` also have all of their fields set as optional, so you might not want to set any values.

        To use these providers please set this value to `{}` (an empty hash)

        '
      oneOf:
      - $ref: '#/components/schemas/PayinMethodDetailsNGNBank'
      - $ref: '#/components/schemas/PayinMethodDetailsMobile'
      - $ref: '#/components/schemas/PayinMethodDetailsBTC'
    PayinMethodResponse:
      type: object
      properties:
        object:
          $ref: '#/components/schemas/PayinMethod'
      readOnly: true
      example:
        object:
          type: GHS::Mobile
          ux_flow: ussd_popup
          in_details:
            phone_number: '+233541299999'
            mobile_provider: vodafone
    StateReasonDetails:
      type: object
      properties:
        code:
          type: string
          description: Status code of transaction
          readOnly: true
          example: '311'
        category:
          type: string
          description: Main category of status code, it could be paid, unknown, pickupable, temporary_error, recipient_error, sender_error, sender_action_required
          readOnly: true
          example: temporary_error
        messages:
          type: array
          description: Tiered messages
          readOnly: true
          example:
          - Temporary error
          - Switch Error
          - Issuer/Switch inoperative
          items:
            type: string
        description:
          type: string
          description: Public, human readable, detailed error message
          readOnly: true
          example: The central switch is not accepting transactions at the moment. We will retry the transaction
      readOnly: true
      example:
        code: '311'
        category: temporary_error
        messages:
        - Temporary error - Retriable
        - Switch Error
        - Issuer/Switch inoperative
        description: The central switch is not accepting transactions at the moment. We will retry the transaction
    PayinMethodDetailsMobile:
      type: object
      properties:
        phone_number:
          type: string
          description: The phone number where the funds should be collected from
          example: '+256129999999'
        mobile_provider:
          $ref: '#/components/schemas/PayoutMethodMobileProviderEnum'
        country:
          $ref: '#/components/schemas/PayoutMethodCountryEnum'
        otp:
          type: string
          description: The OTP that the sender received in otp verified ussd popup ux flow.
      description: "```JSON\n\"details\": {\n  \"phone_number\": \"+256129999999\",\n}\n```"
    PayoutMethodMobileProviderEnum:
      type: string
      description: 'The Mobile Wallet provider of the recipient:


        For XOF (Senegal) valid options are:

        - `orange`: Orange

        - `tigo`: Tigo

        - `emoney`: Emoney

        - `free`: Free

        - `expresso` : Expresso

        - `wave`: Wave


        For XOF (Ivory Coast) valid options are:

        - `orange`: Orange

        - `moov`: Moov

        - `mtn`: MTN

        - `wave`: Wave


        For XOF (Burkina Faso) valid options are:

        - `orange`: Orange

        - `mobicash`: Mobicash

        - `moov` : Moov


        For XOF (Togo) valid options are:

        - `moov`: Moov

        - `tmoney`: Tmoney


        For XOF (Benin) valid options are:

        - `moov`: Moov

        - `mtn`: Mtn


        For XOF (Mali) valid options are:

        - `orange`: Orange

        - `mobicash`: Mobicash

        - `tigo` : Tigo


        For GHS valid options are:

        - `airteltigo`: AirtelTigo

        - `mtn`: MTN

        - `vodafone`: Vodafone


        For KES valid options are:

        - `mpesa`: MPESA


        For UGX valid options are:

        - `africell`: Africell

        - `airtel`: Airtel

        - `mtn`: MTN

        - `telecom`: Telecom


        For XAF (Chad) valid options are:

        - `moov`: Moov


        For XAF (Cameroon) valid options are:

        - `orange`: Orange

        - `mtn`: MTN


        For XAF (Congo) valid options are:

        - `airtel`: Airtel

        - `mtn`: MTN


        For XAF (Gabon) valid options are:

        - `airtel`: Airtel

        - `moov`: Moov


        For GNF (Guinea) valid options are:

        - `orange`: Orange

        - `mtn`: MTN'
      example: orange
      enum:
      - africell
      - airtel
      - airteltigo
      - emoney
      - expresso
      - free
      - mobicash
      - moov
      - mpesa
      - mtn
      - orange
      - telecom
      - tigo
      - tmoney
      - vodafone
      - wave
  securitySchemes:
    AuthorizationKey:
      type: apiKey
      description: Please see the [Authentication guide](https://docs.transferzero.com/docs/authentication) on how to use these fields
      name: Authorization-Key
      in: header
    AuthorizationSecret:
      type: apiKey
      description: Please see the [Authentication guide](https://docs.transferzero.com/docs/authentication) on how to use these fields
      name: Authorization-Secret
      in: header
    AuthorizationNonce:
      type: apiKey
      description: Please see the [Authentication guide](https://docs.transferzero.com/docs/authentication) on how to use these fields
      name: Authorization-Nonce
      in: header
    AuthorizationSignature:
      type: apiKey
      description: Please see the [Authentication guide](https://docs.transferzero.com/docs/authentication) on how to use these fields
      name: Authorization-Signature
      in: header
externalDocs:
  description: API documentation and onboarding guide
  url: https://docs.transferzero.com/