Skip to main content
POST
/
api
/
v3
/
deposit
/
crypto-bridge
Create crypto bridge deposit (Cross-border remittances)
curl --request POST \
  --url https://sandbox-api.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"
  }
}
'
{
  "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"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
customer_key
string
required

Customer key (Provider customer ID in Kotani system)

Example:

"PROVIDER_CUSTOMER_123"

​
provider_reference_id
string
required

Provider's unique transaction reference ID

Example:

"PROVIDER-TXN-20241122-001"

​
amount
number
required

Source fiat amount

Example:

1000

​
source_currency
string
required

Source fiat currency code

Example:

"KES"

​
wallet_id
string
required

Kotani wallet ID to use for transaction

Example:

"KOTANI_WALLET_ID"

​
transaction_type
enum<string>
required

Type of bridge transaction

Available options:
cross_border,
bridge,
chain_settlement
Example:

"cross_border"

​
chain
enum<string>
required

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
enum<string>
required

Token/asset to use

Available options:
CUSD,
USDC,
USDT,
BUSD,
HASH,
HBAR,
USDGLO,
CKES,
CGHS,
MSAT
Example:

"MSAT"

​
crypto_payment
object
required

Crypto payment details (pre-generated invoice or address)

​
settlement
object
required

Settlement details for recipient

​
callback_url
string
required

Callback URL for status updates

Example:

"https://api.provider.com/webhooks/kotani/status"

​
rate_id
string

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"

​
metadata
object

Additional transaction metadata

Response

​
success
boolean
Example:

true

​
message
string
Example:

"Crypto bridge deposit initiated successfully."

​
data
object