---
title: "List Payment Codes"
method: GET
path: "/v1/payment-codes"
tags: ["Payment Code"]
---

# List Payment Codes

`GET /v1/payment-codes`

Retrieves a list of payment codes with support for filtering by mode, USSD code, and status.

## Query parameters

- `ussd_code` string, nullable — Filter by the USSD code assigned to the payment code (if applicable).
- `mode` 'one_time' | 'recurrent', nullable — Filter by usage mode: 'one_time' for single-use codes, or 'recurrent' for reusable ones.
- `status` 'pending' | 'cancelled' | 'processing' | 'expired' | 'completed', nullable — Filter by payment code status: 'pending' (not yet used), 'processing' (in use), 'expired' (duration elapsed), 'cancelled' (manually cancelled), or 'completed' (fulfilled as intended).
- `limit` integer — Maximum number of items to return in a single page. Must be between 1 and 50. Defaults to 10 if not specified.
- `after` string, nullable — Pagination cursor for fetching the next page of results. Set this to the 'next' cursor value from a previous response to continue paginating forward.

## Headers

- `Monime-Space-Id` string, required — The value is the tenancy parameter that Monime uses to determine which space the request is intended for.
- `Monime-Version` 'caph.2025-08-23' | 'caph.2025-06-20', nullable — Specifies which version of the Monime API will handle this request.

## Response `200`

OK

- object
  - `success` boolean — Represents the status of the query operation, confirming if it was successful. This field is always true
  - `messages` unknown[] — Contains a list of messages providing relevant information or feedback related to the query or operation
    - unknown
  - `result` PaymentCode[], nullable — The list of items in the response
    - `id` string — Unique identifier of the payment code object.
    - `mode` 'one_time' | 'recurrent' — Usage mode of the payment code: - 'one_time': Can be used only once - 'recurrent': Can be used multiple times until a target is met or it expires.
    - `status` 'pending' | 'cancelled' | 'processing' | 'expired' | 'completed' — Lifecycle status of the payment code: 'pending' (created but not in use), 'processing' (currently in use), 'expired' (duration elapsed), 'completed' (usage or target fulfilled), or 'cancelled' (manually invalidated).
    - `name` string, nullable — Optional human-readable name for the payment code, useful for labeling or tracking.
    - `amount` object — Amount charged per use of the payment code. For 'recurrent' mode, this applies to each payment instance.
      - `currency` string — The [3-letter](https://en.wikipedia.org/wiki/ISO_4217) ISO currency code. Currently supported: 'SLE'
      - `value` integer — The value representation in the currency's minor unit. E.g. For 1 Leone (SLE 1), the value should be 100, denoting cents, the minor unit.
    - `enable` boolean — Indicates whether the payment code is currently enabled for use.
    - `expireTime` string, date-time — The time at which the payment code expires, provided the code is still pending.
    - `customer` object, nullable — Optional customer information linked to this payment code. Often used for USSD or receipt context.
      - `name` string, nullable — Optional name of the customer associated with the payment code. Displayed in the USSD prompt for contextual reference.
    - `ussdCode` string — The USSD dial string customer(s) can use to initiate a payment for this code.
    - `reference` string, nullable — Reference string associated with the payment code. Useful for transaction tagging or reconciliation.
    - `authorizedProviders` string[], nullable — List of mobile money providers permitted to process payments using this code.
    - `authorizedPhoneNumber` string — MSISDN of the mobile money account exclusively allowed to use this code. Other users will be rejected.
    - `recurrentPaymentTarget` object, nullable — Target payment count or amount that determines when a recurrent payment code is considered complete.
      - `expectedPaymentCount` integer, nullable — Minimum expected number of payments after which the recurrent payment code may be considered complete. Optional.
      - `expectedPaymentTotal` object — Minimum total amount to be collected before the recurrent payment code is considered complete. Optional.
        - `currency` string — The [3-letter](https://en.wikipedia.org/wiki/ISO_4217) ISO currency code. Currently supported: 'SLE'
        - `value` integer — The value representation in the currency's minor unit. E.g. For 1 Leone (SLE 1), the value should be 100, denoting cents, the minor unit.
    - `financialAccountId` string, nullable — ID of the financial account where collected funds will be settled. Defaults to the main account if not provided.
    - `processedPaymentData` object, nullable — The data of the payment that was processed for this payment code. This field is available only during the 'payment_code.processed' webhook event.
      - `amount` object
        - `currency` string — The [3-letter](https://en.wikipedia.org/wiki/ISO_4217) ISO currency code. Currently supported: 'SLE'
        - `value` integer — The value representation in the currency's minor unit. E.g. For 1 Leone (SLE 1), the value should be 100, denoting cents, the minor unit.
      - `orderId` string
      - `paymentId` string
      - `orderNumber` string
      - `channelData` object
        - `providerId` string
        - `accountId` string
        - `reference` string
      - `financialTransactionReference` string
      - `metadata` object, nullable — Metadata is a flexible map of string key-value pairs for tagging or attaching additional information. A maximum of 64 pairs is allowed per object.
    - `createTime` string, date-time — Timestamp indicating when the payment code was created.
    - `updateTime` string, date-time, nullable — Timestamp indicating when the payment code was last updated.
    - `ownershipGraph` object, nullable — Full ownership graph tracing the origin of this payment code objects across multiple objects.
      - `owner` object — **Immediate object** that owns this entity. This is the direct originator or source object.
        - `id` string — **Unique ID** of the object instance that owns this entity.
        - `type` string — **Type of the object** that owns this entity. Examples include: 'internal_transfer', 'checkout_session', 'payment_code'.
        - `metadata` object, nullable — **Arbitrary metadata** describing the owning object.
        - `owner` CoreresourcesParentOwningObject
          - `id` string — **Unique ID** of the object instance that owns this entity.
          - `type` string — **Type of the object** that owns this entity. Examples include: 'internal_transfer', 'checkout_session', 'payment_code'.
          - `metadata` object, nullable — **Arbitrary metadata** describing the owning object.
          - `owner` CoreresourcesParentOwningObject — recursive
    - `metadata` object, nullable — Custom metadata attached to the payment code for storing business-specific context or tags.
  - `pagination` object — The pagination info associated with the response
    - `count` integer — Number of items returned in the current page.
    - `next` string, nullable — Cursor pointing to the next page of results. Use this value as the 'after' query parameter in your next request to fetch the following page. If null, you have reached the end of the result set.

---

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