> ## Documentation Index > Fetch the complete documentation index at: /llms.txt > Use this file to discover all available pages before exploring further. ## OpenAPI ````yaml /openapi/payments.yaml post /payments openapi: 3.0.3 info: title: Simiz Payments API version: 2024-01 description: > The Simiz Payments API lets you accept Mobile Money payments in Central and West Africa. ## Authentication All payment endpoints require a Bearer token using your API key: ``` Authorization: Bearer smz_test_sk_xxx ``` Checkout **public** endpoints (retrieve, pay, status, cancel) require no authentication — they are accessed by the end customer. ## Environments | Environment | Base URL | API Key Prefix | |-------------|----------|----------------| | **Sandbox** | `https://sandbox.api.simiz.io/v1` | `smz_test_` | | **Production** | `https://api.simiz.io/v1` | `smz_live_` | ## Idempotency For `POST` requests, include an `Idempotency-Key` header to safely retry requests without creating duplicate resources. Keys expire after 24 hours. contact: name: Simiz Support email: developer@simiz.io url: https://simiz.io/docs license: name: Proprietary url: https://simiz.io/legal/terms servers: - url: https://api.simiz.io/v1 description: Production — use smz_live_ keys - url: https://sandbox.api.simiz.io/v1 description: Sandbox — use smz_test_ keys security: [] tags: - name: Payments description: > Create and manage payment transactions. A transaction represents a single payment from a customer via Mobile Money. Authenticated with API key. - name: Checkout (Public) description: > Public checkout endpoints used by the payment page on the customer side. No authentication required. - name: Payment Links (Public) description: > Public payment link resolution. These endpoints are used by the hosted payment page when a customer opens a payment link. **No authentication required.** paths: /payments: post: tags: - Payments summary: Create a payment description: > Initiate a new Mobile Money payment. Returns a unique token and a `paymentUrl` to redirect the customer to. The customer will receive a USSD prompt on their phone to confirm the payment. operationId: createPayment parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePaymentBody' example: userId: 550e8400-e29b-41d4-a716-446655440000 amount: 5000 currency: XAF returnUrl: https://merchant.com/payment/success cancelUrl: https://merchant.com/payment/cancel description: 'Order #1234 — 2 items' responses: '201': description: Payment created successfully content: application/json: schema: $ref: '#/components/schemas/Transaction' example: id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 token: pay_abc123xyz789 projectId: 550e8400-e29b-41d4-a716-446655440000 amount: 5000 currency: XAF status: PENDING paymentUrl: https://pay.simiz.io/pay/pay_abc123xyz789 description: 'Order #1234 — 2 items' livemode: false createdAt: '2024-01-15T10:30:00Z' completedAt: null '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimited' security: - ApiKeyAuth: [] x-codeSamples: - lang: cURL source: | curl -X POST https://sandbox.api.simiz.io/v1/payments \ -H "Authorization: Bearer smz_test_sk_abc123" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: unique-key-123" \ -d '{ "userId": "550e8400-e29b-41d4-a716-446655440000", "amount": 5000, "currency": "XAF", "returnUrl": "https://merchant.com/payment/success", "cancelUrl": "https://merchant.com/payment/cancel", "description": "Order #1234" }' - lang: JavaScript label: Node.js source: > const response = await fetch('https://sandbox.api.simiz.io/v1/payments', { method: 'POST', headers: { 'Authorization': 'Bearer smz_test_sk_abc123', 'Content-Type': 'application/json', }, body: JSON.stringify({ userId: '550e8400-e29b-41d4-a716-446655440000', amount: 5000, currency: 'XAF', returnUrl: 'https://merchant.com/payment/success', cancelUrl: 'https://merchant.com/payment/cancel', description: 'Order #1234', }), }); const payment = await response.json(); console.log(payment.token, payment.paymentUrl); - lang: Python source: | import requests resp = requests.post( "https://sandbox.api.simiz.io/v1/payments", headers={"Authorization": "Bearer smz_test_sk_abc123"}, json={ "userId": "550e8400-e29b-41d4-a716-446655440000", "amount": 5000, "currency": "XAF", "returnUrl": "https://merchant.com/payment/success", "cancelUrl": "https://merchant.com/payment/cancel", "description": "Order #1234", }, ) payment = resp.json() components: parameters: IdempotencyKey: name: Idempotency-Key in: header description: >- Unique key for idempotent requests. Same key within 24h returns original response. schema: type: string example: idem_a1b2c3d4e5 schemas: CreatePaymentBody: type: object required: - userId - amount - returnUrl - cancelUrl properties: userId: type: string format: uuid description: UUID of the user initiating the payment example: 550e8400-e29b-41d4-a716-446655440000 amount: type: number minimum: 100 description: >- Payment amount in base currency unit (e.g. 5000 = 5,000 XAF). Minimum: 100 example: 5000 currency: type: string enum: - XAF - XOF default: XAF description: 'ISO 4217 currency code. Default: XAF' example: XAF returnUrl: type: string format: uri description: Redirect URL after successful payment example: https://merchant.com/payment/success cancelUrl: type: string format: uri description: Redirect URL if payment is cancelled example: https://merchant.com/payment/cancel description: type: string description: Payment description shown to the customer example: 'Order #1234 — 2 items' Transaction: type: object properties: id: type: string format: uuid token: type: string description: Unique payment token example: pay_abc123xyz789 projectId: type: string format: uuid reference: type: string nullable: true amount: type: number example: 5000 currency: type: string example: XAF status: $ref: '#/components/schemas/TransactionStatus' paymentMethod: $ref: '#/components/schemas/PaymentMethod' paymentUrl: type: string format: uri nullable: true description: URL to redirect the customer for payment payerPhone: type: string nullable: true payerName: type: string nullable: true payerEmail: type: string nullable: true description: type: string nullable: true livemode: type: boolean description: Whether this is a production transaction createdAt: type: string format: date-time completedAt: type: string format: date-time nullable: true TransactionStatus: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED - CANCELLED - EXPIRED - REFUNDED - PARTIALLY_REFUNDED description: | Transaction lifecycle: - `PENDING` — Awaiting payer confirmation - `PROCESSING` — Payment being processed by provider - `COMPLETED` — Payment received successfully - `FAILED` — Payment failed - `CANCELLED` — Cancelled by merchant or payer - `EXPIRED` — Payer did not confirm in time - `REFUNDED` — Fully refunded - `PARTIALLY_REFUNDED` — Partially refunded PaymentMethod: type: string enum: - ORANGE_MONEY - MTN_MOMO - UNKNOWN description: | Payment methods supported: - `ORANGE_MONEY` — Orange Money - `MTN_MOMO` — MTN Mobile Money - `UNKNOWN` — Fallback / not yet determined ApiError: type: object properties: statusCode: type: integer message: type: string error: type: string responses: BadRequest: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ApiError' example: statusCode: 400 message: amount must not be less than 100 error: Bad Request Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ApiError' example: statusCode: 401 message: Invalid or missing API key error: Unauthorized RateLimited: description: Too many requests content: application/json: schema: $ref: '#/components/schemas/ApiError' example: statusCode: 429 message: Rate limit exceeded error: Too Many Requests securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API Key (smz_*) description: > Use your Simiz API key as the Bearer token. Keys starting with `smz_test_sk_` target sandbox, `smz_live_sk_` target production. ````