> ## 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.

# Accept payments

> Learn how to initiate a payment via the Archefusion API, redirect customers to the gateway checkout page, and verify the transaction after payment

<Note>
  This section assumes you have connected your [payment gateways](https://docs.archefusion.com/pages/payment-gateway), set your [smart routing rules](https://docs.archefusion.com/pages/smart-routing), and configured your [webhook](https://docs.archefusion.com/pages/webhook-setup) in Archefusion.
</Note>

Accepting payments with Archefusion means every transaction is automatically routed through the best available gateway to prevent payment failure. Archefusion evaluates your smart routing rules and live provider health to determine the most suitable gateway to process each transaction.

## Here is how it works:

<iframe width="100%" height="400" src="https://www.youtube.com/embed/QXc6d8UXo5A" title="Archefusion payment flow" frameBorder="0" allowFullScreen />

→ Customer initiates a payment on your platform.

→ Archefusion checks your configured smart routing rule and live provider health to determine the best gateway to process the payment.

For example, if Paystack is configured as the first payment gateway to handle card payments between ₦100 and ₦100,000 but is currently unavailable, Archefusion automatically skips it and selects Flutterwave (your fallback gateway) instead.

→ You send the user to the selected gateway's checkout page. For most gateways this means redirecting to the session's `redirectUrl`; see [payment session](https://docs.archefusion.com/pages/developer-resources/payment-session) for how to handle checkout for each gateway.

→ Customer completes payment and is redirected back to your platform via the redirect URL.

→ Archefusion sends a notification with the payment outcome to your server.

<Note>
  If a payment fails on the checkout page, for example, due to insufficient funds or a declined card, it is marked as failed. This is outside Archefusion's control.
</Note>

## How to accept payments on Archefusion

### Step 1: Collect customers’ payment information.

To initiate a payment, you need to pass information such as email, amount, payment method, currency, phone number, etc. Amount is a required field. You can also pass any additional information in the `metadata` object field.

The customer data can be retrieved from your database, session, or from an HTML form in the example below:

```HTML theme={null}
  <form action="" id="payments">
    <label for="email">Email:
        <input type="email" id="email">
    </label>
    <label for="quantity">Quantity:
        <input type="number" id="quantity">
    </label>
    <label for="method">Payment method:
        <select id="method"> 
            <option value="CARD">Card</option>
            <option value="TRANSFER">Transfer</option>
        </select>
     </label>
    <button type="submit" id="btn">Pay now</button>
  </form>
```

### Step 2: Initiate payment.

When a customer clicks the pay button, your server initiates a payment by sending a POST request to the Archefusion [`initiate payment`](https://docs.archefusion.com/pages/api-reference/initiate-payment) endpoint with your customer's payment details.

<Accordion title="View code example">
  ```javascript theme={null}
  import 'dotenv/config'
  import express from 'express'
  import axios from 'axios'
  import {v4 as uuidv4} from 'uuid'
  const app = express ();
  app.use(express.json())

  app.post('/payments', async(req, res)=>{
      const {email,phone, paymentMethod} = req.body
      const url = 'https://dev.api-gateway.archefusion.com/v1/payments/initiate'

      const secretKey = process.env.SECRETKEY
      const currency = "NGN"
      const redirectUrl = "https://merchant.com/payment/callback";
      const amount = 1000 ;
      const customerCountry = "NGA"
      const payload = {
          "merchantOrderId": `order-${uuidv4()}`,
          "amount": amount,
          "currency": currency,
          "customer":{
              "email": email,
              "phone": phone
          },
          "redirectUrl": redirectUrl,
          "paymentMethod": paymentMethod,
          "customerCountry": customerCountry
      }
      const config = {
          headers:{
              'Authorization': `Bearer ${secretKey}`,
              'Content-Type': 'application/json'
          }
      }
      try {
          const response = await axios.post(url, payload, config)
          const checkout = response.data.data.recommendedGateway.session.redirectUrl
          return res.status(200).json({checkout})
          

      } catch (error) {
          return res.status(500).json({msg:"An error occurred!"})
      }
  })

  const PORT = 3000;
  app.listen(PORT, ()=>{
      console.log('server is running...');
      
  })

  ```

  This example works for redirect-based gateways (E.g., Paystack, Flutterwave, Korapay, Monnify), where you redirect the customer to session.redirectUrl. Interswitch is the exception; it requires a form submission instead of a redirect. See [payment session](https://docs.archefusion.com/pages/developer-resources/payment-session).
</Accordion>

<Accordion title="View response">
  ```json theme={null}
  {
      "status": true,
      "statusCode": 200,
      "message": "Payment initiated",
      "data": {
          "paymentId": "19127846-c7b8-4eb2-a617-81562de606e4",
          "merchantOrderId": "order-1781540906",
          "status": "PENDING",
          "executionStatus": "processing",
          "currency": "NGN",
          "amount": 1000,
          "recommendedGateway": {
              "name": "paystack",
              "session": {
                  "raw": {
                      "reference": "19127846-c7b8-4eb2-a617-81562de606e4",
                      "access_code": "m5i9a95714ufcdr",
                      "authorization_url": "https://checkout.paystack.com/m5i9a95714ufcdr"
                  },
                  "gateway": "paystack",
                  "metadata": {
                      "mode": "test",
                      "paymentId": "19127846-c7b8-4eb2-a617-81562de606e4",
                      "merchantId": "0c89458a-fb09-48ba-91a9-ab697d76be61",
                      "callbackUrl": "https://www.archefusion.com",
                      "redirectUrl": "https://www.archefusion.com",
                      "merchantOrderId": "order-1781540906",
                      "referencePrefix": "PS_",
                      "fallbackGateways": [
                          {
                              "name": "flutterwave",
                              "reason": "plan-fallback"
                          }
                      ]
                  },
                  "reference": "19127846-c7b8-4eb2-a617-81562de606e4",
                  "accessCode": "m5i9a95714ufcdr",
                  "redirectUrl": "https://checkout.paystack.com/m5i9a95714ufcdr"
              }
          },
          "fallbackGateways": [
              {
                  "name": "flutterwave",
                  "reason": "plan-fallback"
              }
          ],
          "routingMode": "smart",
          "requestedGateway": null,
          "smartRoutingBypassed": false,
          "routing": {
              "reasons": [
                  {
                      "code": "smart_routing_rule",
                      "title": "Merchant routing rule matched",
                      "details": {
                          "priority": 1,
                          "ruleName": "New rule",
                          "appliedProviderOrder": ["paystack", "flutterwave"],
                          "aiOptimizationEnabled": true,
                          "healthOverrideStrategy": "after_first_attempt",
                          "configuredProviderOrder": ["paystack", "flutterwave"]
                      },
                      "message": "A smart routing rule matched this transaction context, so the provider order follows the merchant-configured precedence (subject to policy and health overrides).",
                      "category": "rule",
                      "severity": "info"
                  }
              ],
              "version": 2,
              "decidedAt": "2026-06-15T16:28:29.069Z",
              "overrides": [],
              "rationale": "Matched smart routing rule \"New rule\" (priority=1).",
              "candidates": [
                  {
                      "index": 0,
                      "reasons": [
                          {
                              "code": "eligible",
                              "title": "Eligible",
                              "details": {
                                  "provider": "paystack",
                                  "subproviderId": "PAYSTACK_NGN_CARD_0_5000"
                              },
                              "message": "This provider slice is eligible for the transaction context.",
                              "category": "capability",
                              "severity": "info"
                          }
                      ],
                      "eligible": true,
                      "provider": "paystack",
                      "subproviderId": "PAYSTACK_NGN_CARD_0_5000",
                      "ineligibleReason": null
                  },
                  {
                      "index": 1,
                      "reasons": [
                          {
                              "code": "eligible",
                              "title": "Eligible",
                              "details": {
                                  "provider": "flutterwave",
                                  "subproviderId": "FLUTTERWAVE_NGN_CARD_0_5000"
                              },
                              "message": "This provider slice is eligible for the transaction context.",
                              "category": "capability",
                              "severity": "info"
                          }
                      ],
                      "eligible": true,
                      "provider": "flutterwave",
                      "subproviderId": "FLUTTERWAVE_NGN_CARD_0_5000",
                      "ineligibleReason": null
                  }
              ],
              "contextKey": "NGN|CARD|0-5000",
              "recommended": {
                  "index": 0,
                  "reasons": [
                      {
                          "code": "first_eligible_candidate",
                          "title": "First eligible candidate",
                          "details": {
                              "selectedIndex": 0
                          },
                          "message": "The recommended provider is the first eligible candidate in the routing plan (position 1).",
                          "category": "rule",
                          "severity": "info"
                      }
                  ],
                  "provider": "paystack",
                  "subproviderId": "PAYSTACK_NGN_CARD_0_5000"
              },
              "routingMode": "smart",
              "rationaleCode": "smart_routing_rule",
              "rationaleMeta": {
                  "priority": 1,
                  "ruleName": "New rule",
                  "appliedProviderOrder": ["paystack", "flutterwave"],
                  "aiOptimizationEnabled": true,
                  "healthOverrideStrategy": "after_first_attempt",
                  "configuredProviderOrder": ["paystack", "flutterwave"]
              },
              "requestedGateway": null,
              "smartRoutingBypassed": false
          },
          "createdAt": "2026-06-15T16:28:29.073Z",
          "updatedAt": "2026-06-15T16:28:30.506Z"
      }
  }
  ```
</Accordion>

**Important Note:**

1. Payment method is an optional field; however, if not provided, Archefusion cannot match your smart routing rules and will fall back to a [default provider order](https://docs.archefusion.com/pages/glossary#default-provider-order).

2. If you do not provide a `redirectUrl`, customers will be redirected to the one set on your dashboard. Setting it in the code allows you to be flexible if you need to.

3. If you do not set a redirect URL on the dashboard or on the code, customers will not be redirected back to your site after payment.

4. Ensure `merchantOrderId` is unique for every payment request. In the example above, we use UUID to generate a unique order ID automatically.

## Verify transaction

Once the transaction is successful, the customer is redirected back to the redirectUrl you set. However, it is very important that you confirm the status of the transaction before you deliver value.

Archefusion provides two ways to do this:

* **Webhook notifications (recommended)**: Archefusion sends a `payment.succeeded` or `payment.failed` event to your webhook URL automatically when a payment outcome is determined. This is the preferred approach as it does not require additional API calls from your server.

* **Verify endpoint**: You can also call the verify endpoint to check the transaction status manually.

Visit the [verify payments](https://docs.archefusion.com/pages/api-reference/verify-payment) and [webhook notification](https://docs.archefusion.com/pages/handle-webhook) page to learn more about verifying a transaction.