> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hub2.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve a Transfer collection

> Return a list of Transfers, eventually filtered by criteria.



## OpenAPI

````yaml get /transfers
openapi: 3.0.0
info:
  title: Hub2 Service · Api
  description: |-
    This is the Hub2 api reference |
          Please check https://docs.hub2.io/ for the full documentation |
          Rate limits of endpoints are here : https://docs.hub2.io/en/details/limits.html.
  version: 2.149.1
  contact:
    name: Hub2
    url: https://www.hub2.io/
    email: contact@hub2.io
servers: []
security: []
tags:
  - name: Payments
    description: >-
      Best known as the PAY-IN API, it provides endpoints for merchants to
      perform Hub2 PAY-IN transactions.
  - name: Transfers
    description: >-
      Best known as the PAY-OUT API, it provides endpoints for merchants to
      perform Hub2 PAY-OUT transactions.
  - name: IRT
    description: International Remittance Transfers
  - name: Balance
    description: ''
  - name: Webhooks
    description: ''
  - name: Provisioning
    description: ''
  - name: Payment on Terminal
    description: ''
  - name: Receipt
    description: ''
  - name: Sms
    description: ''
  - name: Data
    description: ''
  - name: Compliance
    description: ''
  - name: Recipient
    description: ''
  - name: Delegation
    description: ''
  - name: Deposits
    description: ''
  - name: Payment Links
    description: ''
  - name: Submerchants
    description: ''
