> ## Documentation Index > Fetch the complete documentation index at: https://docs.fingopay.io/llms.txt > Use this file to discover all available pages before exploring further. # Create M-Pesa C2B charge (STK Push) > Initiate an M-Pesa STK Push request to collect payment from a customer. The customer will receive a prompt on their phone to enter their PIN and authorize the payment. Optional fields are advanced; send only required fields unless your integration needs this behavior. ## OpenAPI ````yaml api-reference/openapi.json post /v1/mpesa/charge openapi: 3.1.0 info: title: Fingo Pay API description: >- Fingo Pay's unified payments API for M-Pesa C2B (STK Push), B2C disbursements, B2B transfers, bank transfers, account balances, and transactions. version: 1.0.0 servers: - url: https://api.fingopay.io security: - bearerAuth: [] tags: - name: Payments description: Receive payments from customers - name: Payouts description: Send payments to recipients - name: Accounts description: Account balances and management - name: Transactions description: Transaction history and lookup - name: Verification description: Pre-transaction verification and lookup - name: Webhooks description: Webhook event notifications paths: /v1/mpesa/charge: post: tags: - Payments summary: Create M-Pesa C2B charge (STK Push) description: >- Initiate an M-Pesa STK Push request to collect payment from a customer. The customer will receive a prompt on their phone to enter their PIN and authorize the payment. Optional fields are advanced; send only required fields unless your integration needs this behavior. operationId: mpesaCharge parameters: - name: Idempotency-Key in: header description: >- Unique key to safely retry POST without duplicates. Required in live environment. required: false schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object properties: merchantTransactionId: type: string description: >- Merchant-side reference used for reconciliation. Accepts 1-64 characters (letters, numbers, dot, underscore, or hyphen). example: invoice_48291 pattern: ^[A-Za-z0-9._-]{1,64}$ minLength: 1 maxLength: 64 amount: type: integer description: >- Amount in smallest currency unit (cents). Must be whole KES (divisible by 100). Range 1,000-25,000,000 (KES 10.00-250,000.00). example: 150000 minimum: 1000 maximum: 25000000 phoneNumber: type: string description: >- Customer MSISDN in Kenyan format (+2547/2547/07 or +2541/2541/01 followed by eight digits). example: '+254712345678' pattern: ^(?:\+254|254|0)(?:7|1)\d{8}$ narration: type: string description: Optional customer-facing narration. Maximum 140 characters. example: Invoice 48291 maxLength: 140 webhookUrl: type: string format: uri description: Override webhook destination for this charge. example: https://merchant.example/webhooks/fingo metadata: type: object description: >- Custom metadata key-value pairs. Up to 20 entries. Keys 1-64 characters (letters, numbers, dot, underscore, or hyphen). Values are strings, except reserved key subMerchantDetails which accepts an object. maxProperties: 20 additionalProperties: oneOf: - type: string maxLength: 500 - $ref: '#/components/schemas/SubMerchantDetails' propertyNames: type: string pattern: ^[A-Za-z0-9_.-]{1,64}$ shortcode: type: string description: >- **[Enterprise]** Optional collections shortcode to route the charge via your dedicated shortcode. example: '123456' x-enterprise: true subMerchantId: type: string description: >- **[Enterprise]** Optional internal sub-merchant identifier configured under your organization. example: SM-NAIROBI-001 x-enterprise: true customDisplayName: type: string description: >- Optional custom display name shown to customer (alphanumeric and spaces only, max 40 chars). example: ACME Store maxLength: 40 pattern: ^[a-zA-Z0-9 ]+$ required: - phoneNumber - amount - merchantTransactionId additionalProperties: false examples: minimal_standard: summary: Minimal payload for standard merchants value: merchantTransactionId: invoice_48291 amount: 150000 phoneNumber: '+254712345678' narration: Invoice 48291 enterprise_dedicated_shortcode: summary: Enterprise payload using dedicated shortcode and sub-merchant value: merchantTransactionId: invoice_48291_sm_001 amount: 150000 phoneNumber: '+254712345678' narration: Invoice 48291 shortcode: '600123' subMerchantId: SM-NAIROBI-001 metadata: subMerchantDetails: name: Nairobi West Branch riskLevel: medium responses: '202': description: Accepted — final result will be delivered via webhook. content: application/json: schema: $ref: '#/components/schemas/AcceptedResponse' '400': $ref: '#/components/responses/ErrorResponse' '401': $ref: '#/components/responses/ErrorResponse' '403': $ref: '#/components/responses/ErrorResponse' '409': $ref: '#/components/responses/ErrorResponse' '429': $ref: '#/components/responses/ErrorResponse' '500': $ref: '#/components/responses/ErrorResponse' components: schemas: SubMerchantDetails: type: object description: >- Optional sub-merchant enrichment details used when creating or updating a sub-merchant reference from API traffic. properties: name: type: string description: Display/trading name for the sub-merchant. example: Nairobi West Branch legalName: type: string description: Registered legal name for the sub-merchant. example: Nairobi West Branch Limited businessType: type: string description: Optional business entity type. example: Limited Liability Company email: type: string format: email description: Optional sub-merchant contact email. phoneNumber: type: string description: Optional sub-merchant contact phone number. example: '+254712345678' businessCertNo: type: string description: Optional business registration certificate number. taxId: type: string description: Optional tax identifier (for example KRA PIN). economicSector: type: string description: Optional economic sector reference. riskLevel: type: string enum: - low - medium - high description: >- Optional risk tier used for reconciliation and post-transaction controls. additionalProperties: false AcceptedResponse: type: object properties: status: type: string example: success message: type: string example: Transaction initiated successfully data: type: object properties: merchantTransactionId: type: string example: mtx_123 transactionId: type: string example: txn_01j7b6f9p5y9h required: - merchantTransactionId - transactionId required: - status - message - data Error: type: object properties: error: type: object properties: type: type: string enum: - invalid_request_error - authentication_error - rate_limit_error - api_error - idempotency_error - not_found_error - conflict_error description: Error category code: type: string enum: - missing_parameter - invalid_parameter - unauthorized - forbidden - too_many_requests - internal_error - duplicate - resource_not_found - missing_header - validation_error description: Specific error code message: type: string description: Human-readable error message param: type: - string - 'null' description: The parameter that caused the error, if applicable requestId: type: string description: Request ID for support reference required: - type - code - message required: - error responses: ErrorResponse: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Use your API key as a Bearer token. Example: Authorization: Bearer sk_live_... ````