Get a settlement

GET /api/v1/settlements/:tx_id

Retrieves details of a specific settlement.

Path parameters

Field	Type	Required	Description
tx_id	string	Yes	Bitlipa transaction ID.

Response

Field	Type	Description
tx_id	string	Bitlipa transaction ID.
status	string	Current status (see Status lifecycle).
source_currency	string	Source currency code.
source_amount	integer	Originally requested gross amount (minor units).
expected_source_amount	integer	Gross source amount to be settled (minor units).
destination_currency	string	Destination currency code.
destination_amount	number	Net amount to be / was delivered (after fee).
exchange_rate	number	Applied exchange rate.
platform_fee	number	Fixed platform fee (in destination currency).
fulfillment	string	full, partial, or none.
chain	string	Blockchain network (CAIP-2).
wallet_address	string	Destination wallet.
external_merchant_id	string	Partner's merchant identifier.
external_tx_id	string	Partner's transaction reference (after confirmation).
tx_hash	string	Blockchain transaction hash (when broadcast).
failure_reason	string	Error description (when failed).
created_at	string	Quote creation time (ISO 8601).
confirmed_at	string	Confirmation time (ISO 8601).
executed_at	string	Execution time (ISO 8601).
expires_at	string	Quote expiration (ISO 8601).

Gross vs. net amounts

• source_amount / expected_source_amount are gross amounts (what Bitlipa receives).
• destination_amount is the net amount delivered to the wallet (after platform_fee deduction).

About tx_hash

When present, indicates the transaction was broadcast to the blockchain. This does not mean the transaction is finalized — check status for executed (confirmed) or failed.

Example

PythoncURLResponse — 200 OK

import hashlib, hmac, time, uuid
import requests

API_KEY = "pk_live_xxx"
API_SECRET = b"sk_live_xxx"

tx_id = "tx_abc123def456"
path = f"/api/v1/settlements/{tx_id}"

ts, nonce = str(int(time.time())), str(uuid.uuid4())
sig = hmac.new(
    API_SECRET,
    f"{ts}\nGET\n{path}\n\n".encode(),
    hashlib.sha256,
).hexdigest()

resp = requests.get(
    f"https://api.bitlipa.com{path}",
    headers={
        "Authorization": API_KEY,
        "X-Bitlipa-Timestamp": ts,
        "X-Bitlipa-Nonce": nonce,
        "X-Bitlipa-Signature": sig,
    },
    timeout=10,
)
print(resp.json())

TS=$(date +%s); NONCE=$(uuidgen)
TX_ID=tx_abc123def456
SIG=$(printf '%s\nGET\n/api/v1/settlements/%s\n\n' "$TS" "$TX_ID" \
  | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $2}')

curl "https://api.bitlipa.com/api/v1/settlements/$TX_ID" \
  -H "Authorization: $API_KEY" \
  -H "X-Bitlipa-Timestamp: $TS" \
  -H "X-Bitlipa-Nonce: $NONCE" \
  -H "X-Bitlipa-Signature: $SIG"

{
  "tx_id": "tx_abc123def456",
  "status": "executed",
  "source_currency": "KES",
  "source_amount": 100000,
  "expected_source_amount": 100000,
  "destination_currency": "USDT",
  "destination_amount": 5.20,
  "exchange_rate": 0.0077,
  "platform_fee": 2.50,
  "fulfillment": "full",
  "chain": "eip155:137",
  "wallet_address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "external_merchant_id": "merchant_123",
  "external_tx_id": "UNI-2024-001234",
  "tx_hash": "0x1234567890abcdef...",
  "failure_reason": null,
  "created_at": "2024-01-15T10:30:00Z",
  "confirmed_at": "2024-01-15T10:32:00Z",
  "executed_at": "2024-01-15T10:33:00Z",
  "expires_at": "2024-01-15T10:35:00Z"
}