> ## Documentation Index > Fetch the complete documentation index at: https://docs.krypta-pay.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a payin > Charges a customer's Mobile Money wallet directly. Depending on the operator, the response tells you what the customer must do next: - **Phone prompt** (most operators) — `checkoutUrl` is `null`; the customer approves on their phone with their PIN. - **Operator redirect** (e.g. Wave, Djamo, Orange Money Senegal) — redirect the customer to `checkoutUrl`; they come back to your `redirectUrl`. - **Code** (Orange Money Côte d'Ivoire and Burkina Faso) — `otpRequired` is true: show `otpInstructions` and send the code to [Confirm a payin with a code](/api-reference/payins/confirm-otp). The payin starts as `PENDING`; listen for the `PAYIN_RECEIVED` / `PAYIN_FAILED` webhooks or poll [Get a payin](/api-reference/payins/get). In sandbox the payin is simulated and returns `COMPLETED` immediately. **API key scope:** `payins:write` ## OpenAPI ````yaml POST /v1/payins/checkout openapi: 3.1.0 info: title: KryptaPay API version: 1.0.0 description: >- Collect and pay out across Africa — Mobile Money, bank transfers and stablecoins — through one REST API. Authenticate every request with your secret API key: `Authorization: Bearer kp__…`. All responses use the envelope `{ "ok": boolean, "data"?: …, "error"?: { "code", "message", "details"? } }`. contact: name: KryptaPay Support email: support@krypta-pay.com url: https://krypta-pay.com servers: - url: https://staging.api.krypta-pay.com description: Sandbox - url: https://api.krypta-pay.com description: Production security: - apiKey: [] tags: - name: Payins description: Collect money from your customers' Mobile Money wallets. - name: Payouts description: Send money to Mobile Money wallets, bank accounts and crypto addresses. - name: Fees description: Know the exact fee before you move money. - name: FX description: Exchange rates, quotes and conversions between your wallets. - name: Wallets description: Balances of your multi-currency wallets. - name: Transactions description: Unified history of every movement on your account. - name: Networks description: Which payment networks are currently available. - name: Status description: Public platform status. paths: /v1/payins/checkout: post: tags: - Payins summary: Create a payin description: >- Charges a customer's Mobile Money wallet directly. Depending on the operator, the response tells you what the customer must do next: - **Phone prompt** (most operators) — `checkoutUrl` is `null`; the customer approves on their phone with their PIN. - **Operator redirect** (e.g. Wave, Djamo, Orange Money Senegal) — redirect the customer to `checkoutUrl`; they come back to your `redirectUrl`. - **Code** (Orange Money Côte d'Ivoire and Burkina Faso) — `otpRequired` is true: show `otpInstructions` and send the code to [Confirm a payin with a code](/api-reference/payins/confirm-otp). The payin starts as `PENDING`; listen for the `PAYIN_RECEIVED` / `PAYIN_FAILED` webhooks or poll [Get a payin](/api-reference/payins/get). In sandbox the payin is simulated and returns `COMPLETED` immediately. **API key scope:** `payins:write` operationId: createPayin requestBody: content: application/json: schema: type: object properties: amount: type: string pattern: ^\d+(\.\d{1,8})?$ description: >- Decimal amount with up to 8 fractional digits, e.g. "1500" or "1500.75" currency: $ref: '#/components/schemas/Currency' network: $ref: '#/components/schemas/Network' description: Mobile Money network to charge. Must match `currency`. customer: type: object properties: fullName: type: string maxLength: 180 msisdn: type: string minLength: 6 maxLength: 20 description: >- MSISDN, local or international format (digits only or with a leading "+"), e.g. "97000000", "22997000000", or "+22997000000". The wallet that will be charged. email: type: string format: email additionalProperties: false required: - msisdn redirectUrl: type: string format: uri description: >- Where the operator sends the customer back after an operator redirect (`checkoutUrl`). expiresInSec: type: integer minimum: 60 maximum: 86400 description: >- How long the customer has to approve the payment, in seconds (60 to 86400). required: - amount - currency - customer - network additionalProperties: false example: amount: '5000' currency: XOF network: MTN_BJ customer: fullName: Awa Koné msisdn: '22997000000' email: awa@example.com redirectUrl: https://example.com/orders/1042 expiresInSec: 900 required: true responses: '201': description: Success content: application/json: schema: type: object properties: ok: type: boolean enum: - true data: type: object properties: reference: type: string status: $ref: '#/components/schemas/TransactionStatus' amount: type: string pattern: ^\d+(\.\d{1,8})?$ description: >- Decimal amount with up to 8 fractional digits, e.g. "1500" or "1500.75" currency: $ref: '#/components/schemas/Currency' checkoutUrl: type: - string - 'null' description: >- Operator page to redirect the customer to, for operators that need it. `null` when the customer approves on their phone. expiresInSec: type: integer otpRequired: type: boolean description: >- True when the operator needs a one-time code from the customer to confirm the payment. otpInstructions: type: - string - 'null' description: >- Text to show the customer explaining how to obtain the code. required: - reference - status - amount - currency - checkoutUrl - expiresInSec additionalProperties: false required: - ok - data additionalProperties: false example: ok: true data: reference: tx_3Jk9QwErTy7uIoPa2Sd status: PENDING amount: '5000' currency: XOF checkoutUrl: null expiresInSec: 900 otpRequired: false otpInstructions: null '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateLimited' '502': $ref: '#/components/responses/UpstreamUnavailable' components: schemas: Currency: type: string enum: - XOF - XAF - NGN - GHS - CDF - EUR - USD - USDC - USDT description: ISO currency code (fiat) or stablecoin ticker. Network: type: string enum: - MTN_BJ - MTN_CI - MTN_CM - ORANGE_CI - ORANGE_SN - ORANGE_ML - ORANGE_BF - ORANGE_CM - MOOV_BJ - MOOV_TG - MOOV_CI - MOOV_BF - WAVE_CI - WAVE_SN - FREE_SN - TMONEY_TG - MOBICASH_ML - MOBICASH_BF - DJAMO_CI - MIXX_SN - MTN_CG - AIRTEL_CG - ORANGE_CD - AIRTEL_CD - VODACOM_CD - AFRICELL_CD - AIRTEL_GA - MOMO_NG - AIRTEL_NG - OPAY_NG - MTN_GH - VODAFONE_GH - AIRTELTIGO_GH - BANK_XOF - BANK_XAF - BANK_NGN - BANK_GHS - BANK_CDF - BANK_EUR - BANK_USD - ETH - POLYGON - TRON description: >- Payment network. See [Networks & currencies](/networks) for countries and limits. TransactionStatus: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED - CANCELLED - REFUNDED description: >- Lifecycle status. `COMPLETED`, `FAILED`, `CANCELLED` and `REFUNDED` are final. Error: type: object properties: ok: type: boolean enum: - false error: type: object properties: code: type: string description: Stable, machine-readable code. Branch on this, not on `message`. message: type: string description: Human-readable explanation. May change; do not parse. details: description: >- Extra context. For `validation_error`: `{ formErrors, fieldErrors }`. required: - code - message required: - ok - error responses: Unauthorized: description: Missing, invalid or expired API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: ok: false error: code: unauthorized message: Invalid or expired API key Forbidden: description: >- The key lacks the required scope (`insufficient_scope`), or the account is not KYB-approved (`kyb_required`). content: application/json: schema: $ref: '#/components/schemas/Error' example: ok: false error: code: kyb_required message: Your organization must complete KYB verification. ValidationError: description: >- The request failed validation or a business rule. See `error.code` and, for `validation_error`, `error.details.fieldErrors`. content: application/json: schema: $ref: '#/components/schemas/Error' example: ok: false error: code: validation_error message: 'amount: Invalid amount' RateLimited: description: >- Too many requests. Wait for the number of seconds in the `retry-after` header. content: application/json: schema: $ref: '#/components/schemas/Error' example: ok: false error: code: rate_limited message: Rate limit exceeded, retry in 1 minute UpstreamUnavailable: description: >- The payment operator could not process the request. Retry with backoff or use another network. content: application/json: schema: $ref: '#/components/schemas/Error' example: ok: false error: code: payin_unavailable message: Le paiement Mobile Money est momentanément indisponible. securitySchemes: apiKey: type: http scheme: bearer description: >- Secret API key from **Dashboard → Developers**: `kp_sandbox_…` for Sandbox, `kp_live_…` for Production. Server-side only. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.