> ## Documentation Index > Fetch the complete documentation index at: https://docs.archefusion.com/llms.txt > Use this file to discover all available pages before exploring further. # Initiate payment > This endpoint initiates a payment and routes it to the recommended gateway based on your configured smart routing rule and live provider health. If no rule matches, it falls back to your default provider order. ## OpenAPI ````yaml /archefusion-openapi.yaml post /v1/payments/initiate openapi: 3.0.0 info: title: OpenAPI Spec version: 1.0.0 description: '' servers: - url: https://dev.api-gateway.archefusion.com security: [] tags: - name: Payments paths: /v1/payments/initiate: post: tags: - Payments summary: Initiate payment description: >- This endpoint initiates a payment and routes it to the recommended gateway based on your configured smart routing rule and live provider health. If no rule matches, it falls back to your default provider order. requestBody: content: application/json: schema: type: object required: - merchantOrderId - amount - currency properties: merchantOrderId: type: string description: >- This represents a unique order ID generated by your system. It must be unique for every payment request. example: order-1e57-6y72-8u67 amount: type: integer description: >- This represents the payment amount in the main currency unit. For example, pass 1000 to charge ₦1,000 NGN. example: 1000 currency: type: string description: >- This represents the payment currency in ISO 4217 format. Currently supported: NGN. example: NGN customer: type: object description: This represents the customer's details. properties: id: type: string example: cust_123 email: type: string description: >- Optional overall, but required by some gateways depending on their configuration (e.g. KoraPay). example: customer@example.com phone: type: string example: 2349072305772 metadata: type: object description: >- This represents additional details about your product or service. properties: cartId: type: string example: cart_123 redirectUrl: type: string description: >- This represents the URL to redirect customers to after payment. If not provided, Archefusion uses the redirect URL configured on your dashboard. example: https://merchant.example.com/payment/callback paymentMethod: type: string description: >- This represents the payment method used to match your configured smart routing rule. It is optional, but if not provided, Archefusion cannot match your routing rules and will fall back to the default provider order. Example: Card, Transfer example: CARD customerCountry: type: string example: NGA. responses: '200': description: Success headers: Access-Control-Allow-Origin: schema: type: string example: '*' Content-Length: schema: type: integer example: 3124 Date: schema: type: string example: Thu, 18 Jun 2026 10:26:44 GMT Etag: schema: type: string example: W/"c34-MPuEEW1tKUugRH/TdZLb4KM5d48" X-Archefusion-Service: schema: type: string example: api-gateway X-Powered-By: schema: type: string example: Express content: application/json: schema: type: object properties: status: type: boolean example: true statusCode: type: integer example: 200 message: type: string example: Payment initiated data: type: object properties: paymentId: type: string description: >- The unique Archefusion payment ID for this transaction. example: afb955ff-c4ea-495b-bf36-0d83391751bb merchantOrderId: type: string description: The unique order ID you provided in the request. example: order-1781778397 status: type: string description: >- The payment status. Returns PENDING immediately after initiation. example: PENDING executionStatus: type: string description: The internal processing status of the payment. example: processing currency: type: string example: NGN amount: type: integer description: The payment amount in the main currency unit. example: 1000 recommendedGateway: type: object description: The gateway Archefusion routed this payment to. properties: name: type: string description: The name of the recommended gateway. example: paystack session: type: object description: >- The gateway session details, including the checkout URL to redirect your customer to. properties: raw: type: object description: The raw response returned by the gateway. properties: reference: type: string example: afb955ff-c4ea-495b-bf36-0d83391751bb access_code: type: string example: 5a1izuu4blzixzw authorization_url: type: string description: >- The checkout URL to redirect your customer to complete payment. example: >- https://checkout.paystack.com/5a1izuu4blzixzw gateway: type: string example: paystack reference: type: string example: afb955ff-c4ea-495b-bf36-0d83391751bb accessCode: type: string example: 5a1izuu4blzixzw redirectUrl: type: string description: >- The URL to redirect your customer to complete payment. example: https://checkout.paystack.com/5a1izuu4blzixzw metadata: type: object properties: mode: type: string example: test paymentId: type: string example: afb955ff-c4ea-495b-bf36-0d83391751bb merchantId: type: string example: 0c89458a-fb09-48ba-91a9-ab697d76be61 callbackUrl: type: string example: https://www.archefusion.com redirectUrl: type: string example: https://www.archefusion.com merchantOrderId: type: string example: order-1781778397 referencePrefix: type: string example: PS_ fallbackGateways: type: array items: type: object properties: name: type: string example: paystack reason: type: string example: plan-fallback fallbackGateways: type: array description: >- The list of fallback gateways if the recommended gateway fails. items: type: object properties: name: type: string example: paystack reason: type: string example: plan-fallback routing: type: object description: The routing decision details for this payment. properties: version: type: integer example: 2 decidedAt: type: string format: date-time example: '2026-06-18T10:26:41.248Z' rationale: type: string description: >- A human-readable explanation of why this gateway was selected. example: >- Matched smart routing rule "New rule" (priority=1). rationaleCode: type: string example: smart_routing_rule contextKey: type: string example: NGN|CARD|0-5000 overrides: type: array items: type: object reasons: type: array items: type: object properties: code: type: string example: smart_routing_rule title: type: string example: Merchant routing rule matched message: type: string example: >- A smart routing rule matched this transaction context, so the provider order follows the merchant-configured precedence (subject to policy and health overrides). category: type: string example: rule severity: type: string example: info candidates: type: array items: type: object properties: index: type: integer example: 0 eligible: type: boolean example: true provider: type: string example: paystack subproviderId: type: string example: PAYSTACK_NGN_CARD_0_5000 ineligibleReason: type: string nullable: true example: null recommended: type: object properties: index: type: integer example: 0 provider: type: string example: paystack subproviderId: type: string example: PAYSTACK_NGN_CARD_0_5000 createdAt: type: string format: date-time example: '2026-06-18T10:26:41.271Z' updatedAt: type: string format: date-time example: '2026-06-18T10:26:44.177Z' '400': description: Bad Request headers: Access-Control-Allow-Origin: schema: type: string example: '*' Content-Length: schema: type: integer example: 154 Date: schema: type: string example: Tue, 26 May 2026 07:57:38 GMT Etag: schema: type: string example: W/"9a-AuyP7MA2p0vkOiGlh3P466tvmgc" X-Archefusion-Service: schema: type: string example: api-gateway X-Powered-By: schema: type: string example: Express content: application/json: schema: type: object properties: success: type: boolean example: false statusCode: type: integer example: 400 message: type: string example: Bad Request Exception data: type: object properties: errors: type: array description: >- A list of validation errors describing what went wrong. items: type: string example: - >- amount must be a number conforming to the specified constraints '401': description: Unauthorized headers: Access-Control-Allow-Origin: schema: type: string example: '*' Content-Length: schema: type: integer example: 69 Date: schema: type: string example: Thu, 18 Jun 2026 10:33:50 GMT Etag: schema: type: string example: W/"45-OlR1TLyWOFH5HAqsXK1MjJ6AYqA" X-Archefusion-Service: schema: type: string example: api-gateway X-Powered-By: schema: type: string example: Express content: application/json: schema: type: object properties: success: type: boolean example: false statusCode: type: integer example: 401 message: type: string example: Invalid API key data: nullable: true example: null security: - BearerAuth: [] components: securitySchemes: BearerAuth: type: http scheme: bearer ````