Skip to main content
POST
/
v1
/
payments
/
initiate
Initiate payment
curl --request POST \
  --url https://dev.api-gateway.archefusion.com/v1/payments/initiate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "merchantOrderId": "order-1e57-6y72-8u67",
  "amount": 1000,
  "currency": "NGN",
  "customer": {
    "id": "cust_123",
    "email": "[email protected]",
    "phone": 2349072305772
  },
  "metadata": {
    "cartId": "cart_123"
  },
  "redirectUrl": "https://merchant.example.com/payment/callback",
  "paymentMethod": "CARD",
  "customerCountry": "NGA."
}
'
import requests

url = "https://dev.api-gateway.archefusion.com/v1/payments/initiate"

payload = {
    "merchantOrderId": "order-1e57-6y72-8u67",
    "amount": 1000,
    "currency": "NGN",
    "customer": {
        "id": "cust_123",
        "email": "[email protected]",
        "phone": 2349072305772
    },
    "metadata": { "cartId": "cart_123" },
    "redirectUrl": "https://merchant.example.com/payment/callback",
    "paymentMethod": "CARD",
    "customerCountry": "NGA."
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    merchantOrderId: 'order-1e57-6y72-8u67',
    amount: 1000,
    currency: 'NGN',
    customer: {id: 'cust_123', email: '[email protected]', phone: 2349072305772},
    metadata: {cartId: 'cart_123'},
    redirectUrl: 'https://merchant.example.com/payment/callback',
    paymentMethod: 'CARD',
    customerCountry: 'NGA.'
  })
};