paths:
  /transfers:
    get:
      tags:
        - Transfers
      summary: Retrieve a Transfer collection
      description: Return a list of Transfers, eventually filtered by criteria.
      operationId: TransfersController_filterGet
      parameters:
        - name: reference
          required: false
          in: query
          description: >-
            The reference provided by the client during the creation of this
            transfer. It will most likely be the internal ID of the transaction.
          schema:
            example: ref_2020_11_10_001
            type: string
        - name: isDelegated
          required: false
          in: query
          description: Only transactions matching the given delegated status
          schema:
            example: true
            type: boolean
        - name: to
          required: false
          in: query
          description: |-
            A date in UTC timezone to filters data to, inclusively.
                 Follows the [Datetime ISO](https://en.wikipedia.org/wiki/ISO_8601).
                 The default value is now().
          schema:
            example: '2020-10-15T12:09:49.355Z'
            type: string
        - name: from
          required: false
          in: query
          description: |-
            A date in UTC timezone to filters data from, inclusively.
                Follows the [Datetime ISO](https://en.wikipedia.org/wiki/ISO_8601).
                The default value is the first day of this month.
          schema:
            example: '2020-10-15T12:09:49.355Z'
            type: string
        - name: page
          required: false
          in: query
          description: |-
            The page number in the returned data. The default value is 1.
                Do use with 'perPage' query parameter to paginate properly.
          schema:
            example: 2
            type: number
        - name: perPage
          required: false
          in: query
          description: >-
            The maximum number of results that will be return. The default value
            is 10.
                Do use with 'page' query parameter to paginate properly.
          schema:
            example: 5
            type: number
        - name: ApiKey
          in: header
          description: >-
            Your api key. To create a key, please get into our dashboard. If you
            don't have access to it, please reach the Support team.
          required: true
          schema:
            type: string
        - name: MerchantId
          in: header
          description: >-
            Your merchant ID. This information is available in our dashboard. If
            you don't have access to it, please reach the Support team.
          required: true
          schema:
            type: string
        - name: Environment
          in: header
          description: >-
            Allow you to choose between the sandbox mode to perform some tests
            or the live mode for real world transactions.
          required: true
          schema:
            enum:
              - live
              - sandbox
            type: string
      responses:
        '200':
          headers:
            Content-Range:
              description: >-
                Indicate the response's range. Follow the format :
                start-end/total
              example: 5-9/16
              schema:
                type: string
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TransferNoBalanceDtoAlias'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiBadRequestErrorAlias'
        '401':
          description: Wrong credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiUnauthorizedErrorAlias'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiNotFoundErrorAlias'
        '429':
          description: 'ThrottlerException: Too Many Requests'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTooManyRequestErrorAlias'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiInternalErrorAlias'
components:
  schemas:
    TransferNoBalanceDtoAlias:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the Transfer
          example: tr_z1urYtVFgEebtcj8fxp4v
        merchantId:
          type: string
          description: Identifier of the merchant owning this Transfer
        createdAt:
          type: string
          description: |-
            Datetime in UTC timezone at which this object was created.
                 Follows the [Datetime ISO](https://en.wikipedia.org/wiki/ISO_8601).
          example: '2020-10-15T12:09:49.355Z'
        updatedAt:
          type: string
          description: >-
            Datetime in UTC timezone at which this object was updated for the
            last time .
                 Follows the [Datetime ISO](https://en.wikipedia.org/wiki/ISO_8601).
          example: '2020-10-15T12:16:26.128Z'
        reference:
          type: string
          description: >-
            A reference provided by the client during the creation of this
            Transfer
          example: ref_2020_11_10_001
        description:
          type: string
          description: >-
            An arbitrary string attached to the Transfer. Mostly useful for
            displaying to user. 
        status:
          type: string
          description: The current status of this Transfer
          example: successful
          enum:
            - created
            - successful
            - pending
            - failed
        amount:
          type: number
          description: >-
            Amount intended to be sent to the recipient. A positive integer
            representing how much to charge in the smallest currency unit (e.g.,
            100 cents to charge €1.00 or 100 to charge FCFA100, a zero-decimal
            currency).
          example: 100
        currency:
          type: string
          description: >-
            Three-letter [ISO currency
            code](https://www.iso.org/iso-4217-currency-codes.html).
          example: XOF
        mode:
          type: string
          description: |-
            Mode in which this transfer exists.
                The sandbox mode can be used during the integration phase and is available as soon as the merchant account is created. No real transactions are made in this mode.
                The live mode has to be used to make real transactions.
          example: live
          enum:
            - live
            - sandbox
        destination:
          description: Information about the recipient of this Transfer
          oneOf:
            - $ref: '#/components/schemas/MobileMoneyDto'
            - $ref: '#/components/schemas/BankTransferDto'
            - $ref: '#/components/schemas/AirtimeDto'
          discriminator:
            propertyName: type
            mapping:
              bank_transfer:
                $ref: '#/components/schemas/BankTransferDto'
              mobile_money:
                $ref: '#/components/schemas/MobileMoneyDto'
              airtime:
                $ref: '#/components/schemas/AirtimeDto'
          title: Destination
        fees:
          description: Fees applied to merchant's transfer-account uppon success
          title: TransferFee
          type: array
          items:
            $ref: '#/components/schemas/TransferFeeDto'
        failureCause:
          description: >-
            In case of failure, this object will describe the reason of the
            failure
          title: TransferFailureCause
          allOf:
            - $ref: '#/components/schemas/TransferFailureCauseDto'
        origin:
          description: Information about the origin of this transfer
          title: Origin
          allOf:
            - $ref: '#/components/schemas/OriginDto'
        overrideBusinessName:
          type: string
          description: override business name for aggregator
          title: overrideBusinessName
        overrideBusinessId:
          type: string
          description: override business id for merchant
          title: overrideBusinessId
        isIrt:
          type: boolean
          description: indicate if the transfer was international
          title: isIrt
        providerReference:
          type: string
          description: provider reference that identify this transfer
          title: providerReference
        gatewayId:
          type: string
          description: The gateway ID used for this transfer
          title: gatewayId
        isDelegated:
          type: boolean
          description: Indicates if the transfer is delegated
          title: isDelegated
        aggregatedMerchantId:
          type: string
          description: Aggregated merchant id
          title: aggregatedMerchantId
        providerData:
          type: object
          description: Provider data
          title: providerData
        subMerchantId:
          type: string
          description: Submerchant ID
          example: submerchant_123
        transferInformation:
          description: Merchant-defined payment metadata from transfer creation.
          example:
            recipient_name_hashmac: hash_xyz_789
            transaction_purpose: SALARY
          allOf:
            - $ref: '#/components/schemas/TransferInformationDto'
      required:
        - id
        - merchantId
        - createdAt
        - updatedAt
        - reference
        - description
        - status
        - amount
        - currency
        - mode
        - destination
        - fees
        - isIrt
        - providerReference
        - gatewayId
        - isDelegated
        - aggregatedMerchantId
    ApiBadRequestErrorAlias:
      type: object
      properties:
        status:
          type: number
          description: HTTP error code.
          example: 400
        error:
          description: HTTP error description.
          allOf:
            - $ref: '#/components/schemas/InternalApiBadRequestError'
      required:
        - status
        - error
    ApiUnauthorizedErrorAlias:
      type: object
      properties:
        status:
          type: number
          description: HTTP error code.
          example: 401
        error:
          description: HTTP error description.
          allOf:
            - $ref: '#/components/schemas/InternalApiUnauthorizedError'
      required:
        - status
        - error
    ApiNotFoundErrorAlias:
      type: object
      properties:
        httpStatus:
          type: number
          description: Http status
          enum:
            - 404
          example: 404
        message:
          type: string
          description: Detailed error message which describe what happened.
          example: X not found
        error:
          type: string
          description: Error message
          example: Not found
      required:
        - httpStatus
        - message
        - error
    ApiTooManyRequestErrorAlias:
      type: object
      properties:
        status:
          type: number
          description: status
          enum:
            - 429
          example: 429
        error:
          type: string
          description: Error
          example: 'ThrottlerException: Too Many Requests'
      required:
        - status
        - error
    ApiInternalErrorAlias:
      type: object
      properties:
        type:
          type: string
          description: The type of this error.
          example: internal_error
        code:
          type: string
          description: The error code for this error.
          example:
            - internal_error
            - wrong_credentials
            - not_granted
            - live_mode_not_granted
            - invalid_sandbox_msisdn
            - invalid_url
            - orange_invalid_url
            - wrong_provider
            - override_business_name
            - do_not_override_business_name
        message:
          type: string
          description: The error message describing what happens to throw this error.
          example: An error occurred on our system. Please try again later.
      required:
        - type
        - code
        - message
    MobileMoneyDto:
      type: object
      properties:
        type:
          type: string
          description: The method selected to make this Transfer
          example: mobile_money
          enum:
            - mobile_money
            - bank_transfer
            - airtime
        country:
          type: string
          description: >-
            Two-letter [ISO country
            code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). Represents
            the country where the provider selected by the customer is
            localized. 
          example: CI
        recipientName:
          type: string
          description: recipient's Name
        number:
          type: string
          description: |-
            The identifier referencing the payment method of the customer.
                - In case of a payment by Mobile Money, it corresponds to the customer phone number corresponding to his Mobile Money account
        provider:
          type: string
          description: >-
            The name of the provider selected by the customer, in lowercase. The
            list of supported providers can be found at
            [/data/providers](#operation/DataController_getProviders)
          example: orange
      required:
        - type
        - country
        - number
        - provider
    BankTransferDto:
      type: object
      properties:
        type:
          type: string
          description: The method selected to make this Transfer
          example: mobile_money
          enum:
            - mobile_money
            - bank_transfer
            - airtime
        country:
          type: string
          description: >-
            Two-letter [ISO country
            code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). Represents
            the country where the provider selected by the customer is
            localized. 
          example: CI
        recipientName:
          type: string
          description: recipient's Name
        number:
          type: string
          description: |-
            The identifier referencing the payment method of the customer.
                - In case of a payment by Bank Transfer, it corresponds to the customer bank account number
        accountOwner:
          type: string
          description: The Bank account owner name to which the money must be sent.
        bankCode:
          type: string
          description: The Bank code.
        bankName:
          type: string
          description: The Bank name.
        beneficiaryPhone:
          type: string
          description: The Beneficiary phone
      required:
        - type
        - country
        - number
        - accountOwner
        - bankCode
        - bankName
        - beneficiaryPhone
    AirtimeDto:
      type: object
      properties:
        type:
          type: string
          description: The method selected to make this Transfer
          example: mobile_money
          enum:
            - mobile_money
            - bank_transfer
            - airtime
        country:
          type: string
          description: >-
            Two-letter [ISO country
            code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). Represents
            the country where the provider selected by the customer is
            localized. 
          example: CI
        recipientName:
          type: string
          description: recipient's Name
        number:
          type: string
          description: |-
            The identifier referencing the payment method of the customer.
                - In case of a payment by Airtime, it corresponds to the customer phone number corresponding to his Airtime account
        provider:
          type: string
          description: >-
            The name of the provider selected by the customer, in lowercase. The
            list of supported providers can be found at
            [/data/providers](#operation/DataController_getProviders)
          example: orange
      required:
        - type
        - country
        - number
        - provider
    TransferFeeDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the applied Fee object.
          example: lAe5HnFpvOjwdT9vSIgPA
        rate:
          type: number
          description: >-
            A rate corresponding to the amount (flat or percentage) applied by
            the fees.
        type:
          type: string
          description: |-
            The type of fee applied to the transfer's amount
                
             - flat: A fixed amount applied as is to the amount.
                
             - percent: A rate applied to the amount as a percentage of the latter.
          enum:
            - flat
            - percent
        amount:
          type: number
          description: >-
            Amount applied by this Fees. A positive integer representing how
            much to charge in the smallest currency unit (e.g., 100 cents to
            charge €1.00 or 100 to charge FCFA100, a zero-decimal currency).
          example: 5
        currency:
          type: string
          description: >-
            Three-letter [ISO currency
            code](https://www.iso.org/iso-4217-currency-codes.html).
          example: XOF
        label:
          type: string
          description: An optional label giving information on the reason of this fees.
        taxes:
          description: An array containing every taxes applied to a fee
          type: array
          items:
            type: string
      required:
        - id
        - rate
        - type
        - amount
        - currency
        - taxes
    TransferFailureCauseDto:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        params:
          type: array
          items:
            type: string
      required:
        - code
        - message
        - params
    OriginDto:
      type: object
      properties:
        name:
          type: string
          description: Sender's name
        country:
          type: string
          description: >-
            Sender's country. Two-letter [ISO country
            code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
    TransferInformationDto:
      type: object
      properties:
        recipient_name_hashmac:
          type: string
          description: >-
            Full name of the person receiving the funds (hashed on the partner
            side).
          example: hash_xyz_789
          maxLength: 50
        recipient_phone_hashmac:
          type: string
          description: >-
            Partner-side HMAC or cryptographic hash of the recipient MSISDN (not
            the clear number). Requests that send a plain phone number in this
            field are rejected.
          example: a3f2c9e1b8d7...
          maxLength: 50
        customer_id_hashmac:
          type: string
          description: >-
            Partner-side hashed customer identifier. Use when name or phone
            cannot be sent, to correlate transactions for fraud analysis.
          example: hash_cust_abc
          maxLength: 50
        transaction_purpose:
          type: string
          description: Declared purpose of the payout for compliance and monitoring.
          enum:
            - SALARY
            - LOAN_DISBURSEMENT
            - COMMISSION
            - REFUND
            - CASHOUT
            - OTHER
          example: SALARY
    InternalApiBadRequestError:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP error code.
          example: 400
        message:
          description: >-
            Detailed error message or array of messages to describe what's
            wrong.
          example:
            - destination.provider must be a string
          type: array
          items:
            type: string
        error:
          type: string
          description: The error message
          example: Bad Request
      required:
        - statusCode
        - message
        - error
    InternalApiUnauthorizedError:
      type: object
      properties:
        type:
          type: string
          description: The type of this error.
          example: authorization_error
        code:
          type: string
          description: The internal error code describing what happened.
          enum:
            - bad_payment_intent_token
            - wrong_credentials
          example: wrong_credentials
        message:
          type: string
          description: Detailed error message which describe what happened.
          example: L'ID marchand et/ou la clé d'API sont incorrects.
      required:
        - type
        - code
        - message

````