> ## Documentation Index > Fetch the complete documentation index at: https://docs.kemypay.com/llms.txt > Use this file to discover all available pages before exploring further. # Request a payment (beta) > Asks your customer to pay from their mobile money account: they receive a prompt on their phone and confirm with their PIN. The result arrives by webhook (`mobile_money.collection.completed` or `.failed`). - `reference` is **your** unique reference. Sending the same request again returns the same payment with `200`: your customer is never charged twice. The same reference with another service, amount or phone number is refused. - `webhook_url` and `callback_url` sent here take priority over those of the service. - Returns `201` with status `processing` (or `pending` if the operator did not answer yet: we check it for you). - In test mode the result is immediate (see [Test mode](/test-mode)). ## OpenAPI ````yaml /openapi.yaml post /mobile-money/collections openapi: 3.1.0 info: title: KemyPay API version: '1.0' description: > KemyPay lets you collect mobile money payments in 12 African countries through one API, with one balance per service, country and currency. Every request is authenticated with a secret API key (`sk_live_…` or `sk_test_…`) and must come from one of your allowed IP addresses. Responses use the same envelope: `{ "success": true, "data": …, "meta": … }`, or `{ "success": false, "error": { "code", "message", "details" }, "meta": … }`. Collections, quotes and operator prediction are in **beta**: they are being rolled out in production. contact: name: KemyPay Support email: hi@kemypay.com servers: - url: https://api.kemypay.com/v1 description: Production security: - BearerAuth: [] tags: - name: Catalog description: Countries, operators, prices and service categories - name: Services description: Your services (one per app or business activity), validated by our team - name: Collections description: Collect a payment from a customer's mobile money account (beta) - name: Balances description: One balance per service, country and currency paths: /mobile-money/collections: post: tags: - Collections summary: Request a payment (beta) description: > Asks your customer to pay from their mobile money account: they receive a prompt on their phone and confirm with their PIN. The result arrives by webhook (`mobile_money.collection.completed` or `.failed`). - `reference` is **your** unique reference. Sending the same request again returns the same payment with `200`: your customer is never charged twice. The same reference with another service, amount or phone number is refused. - `webhook_url` and `callback_url` sent here take priority over those of the service. - Returns `201` with status `processing` (or `pending` if the operator did not answer yet: we check it for you). - In test mode the result is immediate (see [Test mode](/test-mode)). operationId: createCollection requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCollectionRequest' responses: '200': description: Same reference sent again — the existing payment, unchanged content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: '#/components/schemas/Collection' meta: $ref: '#/components/schemas/Meta' '201': description: Payment requested content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: '#/components/schemas/Collection' meta: $ref: '#/components/schemas/Meta' '403': $ref: '#/components/responses/ServiceNotActive' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationError' '503': $ref: '#/components/responses/OperatorUnavailable' components: schemas: CreateCollectionRequest: type: object required: - service - amount - currency - phone_number - reference properties: service: type: string format: uuid description: The code of the service that collects. example: 019a8f2e-4c1b-7d3a-9e55-2b6f0c1d8a47 amount: type: string description: >- The value of the goods, as a string. Respect the `decimals` of the operator. example: '1000' currency: type: string example: XAF country: type: string description: Optional check. Refused if the operator is in another country. example: CMR operator: type: string description: >- Operator code (`MTN_CMR`). Optional — guessed from the phone number when missing. example: MTN_CMR phone_number: type: string description: >- Mobile money number with the country code. Spaces, dashes and `+` are removed. example: '237670000000' reference: type: string description: >- Your own unique reference (1 to 100 letters, digits, `.` `_` `:` `-`). Makes the call safe to retry. example: order-2026-10-29-0001 fee_bearer: type: string enum: - merchant - customer description: 'Default: the setting of the service.' description: type: string description: >- Shown to your customer on the payment prompt. 4 to 22 letters, digits or spaces. example: Afroyamo Premium metadata: type: object description: Up to 10 keys with text values. Returned in the webhooks. additionalProperties: type: string example: user_id: '42' webhook_url: type: string format: uri description: >- https. Takes priority over the `webhook_url` of the service for this payment. callback_url: type: string format: uri description: >- Takes priority over the `callback_url` of the service for this payment. Collection: type: object properties: code: type: string format: uuid example: 019a9c41-7e2d-4b8f-a1c3-5d6e7f8a9b0c reference: type: string example: order-2026-10-29-0001 service_code: type: string format: uuid example: 019a8f2e-4c1b-7d3a-9e55-2b6f0c1d8a47 status: type: string enum: - pending - processing - completed - failed example: processing country: type: string example: CMR operator: type: string example: MTN_CMR phone_number: type: string example: '237670000000' currency: type: string example: XAF value: type: string description: The value of the goods you sent. example: '1000.00' amount: type: string description: What the customer pays. example: '1033.00' fee: type: string example: '33.00' fee_bearer: type: string enum: - merchant - customer example: customer net_amount: type: string description: Credited to the balance of the service when the payment succeeds. example: '1000.00' description: type: - string - 'null' example: Afroyamo Premium metadata: type: object additionalProperties: type: string example: user_id: '42' failure_code: type: - string - 'null' enum: - payer_not_found - payment_not_approved - insufficient_balance - payer_limit_reached - invalid_phone_number - invalid_amount - operator_unavailable - payment_in_progress - expired - unknown_error - null example: null failure_message: type: - string - 'null' example: null operator_transaction_id: type: - string - 'null' description: The reference of the transaction at the operator, once paid. example: null callback_url: type: - string - 'null' example: https://afroyamo.com/payment/done created_at: type: string format: date-time example: '2026-10-29T10:00:00+00:00' completed_at: type: - string - 'null' format: date-time example: null Meta: type: object properties: request_id: type: string example: a4f8e2c1b3d97056 timestamp: type: string format: date-time example: '2026-10-29T10:00:00+00:00' mode: type: string enum: - test - live example: live Error: type: object properties: success: type: boolean example: false error: type: object properties: code: type: string example: VALIDATION_ERROR message: type: string example: Some fields of the payment are missing or invalid. details: type: object additionalProperties: true example: phone_number: >- Required: the mobile money number with the country code, digits only, for example 237670000000. meta: $ref: '#/components/schemas/Meta' responses: ServiceNotActive: description: >- `FORBIDDEN`: the service is not `active` (in test mode, `pending_review` is accepted). content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false error: code: FORBIDDEN message: >- The service is pending_review: it cannot collect payments in live mode. details: service_status: pending_review meta: request_id: a4f8e2c1b3d97056 timestamp: '2026-10-29T10:00:00+00:00' mode: live NotFound: description: >- `RESOURCE_NOT_FOUND`: no service or payment with this code in your account and mode. content: application/json: schema: $ref: '#/components/schemas/Error' ValidationError: description: >- `VALIDATION_ERROR`: one or more fields are missing or invalid. `details` explains each field. content: application/json: schema: $ref: '#/components/schemas/Error' OperatorUnavailable: description: >- `OPERATION_FAILED`: the operator is closed for collections right now. Offer another operator. content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false error: code: OPERATION_FAILED message: >- ORANGE_CMR is temporarily unavailable for collections. Offer another operator or try again later. details: failure_code: operator_unavailable meta: request_id: a4f8e2c1b3d97056 timestamp: '2026-10-29T10:00:00+00:00' mode: live securitySchemes: BearerAuth: type: http scheme: bearer description: >- Your secret API key: `sk_live_…` (real money) or `sk_test_…` (test mode). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.