Webhook endpoint for provider settlement status updates
curl --request POST \
--url https://preview.kotanipay.com/api/v3/deposit/crypto-bridge/webhook/provider/settlement \
--header 'Content-Type: application/json' \
--data '
{
"webhook_type": "SETTLEMENT_STATUS_UPDATE",
"provider_reference_id": "PROVIDER-TXN-20241122-001",
"kotani_reference_id": "KOTANI-REF-789",
"status": "COMPLETED",
"timestamp": "2024-11-22T12:05:00Z",
"crypto_payment": {
"chain": "LIGHTNING",
"token": "MSAT",
"payment_hash": "a1b2c3d4e5f6...",
"received_at": "2024-11-22T12:01:30Z",
"amount_msat": 150000000,
"crypto_amount": 150.5
},
"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/webhook/provider/settlement"
payload = {
"webhook_type": "SETTLEMENT_STATUS_UPDATE",
"provider_reference_id": "PROVIDER-TXN-20241122-001",
"kotani_reference_id": "KOTANI-REF-789",
"status": "COMPLETED",
"timestamp": "2024-11-22T12:05:00Z",
"crypto_payment": {
"chain": "LIGHTNING",
"token": "MSAT",
"payment_hash": "a1b2c3d4e5f6...",
"received_at": "2024-11-22T12:01:30Z",
"amount_msat": 150000000,
"crypto_amount": 150.5
},
"metadata": {
"sender_name": "John Doe",
"sender_country": "KE",
"recipient_name": "Jane Smith",
"recipient_country": "ZA",
"notes": "Family support payment"
}
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
webhook_type: 'SETTLEMENT_STATUS_UPDATE',
provider_reference_id: 'PROVIDER-TXN-20241122-001',
kotani_reference_id: 'KOTANI-REF-789',
status: 'COMPLETED',
timestamp: '2024-11-22T12:05:00Z',
crypto_payment: {
chain: 'LIGHTNING',
token: 'MSAT',
payment_hash: 'a1b2c3d4e5f6...',
received_at: '2024-11-22T12:01:30Z',
amount_msat: 150000000,
crypto_amount: 150.5
},
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/webhook/provider/settlement', 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/webhook/provider/settlement",
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([
'webhook_type' => 'SETTLEMENT_STATUS_UPDATE',
'provider_reference_id' => 'PROVIDER-TXN-20241122-001',
'kotani_reference_id' => 'KOTANI-REF-789',
'status' => 'COMPLETED',
'timestamp' => '2024-11-22T12:05:00Z',
'crypto_payment' => [
'chain' => 'LIGHTNING',
'token' => 'MSAT',
'payment_hash' => 'a1b2c3d4e5f6...',
'received_at' => '2024-11-22T12:01:30Z',
'amount_msat' => 150000000,
'crypto_amount' => 150.5
],
'metadata' => [
'sender_name' => 'John Doe',
'sender_country' => 'KE',
'recipient_name' => 'Jane Smith',
'recipient_country' => 'ZA',
'notes' => 'Family support payment'
]
]),
CURLOPT_HTTPHEADER => [
"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/webhook/provider/settlement"
payload := strings.NewReader("{\n \"webhook_type\": \"SETTLEMENT_STATUS_UPDATE\",\n \"provider_reference_id\": \"PROVIDER-TXN-20241122-001\",\n \"kotani_reference_id\": \"KOTANI-REF-789\",\n \"status\": \"COMPLETED\",\n \"timestamp\": \"2024-11-22T12:05:00Z\",\n \"crypto_payment\": {\n \"chain\": \"LIGHTNING\",\n \"token\": \"MSAT\",\n \"payment_hash\": \"a1b2c3d4e5f6...\",\n \"received_at\": \"2024-11-22T12:01:30Z\",\n \"amount_msat\": 150000000,\n \"crypto_amount\": 150.5\n },\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("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/webhook/provider/settlement")
.header("Content-Type", "application/json")
.body("{\n \"webhook_type\": \"SETTLEMENT_STATUS_UPDATE\",\n \"provider_reference_id\": \"PROVIDER-TXN-20241122-001\",\n \"kotani_reference_id\": \"KOTANI-REF-789\",\n \"status\": \"COMPLETED\",\n \"timestamp\": \"2024-11-22T12:05:00Z\",\n \"crypto_payment\": {\n \"chain\": \"LIGHTNING\",\n \"token\": \"MSAT\",\n \"payment_hash\": \"a1b2c3d4e5f6...\",\n \"received_at\": \"2024-11-22T12:01:30Z\",\n \"amount_msat\": 150000000,\n \"crypto_amount\": 150.5\n },\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/webhook/provider/settlement")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"webhook_type\": \"SETTLEMENT_STATUS_UPDATE\",\n \"provider_reference_id\": \"PROVIDER-TXN-20241122-001\",\n \"kotani_reference_id\": \"KOTANI-REF-789\",\n \"status\": \"COMPLETED\",\n \"timestamp\": \"2024-11-22T12:05:00Z\",\n \"crypto_payment\": {\n \"chain\": \"LIGHTNING\",\n \"token\": \"MSAT\",\n \"payment_hash\": \"a1b2c3d4e5f6...\",\n \"received_at\": \"2024-11-22T12:01:30Z\",\n \"amount_msat\": 150000000,\n \"crypto_amount\": 150.5\n },\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": "Webhook received and processed.",
"data": {}
}{
"success": false,
"message": "Transaction not found",
"data": {}
}Crypto Bridge
Crypto Bridge Provider Settlement Webhook
Receives settlement status updates from settlement provider. Requires signature validation. Statuses: SETTLING, COMPLETED, FAILED. For FAILED status, initiates refund process using configured refund method.
POST
/
api
/
v3
/
deposit
/
crypto-bridge
/
webhook
/
provider
/
settlement
Webhook endpoint for provider settlement status updates
curl --request POST \
--url https://preview.kotanipay.com/api/v3/deposit/crypto-bridge/webhook/provider/settlement \
--header 'Content-Type: application/json' \
--data '
{
"webhook_type": "SETTLEMENT_STATUS_UPDATE",
"provider_reference_id": "PROVIDER-TXN-20241122-001",
"kotani_reference_id": "KOTANI-REF-789",
"status": "COMPLETED",
"timestamp": "2024-11-22T12:05:00Z",
"crypto_payment": {
"chain": "LIGHTNING",
"token": "MSAT",
"payment_hash": "a1b2c3d4e5f6...",
"received_at": "2024-11-22T12:01:30Z",
"amount_msat": 150000000,
"crypto_amount": 150.5
},
"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/webhook/provider/settlement"
payload = {
"webhook_type": "SETTLEMENT_STATUS_UPDATE",
"provider_reference_id": "PROVIDER-TXN-20241122-001",
"kotani_reference_id": "KOTANI-REF-789",
"status": "COMPLETED",
"timestamp": "2024-11-22T12:05:00Z",
"crypto_payment": {
"chain": "LIGHTNING",
"token": "MSAT",
"payment_hash": "a1b2c3d4e5f6...",
"received_at": "2024-11-22T12:01:30Z",
"amount_msat": 150000000,
"crypto_amount": 150.5
},
"metadata": {
"sender_name": "John Doe",
"sender_country": "KE",
"recipient_name": "Jane Smith",
"recipient_country": "ZA",
"notes": "Family support payment"
}
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
webhook_type: 'SETTLEMENT_STATUS_UPDATE',
provider_reference_id: 'PROVIDER-TXN-20241122-001',
kotani_reference_id: 'KOTANI-REF-789',
status: 'COMPLETED',
timestamp: '2024-11-22T12:05:00Z',
crypto_payment: {
chain: 'LIGHTNING',
token: 'MSAT',
payment_hash: 'a1b2c3d4e5f6...',
received_at: '2024-11-22T12:01:30Z',
amount_msat: 150000000,
crypto_amount: 150.5
},
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/webhook/provider/settlement', 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/webhook/provider/settlement",
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([
'webhook_type' => 'SETTLEMENT_STATUS_UPDATE',
'provider_reference_id' => 'PROVIDER-TXN-20241122-001',
'kotani_reference_id' => 'KOTANI-REF-789',
'status' => 'COMPLETED',
'timestamp' => '2024-11-22T12:05:00Z',
'crypto_payment' => [
'chain' => 'LIGHTNING',
'token' => 'MSAT',
'payment_hash' => 'a1b2c3d4e5f6...',
'received_at' => '2024-11-22T12:01:30Z',
'amount_msat' => 150000000,
'crypto_amount' => 150.5
],
'metadata' => [
'sender_name' => 'John Doe',
'sender_country' => 'KE',
'recipient_name' => 'Jane Smith',
'recipient_country' => 'ZA',
'notes' => 'Family support payment'
]
]),
CURLOPT_HTTPHEADER => [
"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/webhook/provider/settlement"
payload := strings.NewReader("{\n \"webhook_type\": \"SETTLEMENT_STATUS_UPDATE\",\n \"provider_reference_id\": \"PROVIDER-TXN-20241122-001\",\n \"kotani_reference_id\": \"KOTANI-REF-789\",\n \"status\": \"COMPLETED\",\n \"timestamp\": \"2024-11-22T12:05:00Z\",\n \"crypto_payment\": {\n \"chain\": \"LIGHTNING\",\n \"token\": \"MSAT\",\n \"payment_hash\": \"a1b2c3d4e5f6...\",\n \"received_at\": \"2024-11-22T12:01:30Z\",\n \"amount_msat\": 150000000,\n \"crypto_amount\": 150.5\n },\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("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/webhook/provider/settlement")
.header("Content-Type", "application/json")
.body("{\n \"webhook_type\": \"SETTLEMENT_STATUS_UPDATE\",\n \"provider_reference_id\": \"PROVIDER-TXN-20241122-001\",\n \"kotani_reference_id\": \"KOTANI-REF-789\",\n \"status\": \"COMPLETED\",\n \"timestamp\": \"2024-11-22T12:05:00Z\",\n \"crypto_payment\": {\n \"chain\": \"LIGHTNING\",\n \"token\": \"MSAT\",\n \"payment_hash\": \"a1b2c3d4e5f6...\",\n \"received_at\": \"2024-11-22T12:01:30Z\",\n \"amount_msat\": 150000000,\n \"crypto_amount\": 150.5\n },\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/webhook/provider/settlement")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"webhook_type\": \"SETTLEMENT_STATUS_UPDATE\",\n \"provider_reference_id\": \"PROVIDER-TXN-20241122-001\",\n \"kotani_reference_id\": \"KOTANI-REF-789\",\n \"status\": \"COMPLETED\",\n \"timestamp\": \"2024-11-22T12:05:00Z\",\n \"crypto_payment\": {\n \"chain\": \"LIGHTNING\",\n \"token\": \"MSAT\",\n \"payment_hash\": \"a1b2c3d4e5f6...\",\n \"received_at\": \"2024-11-22T12:01:30Z\",\n \"amount_msat\": 150000000,\n \"crypto_amount\": 150.5\n },\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": "Webhook received and processed.",
"data": {}
}{
"success": false,
"message": "Transaction not found",
"data": {}
}Body
application/json
Webhook type identifier
Example:
"SETTLEMENT_STATUS_UPDATE"
Provider reference ID
Example:
"PROVIDER-TXN-20241122-001"
Kotani reference ID
Example:
"KOTANI-REF-789"
Updated settlement status
Available options:
DEPOSIT_INITIATED, DEPOSIT_CONFIRMED, PAYMENT_SENT, PAYMENT_CONFIRMED, SETTLING, COMPLETED, FAILED, REFUNDED Example:
"COMPLETED"
Webhook timestamp (ISO 8601)
Example:
"2024-11-22T12:05:00Z"
Crypto payment details
Show child attributes
Show child attributes
Settlement details (if successful)
Show child attributes
Show child attributes
Failure details (if failed)
Show child attributes
Show child attributes
Refund details (if failed and refund initiated)
Show child attributes
Show child attributes
Transaction metadata
Show child attributes
Show child attributes