> ## 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 Payments collection > Return a list of Payments, eventually filtered by criteria. ## OpenAPI ````yaml get /payments 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: /payments: get: tags: - Payments summary: Retrieve a Payments collection description: Return a list of Payments, eventually filtered by criteria. operationId: PaymentsController_getPaymentIntents parameters: - 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/PaymentDto' '401': description: Wrong credentials content: application/json: schema: $ref: '#/components/schemas/ApiUnauthorizedErrorAlias' '500': description: Internal error content: application/json: schema: $ref: '#/components/schemas/ApiInternalErrorAlias' components: schemas: PaymentDto: type: object properties: id: type: string description: Unique identifier for the Payment example: pay_QW2d6JnqiatcH8KhK0mD1 intentId: type: string description: Unique identifier for the PaymentIntent owning this Payment example: pi_z1urYtVFgEebtcj8fxp4v 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' status: type: string description: Current status of this Payment enum: - created - failed - pending - successful example: successful amount: type: number description: >- Amount intended to be collected by this payment. 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 method: type: string description: The method selected by the customer to make this Payment example: mobile_money enum: - mobile_money - credit_card - bank_transfer 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 failure: description: >- In case of a Payment attempt failure, this object will describe the reason of the failure title: PaymentFailureCause allOf: - $ref: '#/components/schemas/PaymentFailureCauseDto' fees: description: >- Some fees may be applied on a Payment. This array provides information of the fees that could have been applied on this Payment. title: PaymentFee type: array items: $ref: '#/components/schemas/PaymentFeeDto' nextAction: description: >- Action required to execute to continue the processing of this Payment. The action allows the customer to validate the Payment. - A redirection action provides all the information to redirect the customer to an external page, - A ussd action provides a message to display to the user for the validation of the Payment. He will receive a USSD message on his phone describing how to make the validation, - A otp action requires that you display an input to the customer to collect an OTP. A message is provided to explains to the user how to get this OTP. Then, the client will have to send the authentication request. title: NextAction allOf: - $ref: '#/components/schemas/NextActionDto' providerReference: type: string description: provider reference that identify this payment title: providerReference gatewayId: type: string description: gatewayId used for this payment (Mobile Money Only) title: gatewayId 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, - In case of a payment by Credit Card, it corresponds to the four last digits of the customer's credit card number. paymentInformation: description: >- Optional beneficiary metadata (hashed identifiers) attached to this payment. allOf: - $ref: '#/components/schemas/PaymentInformationDto' isDelegated: type: boolean description: Indicates whether this payment is a delegated payment. required: - id - intentId - createdAt - updatedAt - status - amount - currency - method - country - fees - providerReference - gatewayId - number 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 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 PaymentFailureCauseDto: type: object properties: code: type: string description: Unique code representing the failure cause for the payment. enum: - internal_error - service_unavailable - unknown_reason - customer_account_locked - customer_insufficient_funds - authentication_failed - authentication_timeout - timeout - bad_parameters - forbidden_by_provider - too_many_request - duplicate_request - canceled_by_customer - canceled - fraud_suspicion - unsupported_currency - payer_quota_exceeded - invalid_payment_processor - invalid_amount - blacklisted_msisdn - msisdn_invalid - card_expired - card_declined - card_stolen - card_refused - card_invalid - card_cvn_invalid - address_verification_failed - payment_limit_reached message: type: string description: >- Human readable message explaining the failure cause. This message can be displayed to the customer. params: description: >- List of parameters causing the payment failure in case of invalid parameters type: array items: type: string required: - code - message PaymentFeeDto: 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. rateType: type: string description: >- Fees can either be a flat amount of the transaction amount or percentage of the transaction amount. enum: - percent - flat 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: Taxes applied to this fee. type: array items: type: string required: - id - rate - rateType - amount - currency NextActionDto: type: object properties: type: type: string enum: - ussd - otp - redirection message: type: string data: description: '' allOf: - $ref: '#/components/schemas/RedirectionDataDto' required: - type - message PaymentInformationDto: type: object properties: recipient_name_hashmac: type: string description: >- HMAC or hashed full name of the person receiving the funds. Send only hashed or pseudonymized values; do not send raw personal data. example: a1b2c3d4e5f6 maxLength: 50 recipient_phone_hashmac: type: string description: >- HMAC or hashed MSISDN of the recipient (natural identifier for mobile money). Send only a partner-side hash or HMAC — clear phone numbers are rejected. example: a1b2c3d4e5f6 maxLength: 50 customer_id_hashmac: type: string description: >- Partner-side hashed customer identifier. Use when name or phone hashes are not available, to correlate transactions for fraud analysis. example: a1b2c3d4e5f6 maxLength: 50 transaction_purpose: type: string description: Declared purpose of the payment for compliance and reporting. enum: - SALARY - LOAN_DISBURSEMENT - COMMISSION - REFUND - CASHOUT - OTHER 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 RedirectionDataDto: type: object properties: url: type: string description: >- A fully qualified URL where the customer must be redirected to pursue the payment. urls: type: string description: >- An array of fully qualified URLs where the customer must be redirected to pursue the payment. method: type: string description: HTTP verb to be used to redirect the customer. example: post headers: type: object description: '' data: type: object description: >- Data that need to be used to make the redirection. It could be parameters for a GET request or a body payload for a POST. required: - url - urls - method ````