Skip to content
HitchPay API Docs

GLOBAL PAYMENT (CROSS-BORDER)

Initiate Global Transfer

Send money cross-border to a beneficiary's bank account or mobile money wallet.

POST /v1/crossborder/global-transfer

All payments will be charged to your USD wallet

Prerequisites

Request

Body Parameters

Parameter Type Required Description
customer_uuid string ✅ ID of the KYC-approved customer
amount number ✅ Amount in source currency
destination_currency string ✅ Currency the beneficiary receives
reference string ✅ Unique merchant-generated reference
reason string ✅ Purpose of the transfer. Transfer reasons can only be one of the following: bills, groceries, gift, travel, health, entertainment, housing, school-fees, other
beneficiary.account_name string ✅ Beneficiary's full name
beneficiary.account_number string ✅ Bank account or mobile money number
beneficiary.network_id string ✅ From GET /v1/crossborder/networks
beneficiary.channel_id string ✅ From GET /v1/crossborder/channels
beneficiary.account_type string ✅ bank or momo
beneficiary.country_code string ✅ ISO 3166-1 alpha-2 country code
beneficiary.dial_code string MoMo only International dialling prefix (e.g. +254)

Code Samples — Bank Transfer

const axios = require("axios");

const response = await axios.post(
  "https://sandbox.hitchpay.ng/v1/crossborder/global-transfer",
  {
    customer_uuid: "dda04ec3-3774-4750-ae7b-0c070e8d084b",
    amount: 100,
    source_currency: "USD",
    destination_currency: "KES",
    reference: "REF_BANK_001",
    reason: "School fees",
    beneficiary: {
      account_name: "Jane Doe",
      account_number: "0123456789",
      network_id: "30f11b2e-0905-4c09-ba5f-d05aa4e4a11c",
      channel_id: "de274d59-46b3-49a8-8836-3c0cc5b73a4f",
      account_type: "bank",
      country_code: "KE"
    }
  },
  {
    headers: {
      Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
      "Content-Type": "application/json"
    }
  }
);

console.log(response.data);
<?php

$ch = curl_init();

curl_setopt_array($ch, [
  CURLOPT_URL => "https://sandbox.hitchpay.ng/v1/crossborder/global-transfer",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode([
    "customer_uuid"        => "dda04ec3-3774-4750-ae7b-0c070e8d084b",
    "amount"               => 100,
    "source_currency"      => "USD",
    "destination_currency" => "KES",
    "reference"            => "REF_BANK_001",
    "reason"               => "School fees",
    "beneficiary"          => [
      "account_name"   => "Jane Doe",
      "account_number" => "0123456789",
      "network_id"     => "30f11b2e-0905-4c09-ba5f-d05aa4e4a11c",
      "channel_id"     => "de274d59-46b3-49a8-8836-3c0cc5b73a4f",
      "account_type"   => "bank",
      "country_code"   => "KE"
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Content-Type: application/json"
  ]
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
import requests

url = "https://sandbox.hitchpay.ng/v1/crossborder/global-transfer"

headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}

data = {
    "customer_uuid": "dda04ec3-3774-4750-ae7b-0c070e8d084b",
    "amount": 100,
    "source_currency": "USD",
    "destination_currency": "KES",
    "reference": "REF_BANK_001",
    "reason": "School fees",
    "beneficiary": {
        "account_name": "Jane Doe",
        "account_number": "0123456789",
        "network_id": "30f11b2e-0905-4c09-ba5f-d05aa4e4a11c",
        "channel_id": "de274d59-46b3-49a8-8836-3c0cc5b73a4f",
        "account_type": "bank",
        "country_code": "KE"
    }
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

Code Samples — Mobile Money

const axios = require("axios");

const response = await axios.post(
  "https://sandbox.hitchpay.ng/v1/crossborder/global-transfer",
  {
    customer_uuid: "dda04ec3-3774-4750-ae7b-0c070e8d084b",
    amount: 5,
    source_currency: "NGN",
    destination_currency: "KES",
    reference: "REF_MOMO_001",
    reason: "Payment for services",
    beneficiary: {
      account_name: "John Smith",
      account_number: "254722123456",
      dial_code: "+254",
      network_id: "7ea6df5c-6bba-46b2-a7e6-f511959e7edb",
      channel_id: "cebda160-9966-4485-8d36-6205d516b050",
      account_type: "momo",
      country_code: "KE"
    }
  },
  {
    headers: {
      Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
      "Content-Type": "application/json"
    }
  }
);

console.log(response.data);
<?php

$ch = curl_init();

curl_setopt_array($ch, [
  CURLOPT_URL => "https://sandbox.hitchpay.ng/v1/crossborder/global-transfer",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode([
    "customer_uuid"        => "dda04ec3-3774-4750-ae7b-0c070e8d084b",
    "amount"               => 5,
    "source_currency"      => "NGN",
    "destination_currency" => "KES",
    "reference"            => "REF_MOMO_001",
    "reason"               => "Payment for services",
    "beneficiary"          => [
      "account_name"   => "John Smith",
      "account_number" => "254722123456",
      "dial_code"      => "+254",
      "network_id"     => "7ea6df5c-6bba-46b2-a7e6-f511959e7edb",
      "channel_id"     => "cebda160-9966-4485-8d36-6205d516b050",
      "account_type"   => "momo",
      "country_code"   => "KE"
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Content-Type: application/json"
  ]
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
import requests

url = "https://sandbox.hitchpay.ng/v1/crossborder/global-transfer"

headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}

data = {
    "customer_uuid": "dda04ec3-3774-4750-ae7b-0c070e8d084b",
    "amount": 5,
    "source_currency": "NGN",
    "destination_currency": "KES",
    "reference": "REF_MOMO_001",
    "reason": "Payment for services",
    "beneficiary": {
        "account_name": "John Smith",
        "account_number": "254722123456",
        "dial_code": "+254",
        "network_id": "7ea6df5c-6bba-46b2-a7e6-f511959e7edb",
        "channel_id": "cebda160-9966-4485-8d36-6205d516b050",
        "account_type": "momo",
        "country_code": "KE"
    }
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

Response

200 — Transfer Initiated

{
  "status": "success",
  "message": "Cross-border transfer initiated successfully.",
  "data": {
    "reference": "HTCB13BE4DAC468B",
    "external_reference": "REF_BANK_001",
    "status": "processing",
    "provider_status": "created",
    "provider_reference": "81939272-9c53-5671-8dd3-0a445ef19c48",
    "amount_sent": 100,
    "source_currency": "USD",
    "estimated_amount_received": 12873.28,
    "destination_currency": "KES"
  }
}

Questions? Email [email protected]. Also on GitBook.