> ## 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.

# Payment Code

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.

***

<ResponseExample>
  ```json JSON Model theme={null}
  {
      "id": null,
      "mode": "one_time",
      "status": "pending",
      "name": "Home EDSA Meter Top-up",
      "amount": {
          "currency": null,
          "value": null
      },
      "enable": null,
      "expireTime": null,
      "customer": {
          "name": "Musa Kamara"
      },
      "ussdCode": null,
      "reference": null,
      "authorizedProviders": [
          [
              "m17",
              "m18"
          ]
      ],
      "authorizedPhoneNumber": null,
      "recurrentPaymentTarget": {
          "expectedPaymentCount": null,
          "expectedPaymentTotal": {
              "currency": null,
              "value": null
          }
      },
      "financialAccountId": null,
      "processedPaymentData": {
          "amount": {
              "currency": null,
              "value": null
          },
          "orderId": null,
          "paymentId": null,
          "orderNumber": null,
          "channelData": {
              "providerId": null,
              "accountId": null,
              "reference": null
          },
          "financialTransactionReference": null,
          "metadata": null
      },
      "createTime": null,
      "updateTime": null,
      "ownershipGraph": {
          "owner": {
              "id": null,
              "type": null,
              "metadata": null,
              "": null
          }
      },
      "metadata": null
  }
  ```
</ResponseExample>

<ResponseField name="📋" type="Properties">
  <ResponseField name="id" type="string">
    Unique identifier of the payment code object.
  </ResponseField>

  <ResponseField name="mode" type="enum<string>">
    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.

    Available options: <code>one\_time</code> <code>recurrent</code>
  </ResponseField>

  <ResponseField name="status" type="enum<string>">
    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).

    Available options: <code>pending</code> <code>cancelled</code> <code>processing</code> <code>expired</code> <code>completed</code>
  </ResponseField>

  <ResponseField name="name" type="string">
    Optional human-readable name for the payment code, useful for labeling or tracking.

    Example: <code>Home EDSA Meter Top-up</code>
  </ResponseField>

  <ResponseField name="amount" type="object">
    Amount charged per use of the payment code. For 'recurrent' mode, this applies to each payment instance.

    <Expandable title="properties">
      <ResponseField name="currency" type="string">
        The [3-letter](https://en.wikipedia.org/wiki/ISO_4217) ISO currency code. Currently supported: 'SLE'
      </ResponseField>

      <ResponseField name="value" type="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.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="enable" type="boolean">
    Indicates whether the payment code is currently enabled for use.
  </ResponseField>

  <ResponseField name="expireTime" type="string">
    The time at which the payment code expires, provided the code is still pending.
  </ResponseField>

  <ResponseField name="customer" type="object">
    Optional customer information linked to this payment code. Often used for USSD or receipt context.

    <Expandable title="properties">
      <ResponseField name="name" type="string">
        Optional name of the customer associated with the payment code. Displayed in the USSD prompt for contextual reference.

        MaxLength: <code>100</code>

        Example: <code>Musa Kamara</code>
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="ussdCode" type="string">
    The USSD dial string customer(s) can use to initiate a payment for this code.
  </ResponseField>

  <ResponseField name="reference" type="string">
    Reference string associated with the payment code. Useful for transaction tagging or reconciliation.
  </ResponseField>

  <ResponseField name="authorizedProviders" type="array">
    List of mobile money providers permitted to process payments using this code.

    Example: <code>\[m17 m18]</code>
  </ResponseField>

  <ResponseField name="authorizedPhoneNumber" type="string">
    MSISDN of the mobile money account exclusively allowed to use this code. Other users will be rejected.
  </ResponseField>

  <ResponseField name="recurrentPaymentTarget" type="object">
    Target payment count or amount that determines when a recurrent payment code is considered complete.

    <Expandable title="properties">
      <ResponseField name="expectedPaymentCount" type="integer">
        Minimum expected number of payments after which the recurrent payment code may be considered complete. Optional.
      </ResponseField>

      <ResponseField name="expectedPaymentTotal" type="object">
        Minimum total amount to be collected before the recurrent payment code is considered complete. Optional.

        <Expandable title="properties">
          <ResponseField name="currency" type="string">
            The [3-letter](https://en.wikipedia.org/wiki/ISO_4217) ISO currency code. Currently supported: 'SLE'
          </ResponseField>

          <ResponseField name="value" type="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.
          </ResponseField>
        </Expandable>
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="financialAccountId" type="string">
    ID of the financial account where collected funds will be settled. Defaults to the main account if not provided.
  </ResponseField>

  <ResponseField name="processedPaymentData" type="object">
    The data of the payment that was processed for this payment code. This field is available only during the 'payment\_code.processed' webhook event.

    <Expandable title="properties">
      <ResponseField name="amount" type="object">
        <Expandable title="properties">
          <ResponseField name="currency" type="string">
            The [3-letter](https://en.wikipedia.org/wiki/ISO_4217) ISO currency code. Currently supported: 'SLE'
          </ResponseField>

          <ResponseField name="value" type="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.
          </ResponseField>
        </Expandable>
      </ResponseField>

      <ResponseField name="orderId" type="string" />

      <ResponseField name="paymentId" type="string" />

      <ResponseField name="orderNumber" type="string" />

      <ResponseField name="channelData" type="object">
        <Expandable title="properties">
          <ResponseField name="providerId" type="string" />

          <ResponseField name="accountId" type="string" />

          <ResponseField name="reference" type="string" />
        </Expandable>
      </ResponseField>

      <ResponseField name="financialTransactionReference" type="string" />

      <ResponseField name="metadata" type="object">
        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.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="createTime" type="string">
    Timestamp indicating when the payment code was created.
  </ResponseField>

  <ResponseField name="updateTime" type="string">
    Timestamp indicating when the payment code was last updated.
  </ResponseField>

  <ResponseField name="ownershipGraph" type="object">
    Full ownership graph tracing the origin of this payment code objects across multiple objects.

    <Expandable title="properties">
      <ResponseField name="owner" type="object">
        **Immediate object** that owns this entity. This is the direct originator or source object.

        <Expandable title="properties">
          <ResponseField name="id" type="string">
            **Unique ID** of the object instance that owns this entity.
          </ResponseField>

          <ResponseField name="type" type="string">
            **Type of the object** that owns this entity. Examples include: 'internal\_transfer', 'checkout\_session', 'payment\_code'.
          </ResponseField>

          <ResponseField name="metadata" type="object">
            **Arbitrary metadata** describing the owning object.
          </ResponseField>

          <ResponseField name="" type="" />
        </Expandable>
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="metadata" type="object">
    Custom metadata attached to the payment code for storing business-specific context or tags.
  </ResponseField>
</ResponseField>