fetch('https://dev.api-gateway.archefusion.com/v1/payments/initiate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://dev.api-gateway.archefusion.com/v1/payments/initiate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'merchantOrderId' => 'order-1e57-6y72-8u67',
    'amount' => 1000,
    'currency' => 'NGN',
    'customer' => [
        'id' => 'cust_123',
        'email' => '[email protected]',
        'phone' => 2349072305772
    ],
    'metadata' => [
        'cartId' => 'cart_123'
    ],
    'redirectUrl' => 'https://merchant.example.com/payment/callback',
    'paymentMethod' => 'CARD',
    'customerCountry' => 'NGA.'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://dev.api-gateway.archefusion.com/v1/payments/initiate"

	payload := strings.NewReader("{\n  \"merchantOrderId\": \"order-1e57-6y72-8u67\",\n  \"amount\": 1000,\n  \"currency\": \"NGN\",\n  \"customer\": {\n    \"id\": \"cust_123\",\n    \"email\": \"[email protected]\",\n    \"phone\": 2349072305772\n  },\n  \"metadata\": {\n    \"cartId\": \"cart_123\"\n  },\n  \"redirectUrl\": \"https://merchant.example.com/payment/callback\",\n  \"paymentMethod\": \"CARD\",\n  \"customerCountry\": \"NGA.\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://dev.api-gateway.archefusion.com/v1/payments/initiate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"merchantOrderId\": \"order-1e57-6y72-8u67\",\n  \"amount\": 1000,\n  \"currency\": \"NGN\",\n  \"customer\": {\n    \"id\": \"cust_123\",\n    \"email\": \"[email protected]\",\n    \"phone\": 2349072305772\n  },\n  \"metadata\": {\n    \"cartId\": \"cart_123\"\n  },\n  \"redirectUrl\": \"https://merchant.example.com/payment/callback\",\n  \"paymentMethod\": \"CARD\",\n  \"customerCountry\": \"NGA.\"\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://dev.api-gateway.archefusion.com/v1/payments/initiate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"merchantOrderId\": \"order-1e57-6y72-8u67\",\n  \"amount\": 1000,\n  \"currency\": \"NGN\",\n  \"customer\": {\n    \"id\": \"cust_123\",\n    \"email\": \"[email protected]\",\n    \"phone\": 2349072305772\n  },\n  \"metadata\": {\n    \"cartId\": \"cart_123\"\n  },\n  \"redirectUrl\": \"https://merchant.example.com/payment/callback\",\n  \"paymentMethod\": \"CARD\",\n  \"customerCountry\": \"NGA.\"\n}"

response = http.request(request)
puts response.read_body
{
  "status": true,
  "statusCode": 200,
  "message": "Payment initiated",
  "data": {
    "paymentId": "afb955ff-c4ea-495b-bf36-0d83391751bb",
    "merchantOrderId": "order-1781778397",
    "status": "PENDING",
    "executionStatus": "processing",
    "currency": "NGN",
    "amount": 1000,
    "recommendedGateway": {
      "name": "paystack",
      "session": {
        "raw": {
          "reference": "afb955ff-c4ea-495b-bf36-0d83391751bb",
          "access_code": "5a1izuu4blzixzw",
          "authorization_url": "https://checkout.paystack.com/5a1izuu4blzixzw"
        },
        "gateway": "paystack",
        "reference": "afb955ff-c4ea-495b-bf36-0d83391751bb",
        "accessCode": "5a1izuu4blzixzw",
        "redirectUrl": "https://checkout.paystack.com/5a1izuu4blzixzw",
        "metadata": {
          "mode": "test",
          "paymentId": "afb955ff-c4ea-495b-bf36-0d83391751bb",
          "merchantId": "0c89458a-fb09-48ba-91a9-ab697d76be61",
          "callbackUrl": "https://www.archefusion.com",
          "redirectUrl": "https://www.archefusion.com",
          "merchantOrderId": "order-1781778397",
          "referencePrefix": "PS_",
          "fallbackGateways": [
            {
              "name": "paystack",
              "reason": "plan-fallback"
            }
          ]
        }
      }
    },
    "fallbackGateways": [
      {
        "name": "paystack",
        "reason": "plan-fallback"
      }
    ],
    "routing": {
      "version": 2,
      "decidedAt": "2026-06-18T10:26:41.248Z",
      "rationale": "Matched smart routing rule \"New rule\" (priority=1).",
      "rationaleCode": "smart_routing_rule",
      "contextKey": "NGN|CARD|0-5000",
      "overrides": [
        {}
      ],
      "reasons": [
        {
          "code": "smart_routing_rule",
          "title": "Merchant routing rule matched",
          "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"
        }
      ],
      "candidates": [
        {
          "index": 0,
          "eligible": true,
          "provider": "paystack",
          "subproviderId": "PAYSTACK_NGN_CARD_0_5000",
          "ineligibleReason": null
        }
      ],
      "recommended": {
        "index": 0,
        "provider": "paystack",
        "subproviderId": "PAYSTACK_NGN_CARD_0_5000"
      }
    },
    "createdAt": "2026-06-18T10:26:41.271Z",
    "updatedAt": "2026-06-18T10:26:44.177Z"
  }
}
{
  "success": false,
  "statusCode": 400,
  "message": "Bad Request Exception",
  "data": {
    "errors": [
      "amount must be a number conforming to the specified constraints"
    ]
  }
}
{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API key",
  "data": null
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
merchantOrderId
string
required

This represents a unique order ID generated by your system. It must be unique for every payment request.

Example:

"order-1e57-6y72-8u67"

​
amount
integer
required

This represents the payment amount in the main currency unit. For example, pass 1000 to charge ₦1,000 NGN.

Example:

1000

​
currency
string
required

This represents the payment currency in ISO 4217 format. Currently supported: NGN.

Example:

"NGN"

​
customer
object

This represents the customer's details.

​
metadata
object

This represents additional details about your product or service.

​
redirectUrl
string

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
string

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
string
Example:

"NGA."

Response

Success

​
status
boolean
Example:

true

​
statusCode
integer
Example:

200

​
message
string
Example:

"Payment initiated"

​
data
object