Initiate cross-border collection
curl --request POST \
--url https://api.nexapay.ng/api/v1/business/cross-border/collections/initiate \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--header 'x-business-id: <api-key>' \
--data '
{
"businessId": "<string>",
"country": "UG",
"currency": "UGX",
"amount": 20000,
"paymentMethod": "MTN",
"customer": {
"name": "Jon Snow",
"email": "ray.jon@mail.com",
"phone": "+256775379021"
},
"reference": "<string>",
"sourceCurrency": "UGX",
"targetCurrency": "NGN",
"merchantReference": "ORDER-UG-001",
"description": "Uganda order payment"
}
'import requests
url = "https://api.nexapay.ng/api/v1/business/cross-border/collections/initiate"
payload = {
"businessId": "<string>",
"country": "UG",
"currency": "UGX",
"amount": 20000,
"paymentMethod": "MTN",
"customer": {
"name": "Jon Snow",
"email": "ray.jon@mail.com",
"phone": "+256775379021"
},
"reference": "<string>",
"sourceCurrency": "UGX",
"targetCurrency": "NGN",
"merchantReference": "ORDER-UG-001",
"description": "Uganda order payment"
}
headers = {
"x-api-key": "<api-key>",
"x-business-id": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-api-key': '<api-key>',
'x-business-id': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
businessId: '<string>',
country: 'UG',
currency: 'UGX',
amount: 20000,
paymentMethod: 'MTN',
customer: {name: 'Jon Snow', email: 'ray.jon@mail.com', phone: '+256775379021'},
reference: '<string>',
sourceCurrency: 'UGX',
targetCurrency: 'NGN',
merchantReference: 'ORDER-UG-001',
description: 'Uganda order payment'
})
};
fetch('https://api.nexapay.ng/api/v1/business/cross-border/collections/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://api.nexapay.ng/api/v1/business/cross-border/collections/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([
'businessId' => '<string>',
'country' => 'UG',
'currency' => 'UGX',
'amount' => 20000,
'paymentMethod' => 'MTN',
'customer' => [
'name' => 'Jon Snow',
'email' => 'ray.jon@mail.com',
'phone' => '+256775379021'
],
'reference' => '<string>',
'sourceCurrency' => 'UGX',
'targetCurrency' => 'NGN',
'merchantReference' => 'ORDER-UG-001',
'description' => 'Uganda order payment'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>",
"x-business-id: <api-key>"
],
]);
$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://api.nexapay.ng/api/v1/business/cross-border/collections/initiate"
payload := strings.NewReader("{\n \"businessId\": \"<string>\",\n \"country\": \"UG\",\n \"currency\": \"UGX\",\n \"amount\": 20000,\n \"paymentMethod\": \"MTN\",\n \"customer\": {\n \"name\": \"Jon Snow\",\n \"email\": \"ray.jon@mail.com\",\n \"phone\": \"+256775379021\"\n },\n \"reference\": \"<string>\",\n \"sourceCurrency\": \"UGX\",\n \"targetCurrency\": \"NGN\",\n \"merchantReference\": \"ORDER-UG-001\",\n \"description\": \"Uganda order payment\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("x-business-id", "<api-key>")
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://api.nexapay.ng/api/v1/business/cross-border/collections/initiate")
.header("x-api-key", "<api-key>")
.header("x-business-id", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"businessId\": \"<string>\",\n \"country\": \"UG\",\n \"currency\": \"UGX\",\n \"amount\": 20000,\n \"paymentMethod\": \"MTN\",\n \"customer\": {\n \"name\": \"Jon Snow\",\n \"email\": \"ray.jon@mail.com\",\n \"phone\": \"+256775379021\"\n },\n \"reference\": \"<string>\",\n \"sourceCurrency\": \"UGX\",\n \"targetCurrency\": \"NGN\",\n \"merchantReference\": \"ORDER-UG-001\",\n \"description\": \"Uganda order payment\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nexapay.ng/api/v1/business/cross-border/collections/initiate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["x-business-id"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"businessId\": \"<string>\",\n \"country\": \"UG\",\n \"currency\": \"UGX\",\n \"amount\": 20000,\n \"paymentMethod\": \"MTN\",\n \"customer\": {\n \"name\": \"Jon Snow\",\n \"email\": \"ray.jon@mail.com\",\n \"phone\": \"+256775379021\"\n },\n \"reference\": \"<string>\",\n \"sourceCurrency\": \"UGX\",\n \"targetCurrency\": \"NGN\",\n \"merchantReference\": \"ORDER-UG-001\",\n \"description\": \"Uganda order payment\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"msg": "<string>",
"collection": {
"transactionId": "NexaPay20260903140945570d4ed2170c3",
"reference": "NexaPay20260903140945570d4ed2170c3",
"merchantReference": "ORDER-TEST-001",
"status": "PROCESSING",
"sourceAmount": 20000,
"sourceCurrency": "UGX",
"targetAmount": 7200,
"targetCurrency": "NGN",
"rate": 0.36,
"providerRate": 0.4,
"provider": "brails",
"country": "UG",
"paymentMethod": "MTN",
"createdAt": "2023-11-07T05:31:56Z",
"completedAt": "2023-11-07T05:31:56Z",
"failedAt": "2023-11-07T05:31:56Z",
"failureReason": "<string>"
},
"quote": {
"corridorKey": "UG_UGX_NGN",
"provider": "brails",
"country": "UG",
"sourceCurrency": "UGX",
"targetCurrency": "NGN",
"sourceAmount": 20000,
"providerRate": 0.4,
"merchantRate": 0.36,
"merchantReceives": 7200,
"markupType": "percentage",
"markupValue": 10,
"rateSource": "sellRate",
"creditMode": "instant"
},
"providerResponse": {}
}Cross-Border Collections
Initiate Cross-Border Collection
Starts a cross-border collection. For Kenya, this sends an M-Pesa collection request. For Uganda, this sends an MTN mobile money collection request. NexaPay locks the merchant NGN amount for instant credit after successful provider confirmation.
POST
/
cross-border
/
collections
/
initiate
Initiate cross-border collection
curl --request POST \
--url https://api.nexapay.ng/api/v1/business/cross-border/collections/initiate \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--header 'x-business-id: <api-key>' \
--data '
{
"businessId": "<string>",
"country": "UG",
"currency": "UGX",
"amount": 20000,
"paymentMethod": "MTN",
"customer": {
"name": "Jon Snow",
"email": "ray.jon@mail.com",
"phone": "+256775379021"
},
"reference": "<string>",
"sourceCurrency": "UGX",
"targetCurrency": "NGN",
"merchantReference": "ORDER-UG-001",
"description": "Uganda order payment"
}
'import requests
url = "https://api.nexapay.ng/api/v1/business/cross-border/collections/initiate"
payload = {
"businessId": "<string>",
"country": "UG",
"currency": "UGX",
"amount": 20000,
"paymentMethod": "MTN",
"customer": {
"name": "Jon Snow",
"email": "ray.jon@mail.com",
"phone": "+256775379021"
},
"reference": "<string>",
"sourceCurrency": "UGX",
"targetCurrency": "NGN",
"merchantReference": "ORDER-UG-001",
"description": "Uganda order payment"
}
headers = {
"x-api-key": "<api-key>",
"x-business-id": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-api-key': '<api-key>',
'x-business-id': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
businessId: '<string>',
country: 'UG',
currency: 'UGX',
amount: 20000,
paymentMethod: 'MTN',
customer: {name: 'Jon Snow', email: 'ray.jon@mail.com', phone: '+256775379021'},
reference: '<string>',
sourceCurrency: 'UGX',
targetCurrency: 'NGN',
merchantReference: 'ORDER-UG-001',
description: 'Uganda order payment'
})
};
fetch('https://api.nexapay.ng/api/v1/business/cross-border/collections/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://api.nexapay.ng/api/v1/business/cross-border/collections/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([
'businessId' => '<string>',
'country' => 'UG',
'currency' => 'UGX',
'amount' => 20000,
'paymentMethod' => 'MTN',
'customer' => [
'name' => 'Jon Snow',
'email' => 'ray.jon@mail.com',
'phone' => '+256775379021'
],
'reference' => '<string>',
'sourceCurrency' => 'UGX',
'targetCurrency' => 'NGN',
'merchantReference' => 'ORDER-UG-001',
'description' => 'Uganda order payment'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>",
"x-business-id: <api-key>"
],
]);
$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://api.nexapay.ng/api/v1/business/cross-border/collections/initiate"
payload := strings.NewReader("{\n \"businessId\": \"<string>\",\n \"country\": \"UG\",\n \"currency\": \"UGX\",\n \"amount\": 20000,\n \"paymentMethod\": \"MTN\",\n \"customer\": {\n \"name\": \"Jon Snow\",\n \"email\": \"ray.jon@mail.com\",\n \"phone\": \"+256775379021\"\n },\n \"reference\": \"<string>\",\n \"sourceCurrency\": \"UGX\",\n \"targetCurrency\": \"NGN\",\n \"merchantReference\": \"ORDER-UG-001\",\n \"description\": \"Uganda order payment\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("x-business-id", "<api-key>")
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://api.nexapay.ng/api/v1/business/cross-border/collections/initiate")
.header("x-api-key", "<api-key>")
.header("x-business-id", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"businessId\": \"<string>\",\n \"country\": \"UG\",\n \"currency\": \"UGX\",\n \"amount\": 20000,\n \"paymentMethod\": \"MTN\",\n \"customer\": {\n \"name\": \"Jon Snow\",\n \"email\": \"ray.jon@mail.com\",\n \"phone\": \"+256775379021\"\n },\n \"reference\": \"<string>\",\n \"sourceCurrency\": \"UGX\",\n \"targetCurrency\": \"NGN\",\n \"merchantReference\": \"ORDER-UG-001\",\n \"description\": \"Uganda order payment\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nexapay.ng/api/v1/business/cross-border/collections/initiate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["x-business-id"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"businessId\": \"<string>\",\n \"country\": \"UG\",\n \"currency\": \"UGX\",\n \"amount\": 20000,\n \"paymentMethod\": \"MTN\",\n \"customer\": {\n \"name\": \"Jon Snow\",\n \"email\": \"ray.jon@mail.com\",\n \"phone\": \"+256775379021\"\n },\n \"reference\": \"<string>\",\n \"sourceCurrency\": \"UGX\",\n \"targetCurrency\": \"NGN\",\n \"merchantReference\": \"ORDER-UG-001\",\n \"description\": \"Uganda order payment\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"msg": "<string>",
"collection": {
"transactionId": "NexaPay20260903140945570d4ed2170c3",
"reference": "NexaPay20260903140945570d4ed2170c3",
"merchantReference": "ORDER-TEST-001",
"status": "PROCESSING",
"sourceAmount": 20000,
"sourceCurrency": "UGX",
"targetAmount": 7200,
"targetCurrency": "NGN",
"rate": 0.36,
"providerRate": 0.4,
"provider": "brails",
"country": "UG",
"paymentMethod": "MTN",
"createdAt": "2023-11-07T05:31:56Z",
"completedAt": "2023-11-07T05:31:56Z",
"failedAt": "2023-11-07T05:31:56Z",
"failureReason": "<string>"
},
"quote": {
"corridorKey": "UG_UGX_NGN",
"provider": "brails",
"country": "UG",
"sourceCurrency": "UGX",
"targetCurrency": "NGN",
"sourceAmount": 20000,
"providerRate": 0.4,
"merchantRate": 0.36,
"merchantReceives": 7200,
"markupType": "percentage",
"markupValue": 10,
"rateSource": "sellRate",
"creditMode": "instant"
},
"providerResponse": {}
}Starts a cross-border payment collection request for a supported corridor.
For Kenya, this initiates an M-Pesa collection request to the customer’s phone number. For Uganda, this initiates an MTN mobile money collection request. The merchant is credited in NGN after the provider confirms successful payment.
Notes
- Send customer-facing amounts in normal source-currency units, such as
100for100 KES. - The NGN amount and exchange rate are locked at initiation.
- The initial transaction status is usually
PROCESSING. - On successful provider confirmation, the merchant’s NGN balance is credited instantly and the transaction becomes
COMPLETED. - Use
merchantReferenceto map the collection back to your order, invoice, or checkout session.
Uganda Example
{
"businessId": "69e698368d883f70f4d4ed21",
"country": "UG",
"currency": "UGX",
"amount": 20000,
"paymentMethod": "MTN",
"merchantReference": "ORDER-UG-001",
"description": "Uganda order payment",
"customer": {
"name": "Jon Snow",
"email": "ray.jon@mail.com",
"phone": "+256775379021"
}
}
Authorizations
Merchant API Key (e.g., nexa-prod-... or nexa-test-...)
Merchant Business ID
Headers
Target environment selector (live production vs. simulated sandbox).
Available options:
prod, test Body
application/json
Example:
"UG"
Example:
"UGX"
Example:
20000
Example:
"MTN"
Show child attributes
Show child attributes
Optional merchant-supplied unique NexaPay transaction reference.
Example:
"UGX"
Example:
"NGN"
Example:
"ORDER-UG-001"
Example:
"Uganda order payment"