> ## Documentation Index > Fetch the complete documentation index at: https://docs.monime.io/llms.txt > Use this file to discover all available pages before exploring further. # List Payment Codes > Retrieves a list of payment codes with support for filtering by mode, USSD code, and status. ## OpenAPI ````yaml get /v1/payment-codes openapi: 3.0.3 info: title: Monime API description: Monime REST API. Please visit https://docs.momime.io/api for more details. termsOfService: https://monime.io/legal/terms-of-service contact: name: Monime Developers url: https://github.com/monimesl email: dev@monime.io version: v1 servers: - url: https://api.monime.io/ security: - bearerAuth: [] paths: /v1/payment-codes: get: tags: - Payment Code summary: List Payment Codes description: >- Retrieves a list of payment codes with support for filtering by mode, USSD code, and status. operationId: ListPaymentCodes parameters: - name: ussd_code in: query description: >- Filter by the USSD code assigned to the payment code (if applicable). schema: type: string description: >- Filter by the USSD code assigned to the payment code (if applicable). nullable: true - name: mode in: query description: >- Filter by usage mode: 'one_time' for single-use codes, or 'recurrent' for reusable ones. schema: enum: - one_time - recurrent type: string description: >- Filter by usage mode: 'one_time' for single-use codes, or 'recurrent' for reusable ones. nullable: true - name: status in: query description: >- Filter by payment code status: 'pending' (not yet used), 'processing' (in use), 'expired' (duration elapsed), 'cancelled' (manually cancelled), or 'completed' (fulfilled as intended). schema: enum: - pending - cancelled - processing - expired - completed type: string description: >- Filter by payment code status: 'pending' (not yet used), 'processing' (in use), 'expired' (duration elapsed), 'cancelled' (manually cancelled), or 'completed' (fulfilled as intended). nullable: true - name: limit in: query description: >- Maximum number of items to return in a single page. Must be between 1 and 50. Defaults to 10 if not specified. schema: maximum: 50 minimum: 1 type: integer description: >- Maximum number of items to return in a single page. Must be between 1 and 50. Defaults to 10 if not specified. default: 10 - name: after in: query description: >- Pagination cursor for fetching the next page of results. Set this to the 'next' cursor value from a previous response to continue paginating forward. schema: maxLength: 2000 type: string description: >- Pagination cursor for fetching the next page of results. Set this to the 'next' cursor value from a previous response to continue paginating forward. nullable: true - name: Monime-Space-Id in: header description: >- The value is the tenancy parameter that Monime uses to determine which space the request is intended for. required: true schema: maxLength: 64 pattern: ^spc-.*$ type: string description: >- The value is the tenancy parameter that Monime uses to determine which space the request is intended for. - name: Monime-Version in: header description: Specifies which version of the Monime API will handle this request. schema: enum: - caph.2025-08-23 - caph.2025-06-20 type: string description: >- Specifies which version of the Monime API will handle this request. nullable: true responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean description: >- Represents the status of the query operation, confirming if it was successful. This field is always true messages: type: array items: {} description: >- Contains a list of messages providing relevant information or feedback related to the query or operation result: type: array items: $ref: '#/components/schemas/PaymentCode' description: The list of items in the response nullable: true pagination: type: object properties: count: type: integer description: Number of items returned in the current page. next: type: string description: >- 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. nullable: true description: The pagination info associated with the response components: schemas: PaymentCode: title: Payment Code type: object properties: id: type: string description: Unique identifier of the payment code object. mode: enum: - one_time - recurrent type: string description: >- 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: enum: - pending - cancelled - processing - expired - completed type: string description: >- 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: type: string description: >- Optional human-readable name for the payment code, useful for labeling or tracking. nullable: true example: Home EDSA Meter Top-up amount: type: object properties: currency: type: string description: >- The [3-letter](https://en.wikipedia.org/wiki/ISO_4217) ISO currency code. Currently supported: 'SLE' value: type: integer description: >- 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. additionalProperties: false description: >- Amount charged per use of the payment code. For 'recurrent' mode, this applies to each payment instance. enable: type: boolean description: Indicates whether the payment code is currently enabled for use. expireTime: type: string description: >- The time at which the payment code expires, provided the code is still pending. format: date-time customer: type: object properties: name: maxLength: 100 type: string description: >- Optional name of the customer associated with the payment code. Displayed in the USSD prompt for contextual reference. nullable: true example: Musa Kamara additionalProperties: false description: >- Optional customer information linked to this payment code. Often used for USSD or receipt context. nullable: true ussdCode: type: string description: >- The USSD dial string customer(s) can use to initiate a payment for this code. reference: type: string description: >- Reference string associated with the payment code. Useful for transaction tagging or reconciliation. nullable: true authorizedProviders: type: array items: enum: - m17 - m18 type: string description: >- The ID of the MOMO as identified by Monime. E.g. m17 to denote Orange Money SL description: >- List of mobile money providers permitted to process payments using this code. nullable: true example: - m17 - m18 authorizedPhoneNumber: type: string description: >- MSISDN of the mobile money account exclusively allowed to use this code. Other users will be rejected. recurrentPaymentTarget: type: object properties: expectedPaymentCount: minimum: 1 type: integer description: >- Minimum expected number of payments after which the recurrent payment code may be considered complete. Optional. nullable: true example: 10 expectedPaymentTotal: type: object properties: currency: type: string description: >- The [3-letter](https://en.wikipedia.org/wiki/ISO_4217) ISO currency code. Currently supported: 'SLE' value: type: integer description: >- 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. additionalProperties: false description: >- Minimum total amount to be collected before the recurrent payment code is considered complete. Optional. additionalProperties: false description: >- Target payment count or amount that determines when a recurrent payment code is considered complete. nullable: true financialAccountId: type: string description: >- ID of the financial account where collected funds will be settled. Defaults to the main account if not provided. nullable: true processedPaymentData: type: object properties: amount: type: object properties: currency: type: string description: >- The [3-letter](https://en.wikipedia.org/wiki/ISO_4217) ISO currency code. Currently supported: 'SLE' value: type: integer description: >- 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. additionalProperties: false orderId: type: string paymentId: type: string orderNumber: type: string channelData: type: object properties: providerId: type: string accountId: type: string reference: type: string financialTransactionReference: type: string metadata: maxProperties: 64 type: object additionalProperties: maxLength: 100 type: string description: Metadata values are free-form strings up to 100 characters. description: >- 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. nullable: true description: >- The data of the payment that was processed for this payment code. This field is available only during the 'payment_code.processed' webhook event. nullable: true createTime: type: string description: Timestamp indicating when the payment code was created. format: date-time updateTime: type: string description: Timestamp indicating when the payment code was last updated. format: date-time nullable: true ownershipGraph: title: OwnershipGraph type: object properties: owner: title: OwnershipObject type: object properties: id: type: string description: '**Unique ID** of the object instance that owns this entity.' readOnly: true type: type: string description: >- **Type of the object** that owns this entity. Examples include: 'internal_transfer', 'checkout_session', 'payment_code'. readOnly: true metadata: maxProperties: 64 type: object additionalProperties: maxLength: 100 type: string description: >- Metadata values are free-form strings up to 100 characters. description: '**Arbitrary metadata** describing the owning object.' nullable: true readOnly: true owner: $ref: '#/components/schemas/CoreresourcesParentOwningObject' additionalProperties: false description: >- **Immediate object** that owns this entity. This is the direct originator or source object. readOnly: true additionalProperties: false description: >- Full ownership graph tracing the origin of this payment code objects across multiple objects. nullable: true metadata: maxProperties: 64 type: object additionalProperties: maxLength: 100 type: string description: Metadata values are free-form strings up to 100 characters. description: >- Custom metadata attached to the payment code for storing business-specific context or tags. nullable: true description: >- A **Payment Code** is a programmable, short-lived token that allows users to collect payments from others. It is especially useful in **USSD-like** or **QR-based** flows, where the payer enters or scans a code to complete a transaction. Payment Codes provide flexibility for both **one-time** and **recurrent** collections, with configurable restrictions and targets. --- ### Use Cases - **USSD Payment Collection** A merchant generates a Payment Code and displays it in USSD. Customers enter the code to make payments. *Example*: A vendor creates a one-time code for **SLE 50** which a customer redeems via their mobile money wallet. - **QR Code at Point of Sale** The Payment Code is encoded as a QR displayed at checkout. Customers scan the QR to pay. *Example*: A shop generates a QR-based Payment Code for **SLE 200**, which is redeemed on the spot. - **Recurring Subscription Collection** A fitness center issues a recurrent Payment Code for monthly fees. *Example*: The code accepts up to **12 payments** of **SLE 500** each, after which it auto-completes. - **Targeted Collection** Restrict a Payment Code to a specific MSISDN or provider. *Example*: Only customers on **Orange Money** with a registered number can redeem the code. --- CoreresourcesParentOwningObject: title: OwnershipObject type: object properties: id: type: string description: '**Unique ID** of the object instance that owns this entity.' readOnly: true type: type: string description: >- **Type of the object** that owns this entity. Examples include: 'internal_transfer', 'checkout_session', 'payment_code'. readOnly: true metadata: maxProperties: 64 type: object additionalProperties: maxLength: 100 type: string description: Metadata values are free-form strings up to 100 characters. description: '**Arbitrary metadata** describing the owning object.' nullable: true readOnly: true owner: $ref: '#/components/schemas/CoreresourcesParentOwningObject' additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: auth-scheme description: >- Bearer HTTP authentication specified with the header Authorization: Bearer ````