Create crypto bridge deposit (Cross-border remittances)
curl --request POST \
--url https://preview.kotanipay.com/api/v3/deposit/crypto-bridge \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"customer_key": "PROVIDER_CUSTOMER_123",
"provider_reference_id": "PROVIDER-TXN-20241122-001",
"amount": 1000,
"source_currency": "KES",
"wallet_id": "KOTANI_WALLET_ID",
"transaction_type": "cross_border",
"chain": "LIGHTNING",
"token": "MSAT",
"crypto_payment": {
"bolt11": "lnbc1500n1p0xyz...",
"payment_hash": "a1b2c3d4e5f6...",
"amount_msat": 150000000,
"address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
"crypto_amount": 150.5,
"expires_at": "2024-11-22T12:30:00Z"
},
"settlement": {
"amount": 150,
"currency": "ZAR",
"country": "ZA",
"recipient": {
"phone_number": "+27821234567",
"payment_method": "MOBILE_MONEY",
"mobile_money_provider": "VODACOM",
"bank_account_number": "1234567890",
"bank_code": "ABSA",
"account_holder_name": "Jane Smith"
}
},
"callback_url": "https://api.provider.com/webhooks/kotani/status",
"rate_id": "RATE-CB-1732454321-XYZ123",
"metadata": {
"sender_name": "John Doe",
"sender_country": "KE",
"recipient_name": "Jane Smith",
"recipient_country": "ZA",
"notes": "Family support payment"
}
}
'import requests
url = "https://preview.kotanipay.com/api/v3/deposit/crypto-bridge"
payload = {
"customer_key": "PROVIDER_CUSTOMER_123",
"provider_reference_id": "PROVIDER-TXN-20241122-001",
"amount": 1000,
"source_currency": "KES",
"wallet_id": "KOTANI_WALLET_ID",
"transaction_type": "cross_border",
"chain": "LIGHTNING",
"token": "MSAT",
"crypto_payment": {
"bolt11": "lnbc1500n1p0xyz...",
"payment_hash": "a1b2c3d4e5f6...",
"amount_msat": 150000000,
"address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
"crypto_amount": 150.5,
"expires_at": "2024-11-22T12:30:00Z"
},
"settlement": {
"amount": 150,
"currency": "ZAR",
"country": "ZA",
"recipient": {
"phone_number": "+27821234567",
"payment_method": "MOBILE_MONEY",
"mobile_money_provider": "VODACOM",
"bank_account_number": "1234567890",
"bank_code": "ABSA",
"account_holder_name": "Jane Smith"
}
},
"callback_url": "https://api.provider.com/webhooks/kotani/status",
"rate_id": "RATE-CB-1732454321-XYZ123",
"metadata": {
"sender_name": "John Doe",
"sender_country": "KE",
"recipient_name": "Jane Smith",
"recipient_country": "ZA",
"notes": "Family support payment"
}
}
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({
customer_key: 'PROVIDER_CUSTOMER_123',
provider_reference_id: 'PROVIDER-TXN-20241122-001',
amount: 1000,
source_currency: 'KES',
wallet_id: 'KOTANI_WALLET_ID',
transaction_type: 'cross_border',
chain: 'LIGHTNING',
token: 'MSAT',
crypto_payment: {
bolt11: 'lnbc1500n1p0xyz...',
payment_hash: 'a1b2c3d4e5f6...',
amount_msat: 150000000,
address: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
crypto_amount: 150.5,
expires_at: '2024-11-22T12:30:00Z'
},
settlement: {
amount: 150,
currency: 'ZAR',
country: 'ZA',
recipient: {
phone_number: '+27821234567',
payment_method: 'MOBILE_MONEY',
mobile_money_provider: 'VODACOM',
bank_account_number: '1234567890',
bank_code: 'ABSA',
account_holder_name: 'Jane Smith'
}
},
callback_url: 'https://api.provider.com/webhooks/kotani/status',
rate_id: 'RATE-CB-1732454321-XYZ123',
metadata: {
sender_name: 'John Doe',
sender_country: 'KE',
recipient_name: 'Jane Smith',
recipient_country: 'ZA',
notes: 'Family support payment'
}
})
};
fetch('https://preview.kotanipay.com/api/v3/deposit/crypto-bridge', 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://preview.kotanipay.com/api/v3/deposit/crypto-bridge",
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([
'customer_key' => 'PROVIDER_CUSTOMER_123',
'provider_reference_id' => 'PROVIDER-TXN-20241122-001',
'amount' => 1000,
'source_currency' => 'KES',
'wallet_id' => 'KOTANI_WALLET_ID',
'transaction_type' => 'cross_border',
'chain' => 'LIGHTNING',
'token' => 'MSAT',
'crypto_payment' => [
'bolt11' => 'lnbc1500n1p0xyz...',
'payment_hash' => 'a1b2c3d4e5f6...',
'amount_msat' => 150000000,
'address' => '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
'crypto_amount' => 150.5,
'expires_at' => '2024-11-22T12:30:00Z'
],
'settlement' => [
'amount' => 150,
'currency' => 'ZAR',
'country' => 'ZA',
'recipient' => [
'phone_number' => '+27821234567',
'payment_method' => 'MOBILE_MONEY',
'mobile_money_provider' => 'VODACOM',
'bank_account_number' => '1234567890',
'bank_code' => 'ABSA',
'account_holder_name' => 'Jane Smith'
]
],
'callback_url' => 'https://api.provider.com/webhooks/kotani/status',
'rate_id' => 'RATE-CB-1732454321-XYZ123',
'metadata' => [
'sender_name' => 'John Doe',
'sender_country' => 'KE',
'recipient_name' => 'Jane Smith',
'recipient_country' => 'ZA',
'notes' => 'Family support payment'
]
]),
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://preview.kotanipay.com/api/v3/deposit/crypto-bridge"
payload := strings.NewReader("{\n \"customer_key\": \"PROVIDER_CUSTOMER_123\",\n \"provider_reference_id\": \"PROVIDER-TXN-20241122-001\",\n \"amount\": 1000,\n \"source_currency\": \"KES\",\n \"wallet_id\": \"KOTANI_WALLET_ID\",\n \"transaction_type\": \"cross_border\",\n \"chain\": \"LIGHTNING\",\n \"token\": \"MSAT\",\n \"crypto_payment\": {\n \"bolt11\": \"lnbc1500n1p0xyz...\",\n \"payment_hash\": \"a1b2c3d4e5f6...\",\n \"amount_msat\": 150000000,\n \"address\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n \"crypto_amount\": 150.5,\n \"expires_at\": \"2024-11-22T12:30:00Z\"\n },\n \"settlement\": {\n \"amount\": 150,\n \"currency\": \"ZAR\",\n \"country\": \"ZA\",\n \"recipient\": {\n \"phone_number\": \"+27821234567\",\n \"payment_method\": \"MOBILE_MONEY\",\n \"mobile_money_provider\": \"VODACOM\",\n \"bank_account_number\": \"1234567890\",\n \"bank_code\": \"ABSA\",\n \"account_holder_name\": \"Jane Smith\"\n }\n },\n \"callback_url\": \"https://api.provider.com/webhooks/kotani/status\",\n \"rate_id\": \"RATE-CB-1732454321-XYZ123\",\n \"metadata\": {\n \"sender_name\": \"John Doe\",\n \"sender_country\": \"KE\",\n \"recipient_name\": \"Jane Smith\",\n \"recipient_country\": \"ZA\",\n \"notes\": \"Family support payment\"\n }\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://preview.kotanipay.com/api/v3/deposit/crypto-bridge")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"customer_key\": \"PROVIDER_CUSTOMER_123\",\n \"provider_reference_id\": \"PROVIDER-TXN-20241122-001\",\n \"amount\": 1000,\n \"source_currency\": \"KES\",\n \"wallet_id\": \"KOTANI_WALLET_ID\",\n \"transaction_type\": \"cross_border\",\n \"chain\": \"LIGHTNING\",\n \"token\": \"MSAT\",\n \"crypto_payment\": {\n \"bolt11\": \"lnbc1500n1p0xyz...\",\n \"payment_hash\": \"a1b2c3d4e5f6...\",\n \"amount_msat\": 150000000,\n \"address\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n \"crypto_amount\": 150.5,\n \"expires_at\": \"2024-11-22T12:30:00Z\"\n },\n \"settlement\": {\n \"amount\": 150,\n \"currency\": \"ZAR\",\n \"country\": \"ZA\",\n \"recipient\": {\n \"phone_number\": \"+27821234567\",\n \"payment_method\": \"MOBILE_MONEY\",\n \"mobile_money_provider\": \"VODACOM\",\n \"bank_account_number\": \"1234567890\",\n \"bank_code\": \"ABSA\",\n \"account_holder_name\": \"Jane Smith\"\n }\n },\n \"callback_url\": \"https://api.provider.com/webhooks/kotani/status\",\n \"rate_id\": \"RATE-CB-1732454321-XYZ123\",\n \"metadata\": {\n \"sender_name\": \"John Doe\",\n \"sender_country\": \"KE\",\n \"recipient_name\": \"Jane Smith\",\n \"recipient_country\": \"ZA\",\n \"notes\": \"Family support payment\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://preview.kotanipay.com/api/v3/deposit/crypto-bridge")
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 \"customer_key\": \"PROVIDER_CUSTOMER_123\",\n \"provider_reference_id\": \"PROVIDER-TXN-20241122-001\",\n \"amount\": 1000,\n \"source_currency\": \"KES\",\n \"wallet_id\": \"KOTANI_WALLET_ID\",\n \"transaction_type\": \"cross_border\",\n \"chain\": \"LIGHTNING\",\n \"token\": \"MSAT\",\n \"crypto_payment\": {\n \"bolt11\": \"lnbc1500n1p0xyz...\",\n \"payment_hash\": \"a1b2c3d4e5f6...\",\n \"amount_msat\": 150000000,\n \"address\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n \"crypto_amount\": 150.5,\n \"expires_at\": \"2024-11-22T12:30:00Z\"\n },\n \"settlement\": {\n \"amount\": 150,\n \"currency\": \"ZAR\",\n \"country\": \"ZA\",\n \"recipient\": {\n \"phone_number\": \"+27821234567\",\n \"payment_method\": \"MOBILE_MONEY\",\n \"mobile_money_provider\": \"VODACOM\",\n \"bank_account_number\": \"1234567890\",\n \"bank_code\": \"ABSA\",\n \"account_holder_name\": \"Jane Smith\"\n }\n },\n \"callback_url\": \"https://api.provider.com/webhooks/kotani/status\",\n \"rate_id\": \"RATE-CB-1732454321-XYZ123\",\n \"metadata\": {\n \"sender_name\": \"John Doe\",\n \"sender_country\": \"KE\",\n \"recipient_name\": \"Jane Smith\",\n \"recipient_country\": \"ZA\",\n \"notes\": \"Family support payment\"\n }\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "Crypto bridge deposit initiated successfully.",
"data": {
"kotani_reference_id": "KOTANI-REF-789",
"provider_reference_id": "PROVIDER-TXN-20241122-001",
"status": "DEPOSIT_INITIATED",
"chain": "LIGHTNING",
"token": "MSAT",
"payment_hash": "a1b2c3d4e5f6...",
"refund_config": {
"primary_method": "CRYPTO_INVOICE",
"chain": "LIGHTNING",
"token": "MSAT",
"refund_invoice": "lnbc1500n1p0xyz...",
"refund_payment_hash": "a1b2c3d4e5f6...",
"refund_amount_msat": 150000000,
"refund_crypto_amount": 150.5,
"fallback_address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
"fallback_method": "CRYPTO_ADDRESS",
"expires_at": "2024-11-22T13:00:00Z"
},
"estimated_completion": "2024-11-22T12:10:00Z",
"created_at": "2024-11-22T12:00:00Z"
}
}{
"success": false,
"message": "Bad Request",
"data": {}
}{
"success": false,
"message": "Unauthorized",
"data": {}
}{
"success": false,
"message": "Invalid invoice or payment details",
"data": {}
}Crypto Bridge
Create Crypto Bridge Deposit
Enables cross-border transactions using blockchain as settlement rail. Provider initiates the transaction with a pre-generated payment invoice. Flow: Fiat collection → Crypto payment → Settlement to recipient. Supports Lightning Network, Solana, Base, Ethereum, and other chains. Supports mobile money and bank transfer settlements.
POST
/
api
/
v3
/
deposit
/
crypto-bridge
Create crypto bridge deposit (Cross-border remittances)
curl --request POST \
--url https://preview.kotanipay.com/api/v3/deposit/crypto-bridge \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"customer_key": "PROVIDER_CUSTOMER_123",
"provider_reference_id": "PROVIDER-TXN-20241122-001",
"amount": 1000,
"source_currency": "KES",
"wallet_id": "KOTANI_WALLET_ID",
"transaction_type": "cross_border",
"chain": "LIGHTNING",
"token": "MSAT",
"crypto_payment": {
"bolt11": "lnbc1500n1p0xyz...",
"payment_hash": "a1b2c3d4e5f6...",
"amount_msat": 150000000,
"address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
"crypto_amount": 150.5,
"expires_at": "2024-11-22T12:30:00Z"
},
"settlement": {
"amount": 150,
"currency": "ZAR",
"country": "ZA",
"recipient": {
"phone_number": "+27821234567",
"payment_method": "MOBILE_MONEY",
"mobile_money_provider": "VODACOM",
"bank_account_number": "1234567890",
"bank_code": "ABSA",
"account_holder_name": "Jane Smith"
}
},
"callback_url": "https://api.provider.com/webhooks/kotani/status",
"rate_id": "RATE-CB-1732454321-XYZ123",
"metadata": {
"sender_name": "John Doe",
"sender_country": "KE",
"recipient_name": "Jane Smith",
"recipient_country": "ZA",
"notes": "Family support payment"
}
}
'import requests
url = "https://preview.kotanipay.com/api/v3/deposit/crypto-bridge"
payload = {
"customer_key": "PROVIDER_CUSTOMER_123",
"provider_reference_id": "PROVIDER-TXN-20241122-001",
"amount": 1000,
"source_currency": "KES",
"wallet_id": "KOTANI_WALLET_ID",
"transaction_type": "cross_border",
"chain": "LIGHTNING",
"token": "MSAT",
"crypto_payment": {
"bolt11": "lnbc1500n1p0xyz...",
"payment_hash": "a1b2c3d4e5f6...",
"amount_msat": 150000000,
"address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
"crypto_amount": 150.5,
"expires_at": "2024-11-22T12:30:00Z"
},
"settlement": {
"amount": 150,
"currency": "ZAR",
"country": "ZA",
"recipient": {
"phone_number": "+27821234567",
"payment_method": "MOBILE_MONEY",
"mobile_money_provider": "VODACOM",
"bank_account_number": "1234567890",
"bank_code": "ABSA",
"account_holder_name": "Jane Smith"
}
},
"callback_url": "https://api.provider.com/webhooks/kotani/status",
"rate_id": "RATE-CB-1732454321-XYZ123",
"metadata": {
"sender_name": "John Doe",
"sender_country": "KE",
"recipient_name": "Jane Smith",
"recipient_country": "ZA",
"notes": "Family support payment"
}
}
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({
customer_key: 'PROVIDER_CUSTOMER_123',
provider_reference_id: 'PROVIDER-TXN-20241122-001',
amount: 1000,
source_currency: 'KES',
wallet_id: 'KOTANI_WALLET_ID',
transaction_type: 'cross_border',
chain: 'LIGHTNING',
token: 'MSAT',
crypto_payment: {
bolt11: 'lnbc1500n1p0xyz...',
payment_hash: 'a1b2c3d4e5f6...',
amount_msat: 150000000,
address: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
crypto_amount: 150.5,
expires_at: '2024-11-22T12:30:00Z'
},
settlement: {
amount: 150,
currency: 'ZAR',
country: 'ZA',
recipient: {
phone_number: '+27821234567',
payment_method: 'MOBILE_MONEY',
mobile_money_provider: 'VODACOM',
bank_account_number: '1234567890',
bank_code: 'ABSA',
account_holder_name: 'Jane Smith'
}
},
callback_url: 'https://api.provider.com/webhooks/kotani/status',
rate_id: 'RATE-CB-1732454321-XYZ123',
metadata: {
sender_name: 'John Doe',
sender_country: 'KE',
recipient_name: 'Jane Smith',
recipient_country: 'ZA',
notes: 'Family support payment'
}
})
};
fetch('https://preview.kotanipay.com/api/v3/deposit/crypto-bridge', 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://preview.kotanipay.com/api/v3/deposit/crypto-bridge",
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([
'customer_key' => 'PROVIDER_CUSTOMER_123',
'provider_reference_id' => 'PROVIDER-TXN-20241122-001',
'amount' => 1000,
'source_currency' => 'KES',
'wallet_id' => 'KOTANI_WALLET_ID',
'transaction_type' => 'cross_border',
'chain' => 'LIGHTNING',
'token' => 'MSAT',
'crypto_payment' => [
'bolt11' => 'lnbc1500n1p0xyz...',
'payment_hash' => 'a1b2c3d4e5f6...',
'amount_msat' => 150000000,
'address' => '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
'crypto_amount' => 150.5,
'expires_at' => '2024-11-22T12:30:00Z'
],
'settlement' => [
'amount' => 150,
'currency' => 'ZAR',
'country' => 'ZA',
'recipient' => [
'phone_number' => '+27821234567',
'payment_method' => 'MOBILE_MONEY',
'mobile_money_provider' => 'VODACOM',
'bank_account_number' => '1234567890',
'bank_code' => 'ABSA',
'account_holder_name' => 'Jane Smith'
]
],
'callback_url' => 'https://api.provider.com/webhooks/kotani/status',
'rate_id' => 'RATE-CB-1732454321-XYZ123',
'metadata' => [
'sender_name' => 'John Doe',
'sender_country' => 'KE',
'recipient_name' => 'Jane Smith',
'recipient_country' => 'ZA',
'notes' => 'Family support payment'
]
]),
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://preview.kotanipay.com/api/v3/deposit/crypto-bridge"
payload := strings.NewReader("{\n \"customer_key\": \"PROVIDER_CUSTOMER_123\",\n \"provider_reference_id\": \"PROVIDER-TXN-20241122-001\",\n \"amount\": 1000,\n \"source_currency\": \"KES\",\n \"wallet_id\": \"KOTANI_WALLET_ID\",\n \"transaction_type\": \"cross_border\",\n \"chain\": \"LIGHTNING\",\n \"token\": \"MSAT\",\n \"crypto_payment\": {\n \"bolt11\": \"lnbc1500n1p0xyz...\",\n \"payment_hash\": \"a1b2c3d4e5f6...\",\n \"amount_msat\": 150000000,\n \"address\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n \"crypto_amount\": 150.5,\n \"expires_at\": \"2024-11-22T12:30:00Z\"\n },\n \"settlement\": {\n \"amount\": 150,\n \"currency\": \"ZAR\",\n \"country\": \"ZA\",\n \"recipient\": {\n \"phone_number\": \"+27821234567\",\n \"payment_method\": \"MOBILE_MONEY\",\n \"mobile_money_provider\": \"VODACOM\",\n \"bank_account_number\": \"1234567890\",\n \"bank_code\": \"ABSA\",\n \"account_holder_name\": \"Jane Smith\"\n }\n },\n \"callback_url\": \"https://api.provider.com/webhooks/kotani/status\",\n \"rate_id\": \"RATE-CB-1732454321-XYZ123\",\n \"metadata\": {\n \"sender_name\": \"John Doe\",\n \"sender_country\": \"KE\",\n \"recipient_name\": \"Jane Smith\",\n \"recipient_country\": \"ZA\",\n \"notes\": \"Family support payment\"\n }\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://preview.kotanipay.com/api/v3/deposit/crypto-bridge")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"customer_key\": \"PROVIDER_CUSTOMER_123\",\n \"provider_reference_id\": \"PROVIDER-TXN-20241122-001\",\n \"amount\": 1000,\n \"source_currency\": \"KES\",\n \"wallet_id\": \"KOTANI_WALLET_ID\",\n \"transaction_type\": \"cross_border\",\n \"chain\": \"LIGHTNING\",\n \"token\": \"MSAT\",\n \"crypto_payment\": {\n \"bolt11\": \"lnbc1500n1p0xyz...\",\n \"payment_hash\": \"a1b2c3d4e5f6...\",\n \"amount_msat\": 150000000,\n \"address\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n \"crypto_amount\": 150.5,\n \"expires_at\": \"2024-11-22T12:30:00Z\"\n },\n \"settlement\": {\n \"amount\": 150,\n \"currency\": \"ZAR\",\n \"country\": \"ZA\",\n \"recipient\": {\n \"phone_number\": \"+27821234567\",\n \"payment_method\": \"MOBILE_MONEY\",\n \"mobile_money_provider\": \"VODACOM\",\n \"bank_account_number\": \"1234567890\",\n \"bank_code\": \"ABSA\",\n \"account_holder_name\": \"Jane Smith\"\n }\n },\n \"callback_url\": \"https://api.provider.com/webhooks/kotani/status\",\n \"rate_id\": \"RATE-CB-1732454321-XYZ123\",\n \"metadata\": {\n \"sender_name\": \"John Doe\",\n \"sender_country\": \"KE\",\n \"recipient_name\": \"Jane Smith\",\n \"recipient_country\": \"ZA\",\n \"notes\": \"Family support payment\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://preview.kotanipay.com/api/v3/deposit/crypto-bridge")
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 \"customer_key\": \"PROVIDER_CUSTOMER_123\",\n \"provider_reference_id\": \"PROVIDER-TXN-20241122-001\",\n \"amount\": 1000,\n \"source_currency\": \"KES\",\n \"wallet_id\": \"KOTANI_WALLET_ID\",\n \"transaction_type\": \"cross_border\",\n \"chain\": \"LIGHTNING\",\n \"token\": \"MSAT\",\n \"crypto_payment\": {\n \"bolt11\": \"lnbc1500n1p0xyz...\",\n \"payment_hash\": \"a1b2c3d4e5f6...\",\n \"amount_msat\": 150000000,\n \"address\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n \"crypto_amount\": 150.5,\n \"expires_at\": \"2024-11-22T12:30:00Z\"\n },\n \"settlement\": {\n \"amount\": 150,\n \"currency\": \"ZAR\",\n \"country\": \"ZA\",\n \"recipient\": {\n \"phone_number\": \"+27821234567\",\n \"payment_method\": \"MOBILE_MONEY\",\n \"mobile_money_provider\": \"VODACOM\",\n \"bank_account_number\": \"1234567890\",\n \"bank_code\": \"ABSA\",\n \"account_holder_name\": \"Jane Smith\"\n }\n },\n \"callback_url\": \"https://api.provider.com/webhooks/kotani/status\",\n \"rate_id\": \"RATE-CB-1732454321-XYZ123\",\n \"metadata\": {\n \"sender_name\": \"John Doe\",\n \"sender_country\": \"KE\",\n \"recipient_name\": \"Jane Smith\",\n \"recipient_country\": \"ZA\",\n \"notes\": \"Family support payment\"\n }\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "Crypto bridge deposit initiated successfully.",
"data": {
"kotani_reference_id": "KOTANI-REF-789",
"provider_reference_id": "PROVIDER-TXN-20241122-001",
"status": "DEPOSIT_INITIATED",
"chain": "LIGHTNING",
"token": "MSAT",
"payment_hash": "a1b2c3d4e5f6...",
"refund_config": {
"primary_method": "CRYPTO_INVOICE",
"chain": "LIGHTNING",
"token": "MSAT",
"refund_invoice": "lnbc1500n1p0xyz...",
"refund_payment_hash": "a1b2c3d4e5f6...",
"refund_amount_msat": 150000000,
"refund_crypto_amount": 150.5,
"fallback_address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
"fallback_method": "CRYPTO_ADDRESS",
"expires_at": "2024-11-22T13:00:00Z"
},
"estimated_completion": "2024-11-22T12:10:00Z",
"created_at": "2024-11-22T12:00:00Z"
}
}{
"success": false,
"message": "Bad Request",
"data": {}
}{
"success": false,
"message": "Unauthorized",
"data": {}
}{
"success": false,
"message": "Invalid invoice or payment details",
"data": {}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
Customer key (Provider customer ID in Kotani system)
Example:
"PROVIDER_CUSTOMER_123"
Provider's unique transaction reference ID
Example:
"PROVIDER-TXN-20241122-001"
Source fiat amount
Example:
1000
Source fiat currency code
Example:
"KES"
Kotani wallet ID to use for transaction
Example:
"KOTANI_WALLET_ID"
Type of bridge transaction
Available options:
cross_border, bridge, chain_settlement Example:
"cross_border"
Blockchain/network to use
Available options:
CELO, ETHEREUM, ARBITRUM, AVALANCHE, BINANCE, POLYGON, OPTIMISM, FUSE, TRON, PROVENANCE, SOLANA, HEDERA, STELLAR, BASE, LISK, VICTION, SCROLL, LIGHTNING Example:
"LIGHTNING"
Token/asset to use
Available options:
CUSD, USDC, USDT, BUSD, HASH, HBAR, USDGLO, CKES, CGHS, MSAT Example:
"MSAT"
Crypto payment details (pre-generated invoice or address)
Show child attributes
Show child attributes
Settlement details for recipient
Show child attributes
Show child attributes
Callback URL for status updates
Example:
"https://api.provider.com/webhooks/kotani/status"
Rate ID from /rate/crypto-bridge endpoint. Optional but recommended. Validates fiat->crypto conversion rate. Rate expires in 60 seconds.
Example:
"RATE-CB-1732454321-XYZ123"
Additional transaction metadata
Show child attributes
Show child attributes