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-70-0o8hh-ojy78j0e-8i903-pl679-e07",
"amount": 200,
"currency": "NGN",
"customer": {
"email": "[email protected]",
"id": "cust_123",
"phone": "070780934789"
},
"metadata": {
"cartId": "cart_127"
},
"redirectUrl": "https://merchant.example.com/payment/callback",
"paymentMethod": "transfer",
"customerCountry": "NGA"
}
'import requests
url = "https://dev.api-gateway.archefusion.com/v1/payments/initiate"
payload = {
"merchantOrderId": "order-70-0o8hh-ojy78j0e-8i903-pl679-e07",
"amount": 200,
"currency": "NGN",
"customer": {
"email": "[email protected]",
"id": "cust_123",
"phone": "070780934789"
},
"metadata": { "cartId": "cart_127" },
"redirectUrl": "https://merchant.example.com/payment/callback",
"paymentMethod": "transfer",
"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-70-0o8hh-ojy78j0e-8i903-pl679-e07',
amount: 200,
currency: 'NGN',
customer: {email: '[email protected]', id: 'cust_123', phone: '070780934789'},
metadata: {cartId: 'cart_127'},
redirectUrl: 'https://merchant.example.com/payment/callback',
paymentMethod: 'transfer',
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-70-0o8hh-ojy78j0e-8i903-pl679-e07',
'amount' => 200,
'currency' => 'NGN',
'customer' => [
'email' => '[email protected]',
'id' => 'cust_123',
'phone' => '070780934789'
],
'metadata' => [
'cartId' => 'cart_127'
],
'redirectUrl' => 'https://merchant.example.com/payment/callback',
'paymentMethod' => 'transfer',
'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-70-0o8hh-ojy78j0e-8i903-pl679-e07\",\n \"amount\": 200,\n \"currency\": \"NGN\",\n \"customer\": {\n \"email\": \"[email protected]\",\n \"id\": \"cust_123\",\n \"phone\": \"070780934789\"\n },\n \"metadata\": {\n \"cartId\": \"cart_127\"\n },\n \"redirectUrl\": \"https://merchant.example.com/payment/callback\",\n \"paymentMethod\": \"transfer\",\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-70-0o8hh-ojy78j0e-8i903-pl679-e07\",\n \"amount\": 200,\n \"currency\": \"NGN\",\n \"customer\": {\n \"email\": \"[email protected]\",\n \"id\": \"cust_123\",\n \"phone\": \"070780934789\"\n },\n \"metadata\": {\n \"cartId\": \"cart_127\"\n },\n \"redirectUrl\": \"https://merchant.example.com/payment/callback\",\n \"paymentMethod\": \"transfer\",\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-70-0o8hh-ojy78j0e-8i903-pl679-e07\",\n \"amount\": 200,\n \"currency\": \"NGN\",\n \"customer\": {\n \"email\": \"[email protected]\",\n \"id\": \"cust_123\",\n \"phone\": \"070780934789\"\n },\n \"metadata\": {\n \"cartId\": \"cart_127\"\n },\n \"redirectUrl\": \"https://merchant.example.com/payment/callback\",\n \"paymentMethod\": \"transfer\",\n \"customerCountry\": \"NGA\"\n}"
response = http.request(request)
puts response.read_body{
"status": true,
"statusCode": 200,
"message": "Payment initiated",
"data": {
"paymentId": "668aca23-9ed2-4f10-a985-2636c5624a0b",
"merchantOrderId": "order-70-0o8hh-ojy78j0e-8i903-pl679-e07",
"status": "PENDING",
"executionStatus": "processing",
"currency": "NGN",
"amount": 200,
"recommendedGateway": {
"name": "paystack",
"session": {
"raw": {
"reference": "668aca23-9ed2-4f10-a985-2636c5624a0b",
"access_code": "8t7sxqvgn023yc5",
"authorization_url": "https://checkout.paystack.com/8t7sxqvgn023yc5"
},
"gateway": "paystack",
"reference": "668aca23-9ed2-4f10-a985-2636c5624a0b",
"accessCode": "8t7sxqvgn023yc5",
"redirectUrl": "https://checkout.paystack.com/8t7sxqvgn023yc5",
"metadata": {
"mode": "test",
"paymentId": "668aca23-9ed2-4f10-a985-2636c5624a0b",
"merchantId": "bd9e885e-8b38-43ef-be51-8420ac6a926e",
"callbackUrl": "https://app.archefusion.com/",
"redirectUrl": "https://app.archefusion.com/",
"merchantOrderId": "order-70-0o8hh-ojy78j0e-8i903-pl679-e07",
"referencePrefix": "UBER_ARCHE_",
"fallbackGateways": [
{
"name": "flutterwave",
"reason": "plan-fallback"
}
]
}
}
},
"fallbackGateways": [
{
"name": "flutterwave",
"reason": "plan-fallback"
}
],
"routingMode": "smart",
"requestedGateway": null,
"smartRoutingBypassed": false,
"routing": {
"version": 2,
"decidedAt": "2026-07-23T10:29:35.942Z",
"rationale": "Matched smart routing rule \"Low Bank Transfer Routing\" (priority=1).",
"rationaleCode": "smart_routing_rule",
"contextKey": "NGN|TRANSFER|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_TRANSFER_0_5000",
"ineligibleReason": null
}
],
"recommended": {
"index": 0,
"provider": "paystack",
"subproviderId": "PAYSTACK_NGN_TRANSFER_0_5000"
}
},
"createdAt": "2026-07-23T10:29:35.944Z",
"updatedAt": "2026-07-23T10:29:37.153Z"
}
}{
"success": false,
"statusCode": 400,
"message": "Bad Request Exception",
"data": {
"errors": [
"customer.email must be an email"
]
}
}{
"success": false,
"statusCode": 401,
"message": "Invalid API key",
"data": null
}Payments
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.
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-70-0o8hh-ojy78j0e-8i903-pl679-e07",
"amount": 200,
"currency": "NGN",
"customer": {
"email": "[email protected]",
"id": "cust_123",
"phone": "070780934789"
},
"metadata": {
"cartId": "cart_127"
},
"redirectUrl": "https://merchant.example.com/payment/callback",
"paymentMethod": "transfer",
"customerCountry": "NGA"
}
'import requests
url = "https://dev.api-gateway.archefusion.com/v1/payments/initiate"
payload = {
"merchantOrderId": "order-70-0o8hh-ojy78j0e-8i903-pl679-e07",
"amount": 200,
"currency": "NGN",
"customer": {
"email": "[email protected]",
"id": "cust_123",
"phone": "070780934789"
},
"metadata": { "cartId": "cart_127" },
"redirectUrl": "https://merchant.example.com/payment/callback",
"paymentMethod": "transfer",
"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-70-0o8hh-ojy78j0e-8i903-pl679-e07',
amount: 200,
currency: 'NGN',
customer: {email: '[email protected]', id: 'cust_123', phone: '070780934789'},
metadata: {cartId: 'cart_127'},
redirectUrl: 'https://merchant.example.com/payment/callback',
paymentMethod: 'transfer',
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-70-0o8hh-ojy78j0e-8i903-pl679-e07',
'amount' => 200,
'currency' => 'NGN',
'customer' => [
'email' => '[email protected]',
'id' => 'cust_123',
'phone' => '070780934789'
],
'metadata' => [
'cartId' => 'cart_127'
],
'redirectUrl' => 'https://merchant.example.com/payment/callback',
'paymentMethod' => 'transfer',
'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-70-0o8hh-ojy78j0e-8i903-pl679-e07\",\n \"amount\": 200,\n \"currency\": \"NGN\",\n \"customer\": {\n \"email\": \"[email protected]\",\n \"id\": \"cust_123\",\n \"phone\": \"070780934789\"\n },\n \"metadata\": {\n \"cartId\": \"cart_127\"\n },\n \"redirectUrl\": \"https://merchant.example.com/payment/callback\",\n \"paymentMethod\": \"transfer\",\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-70-0o8hh-ojy78j0e-8i903-pl679-e07\",\n \"amount\": 200,\n \"currency\": \"NGN\",\n \"customer\": {\n \"email\": \"[email protected]\",\n \"id\": \"cust_123\",\n \"phone\": \"070780934789\"\n },\n \"metadata\": {\n \"cartId\": \"cart_127\"\n },\n \"redirectUrl\": \"https://merchant.example.com/payment/callback\",\n \"paymentMethod\": \"transfer\",\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-70-0o8hh-ojy78j0e-8i903-pl679-e07\",\n \"amount\": 200,\n \"currency\": \"NGN\",\n \"customer\": {\n \"email\": \"[email protected]\",\n \"id\": \"cust_123\",\n \"phone\": \"070780934789\"\n },\n \"metadata\": {\n \"cartId\": \"cart_127\"\n },\n \"redirectUrl\": \"https://merchant.example.com/payment/callback\",\n \"paymentMethod\": \"transfer\",\n \"customerCountry\": \"NGA\"\n}"
response = http.request(request)
puts response.read_body{
"status": true,
"statusCode": 200,
"message": "Payment initiated",
"data": {
"paymentId": "668aca23-9ed2-4f10-a985-2636c5624a0b",
"merchantOrderId": "order-70-0o8hh-ojy78j0e-8i903-pl679-e07",
"status": "PENDING",
"executionStatus": "processing",
"currency": "NGN",
"amount": 200,
"recommendedGateway": {
"name": "paystack",
"session": {
"raw": {
"reference": "668aca23-9ed2-4f10-a985-2636c5624a0b",
"access_code": "8t7sxqvgn023yc5",
"authorization_url": "https://checkout.paystack.com/8t7sxqvgn023yc5"
},
"gateway": "paystack",
"reference": "668aca23-9ed2-4f10-a985-2636c5624a0b",
"accessCode": "8t7sxqvgn023yc5",
"redirectUrl": "https://checkout.paystack.com/8t7sxqvgn023yc5",
"metadata": {
"mode": "test",
"paymentId": "668aca23-9ed2-4f10-a985-2636c5624a0b",
"merchantId": "bd9e885e-8b38-43ef-be51-8420ac6a926e",
"callbackUrl": "https://app.archefusion.com/",
"redirectUrl": "https://app.archefusion.com/",
"merchantOrderId": "order-70-0o8hh-ojy78j0e-8i903-pl679-e07",
"referencePrefix": "UBER_ARCHE_",
"fallbackGateways": [
{
"name": "flutterwave",
"reason": "plan-fallback"
}
]
}
}
},
"fallbackGateways": [
{
"name": "flutterwave",
"reason": "plan-fallback"
}
],
"routingMode": "smart",
"requestedGateway": null,
"smartRoutingBypassed": false,
"routing": {
"version": 2,
"decidedAt": "2026-07-23T10:29:35.942Z",
"rationale": "Matched smart routing rule \"Low Bank Transfer Routing\" (priority=1).",
"rationaleCode": "smart_routing_rule",
"contextKey": "NGN|TRANSFER|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_TRANSFER_0_5000",
"ineligibleReason": null
}
],
"recommended": {
"index": 0,
"provider": "paystack",
"subproviderId": "PAYSTACK_NGN_TRANSFER_0_5000"
}
},
"createdAt": "2026-07-23T10:29:35.944Z",
"updatedAt": "2026-07-23T10:29:37.153Z"
}
}{
"success": false,
"statusCode": 400,
"message": "Bad Request Exception",
"data": {
"errors": [
"customer.email must be an email"
]
}
}{
"success": false,
"statusCode": 401,
"message": "Invalid API key",
"data": null
}Reading the response
The
recommendedGateway.session object contains the main checkout and payment details. See the payment session page to learn more about this field.Fallback behavior
If the first configured gateway in your smart routing rule fails, Archefusion routes the payment to your available fallback gateway. The response for a successful fallback is the same as when no fallback was applied. If all gateways fail, including the first configured gateway and the fallback gateways, the payment fails with
status: FAILED. See the failed payment section to learn more.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
A unique order ID generated by your system to track and reconcile the payment. It must be unique for every payment request. This is your own reference, not the gateway's transaction reference. Visit the payment identifiers page to learn more about IDs in Archefusion.
Example:
"order-70-0o8hh-ojy78j0e-8i903-pl679-e07"
This represents the payment amount in the main currency unit. For example, pass 1000 to charge ₦1,000 NGN.
Example:
200
This represents the payment currency in ISO 4217 format. Currently supported: NGN.
Example:
"NGN"
This represents the customer's details.
Show child attributes
Show child attributes
This represents additional details about your product or service.
Show child attributes
Show child attributes
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"
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:
"transfer"
Example:
"NGA"
Was this page helpful?