---
title: "Retrieve a Payments collection"
method: GET
path: "/payments"
tags: ["Payments"]
---

# Retrieve a Payments collection

`GET /payments`

Return a list of Payments, eventually filtered by criteria.

## Query parameters

- `isDelegated` boolean
- `to` string
- `from` string
- `page` number
- `perPage` number

## Headers

- `ApiKey` string, required
- `MerchantId` string, required
- `Environment` 'live' | 'sandbox', required

## Response `200`

- PaymentDto[]
  - `id` string, required — Unique identifier for the Payment
  - `intentId` string, required — Unique identifier for the PaymentIntent owning this Payment
  - `createdAt` string, required — Datetime in UTC timezone at which this object was created. Follows the [Datetime ISO](https://en.wikipedia.org/wiki/ISO_8601).
  - `updatedAt` string, required — 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).
  - `status` 'created' | 'failed' | 'pending' | 'successful', required — Current status of this Payment
  - `amount` number, required — 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).
  - `currency` string, required — Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html).
  - `method` 'mobile_money' | 'credit_card' | 'bank_transfer', required — The method selected by the customer to make this Payment
  - `country` string, required — 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.
  - `failure` PaymentFailureCauseDto
    - `code` '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', required — Unique code representing the failure cause for the payment.
    - `message` string, required — Human readable message explaining the failure cause. This message can be displayed to the customer.
    - `params` string[] — List of parameters causing the payment failure in case of invalid parameters
  - `fees` PaymentFeeDto[], required — Some fees may be applied on a Payment. This array provides information of the fees that could have been applied on this Payment.
    - `id` string, required — Unique identifier of the applied Fee object.
    - `rate` number, required — A rate corresponding to the amount (flat or percentage) applied by the fees.
    - `rateType` 'percent' | 'flat', required — Fees can either be a flat amount of the transaction amount or percentage of the transaction amount.
    - `amount` number, required — 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).
    - `currency` string, required — Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html).
    - `label` string — An optional label giving information on the reason of this fees.
    - `taxes` string[] — Taxes applied to this fee.
  - `nextAction` NextActionDto
    - `type` 'ussd' | 'otp' | 'redirection', required
    - `message` string, required
    - `data` RedirectionDataDto
      - `url` string, required — A fully qualified URL where the customer must be redirected to pursue the payment.
      - `urls` string, required — An array of fully qualified URLs where the customer must be redirected to pursue the payment.
      - `method` string, required — HTTP verb to be used to redirect the customer.
      - `headers` object
      - `data` object — 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.
  - `providerReference` string, required — provider reference that identify this payment
  - `gatewayId` string, required — gatewayId used for this payment (Mobile Money Only)
  - `number` string, required — 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` PaymentInformationDto
    - `recipient_name_hashmac` string — HMAC or hashed full name of the person receiving the funds. Send only hashed or pseudonymized values; do not send raw personal data.
    - `recipient_phone_hashmac` string — 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.
    - `customer_id_hashmac` string — Partner-side hashed customer identifier. Use when name or phone hashes are not available, to correlate transactions for fraud analysis.
    - `transaction_purpose` 'SALARY' | 'LOAN_DISBURSEMENT' | 'COMMISSION' | 'REFUND' | 'CASHOUT' | 'OTHER' — Declared purpose of the payment for compliance and reporting.
  - `isDelegated` boolean — Indicates whether this payment is a delegated payment.

## Other responses

- `401` — Wrong credentials
- `500` — Internal error

---

[API](https://skmtc.net/hub2/apis/hub2-service-api.md) · [All operations](https://skmtc.net/hub2/apis/hub2-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hub2/hub2-service-api/versions/adb17b4b80f4/schema)