GLOBAL PAYMENT (CROSS-BORDER)

Initiate Global Collections

Collect funds from a sender in their local currency via bank transfer or mobile money.

POST /v1/crossborder/global-collection

Bank transfer: Returns bankInfo — share these account details with the sender so they can pay
Mobile money: Sends a payment prompt to the sender's phone automatically

Prerequisites

Customer must have overall_kyc_status: approved
Fetch channel_id from GET /v1/crossborder/channels using ramptype=deposit
Fetch network_id from GET /v1/crossborder/networks

Request

Body Parameters

Parameter	Type	Required	Description
`customer_uuid`	string	✅	UUID of the KYC-approved customer (the sender)
`amount`	number	✅	Amount to collect in the sender's local currency
`currency`	string	✅	Sender's local currency
`channel_id`	string	✅	From `GET /v1/crossborder/channels` with `ramptype=deposit`
`account_number`	string	✅	Sender's bank account or mobile money number
`network_id`	string	✅	From `GET /v1/crossborder/networks`
`reason`	string	✅	Purpose of the collection
`reference`	string	✅	Unique merchant-generated reference
`dial_code`	string	✅	International dialling prefix (e.g. `+254`)
`account_type`	string	✅	`bank` or `momo`
`country_code`	string	✅	ISO 3166-1 alpha-2 country code

Code Samples — Bank Transfer Collection

const axios = require("axios");

const response = await axios.post(
  "https://sandbox.hitchpay.ng/v1/crossborder/global-collection",
  {
    customer_uuid: "dda04ec3-3774-4750-ae7b-0c070e8d084b",
    amount: 5000,
    currency: "KES",
    channel_id: "de274d59-46b3-49a8-8836-3c0cc5b73a4f",
    account_number: "254722123456",
    network_id: "30f11b2e-0905-4c09-ba5f-d05aa4e4a11c",
    reason: "entertainment",
    reference: "REF7292901912",
    dial_code: "+254",
    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-collection",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode([
    "customer_uuid" => "dda04ec3-3774-4750-ae7b-0c070e8d084b",
    "amount"        => 5000,
    "currency"      => "KES",
    "channel_id"    => "de274d59-46b3-49a8-8836-3c0cc5b73a4f",
    "account_number"=> "254722123456",
    "network_id"    => "30f11b2e-0905-4c09-ba5f-d05aa4e4a11c",
    "reason"        => "entertainment",
    "reference"     => "REF7292901912",
    "dial_code"     => "+254",
    "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-collection"

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

data = {
    "customer_uuid": "dda04ec3-3774-4750-ae7b-0c070e8d084b",
    "amount": 5000,
    "currency": "KES",
    "channel_id": "de274d59-46b3-49a8-8836-3c0cc5b73a4f",
    "account_number": "254722123456",
    "network_id": "30f11b2e-0905-4c09-ba5f-d05aa4e4a11c",
    "reason": "entertainment",
    "reference": "REF7292901912",
    "dial_code": "+254",
    "account_type": "bank",
    "country_code": "KE"
}

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

Code Samples — Mobile Money Collection

const axios = require("axios");

const response = await axios.post(
  "https://sandbox.hitchpay.ng/v1/crossborder/global-collection",
  {
    customer_uuid: "dda04ec3-3774-4750-ae7b-0c070e8d084b",
    amount: 5000,
    currency: "KES",
    channel_id: "cebda160-9966-4485-8d36-6205d516b050",
    account_number: "254722123456",
    network_id: "7ea6df5c-6bba-46b2-a7e6-f511959e7edb",
    reason: "entertainment",
    reference: "REF721291292",
    dial_code: "+254",
    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-collection",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode([
    "customer_uuid" => "dda04ec3-3774-4750-ae7b-0c070e8d084b",
    "amount"        => 5000,
    "currency"      => "KES",
    "channel_id"    => "cebda160-9966-4485-8d36-6205d516b050",
    "account_number"=> "254722123456",
    "network_id"    => "7ea6df5c-6bba-46b2-a7e6-f511959e7edb",
    "reason"        => "entertainment",
    "reference"     => "REF721291292",
    "dial_code"     => "+254",
    "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-collection"

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

data = {
    "customer_uuid": "dda04ec3-3774-4750-ae7b-0c070e8d084b",
    "amount": 5000,
    "currency": "KES",
    "channel_id": "cebda160-9966-4485-8d36-6205d516b050",
    "account_number": "254722123456",
    "network_id": "7ea6df5c-6bba-46b2-a7e6-f511959e7edb",
    "reason": "entertainment",
    "reference": "REF721291292",
    "dial_code": "+254",
    "account_type": "momo",
    "country_code": "KE"
}

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

Response

200 — Bank Transfer Collection

{
  "status": "success",
  "message": "Cross-border collection initiated successfully.",
  "data": {
    "reference": "HTCCBEF4EC275285",
    "external_reference": "REF7292901912",
    "status": "processing",
    "amount": 5000,
    "currency": "KES",
    "account_type": "bank",
    "bankInfo": {
      "accountName": "HitchPay Collections",
      "accountNumber": "1234567890",
      "bankName": "National Bank of Kenya",
      "bankCode": "52"
    }
  }
}

200 — Mobile Money Collection

{
  "status": "success",
  "message": "Cross-border collection initiated successfully.",
  "data": {
    "reference": "HTCCBEF4EC275286",
    "external_reference": "REF721291292",
    "status": "processing",
    "amount": 5000,
    "currency": "KES",
    "account_type": "momo"
  }
}

For bank collections, share the bankInfo details with your sender. For MoMo collections, the sender receives a prompt on their phone automatically

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