--- title: "Create Payment Code" method: POST path: "/v1/payment-codes" tags: ["Payment Code"] --- # Create Payment Code `POST /v1/payment-codes` Creates a new payment code with the specified parameters for value collection and provider restrictions. ## Headers - `Idempotency-Key` string, required — This header is used to uniquely identify a logical request, ensuring that it is not processed more than once during retries. - `Monime-Version` 'caph.2025-08-23' | 'caph.2025-06-20', nullable — Specifies which version of the Monime API will handle this request. - `Monime-Space-Id` string, required — The value is the tenancy parameter that Monime uses to determine which space the request is intended for. ## Request body - object — Creates a new payment code with the specified parameters for value collection and provider restrictions. - `mode` 'one_time' | 'recurrent' — Defines whether the payment code is single-use ('one_time') or reusable ('recurrent'). - `name` string, nullable, required — Descriptive name for the payment code, used for display or tracking. - `enable` boolean — Whether the payment code should be enabled for use on creation. - `amount` object — Amount to charge per use of the payment code. For 'recurrent' codes, this applies to each payment. - `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. - `duration` string — How long the payment code remains valid before expiring. - `customer` object, nullable — Customer associated with the payment code, if any. - `name` string, nullable — Optional name of the customer associated with the payment code. Displayed in the USSD prompt for contextual reference. - `reference` string, nullable — Reference tag to associate with this payment code for reconciliation or tracking. - `authorizedProviders` string[], nullable — List of mobile money provider IDs permitted to process payments using this code. - `authorizedPhoneNumber` string — MSISDN of the mobile money account exclusively allowed to use this code. - `recurrentPaymentTarget` object, nullable — Defines the target number of payments or total amount for completing a recurrent code. - `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 — Financial account where collected funds are settled. Defaults to the main account if omitted. - `metadata` object, nullable — Optional metadata for attaching custom business context to the payment code. ## 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 — 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. --- - `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. --- [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)