Confirm a settlement¶

POST /api/v1/settlements/confirm

Confirms a quoted settlement and initiates execution.

Call only after merchant acceptance

Only call this endpoint after the merchant has accepted the quote. The partner should create their internal transaction record at this point using the expected_source_amount from the quote.

Request body¶

Field	Type	Required	Description
`tx_id`	string	Yes	Bitlipa transaction ID from the quote.
`external_tx_id`	string	Yes	Partner's internal transaction reference.
`callback_url`	string	Yes	HTTPS endpoint for status callbacks.

Response¶

Field	Type	Description
`tx_id`	string	Bitlipa transaction ID.
`status`	string	`processing`.
`confirmed_at`	string	Confirmation timestamp (ISO 8601).

tx_hash is not returned here

The tx_hash is not available at confirmation time. It is provided via callback or GET endpoint once the blockchain transaction is broadcast. The presence of tx_hash indicates the transaction was broadcast to the network, not that it is finalized — monitor status for executed or failed.

Example¶

PythoncURLResponse — 200 OK

import hashlib, hmac, json, time, uuid
import requests

API_KEY = "pk_live_xxx"
API_SECRET = b"sk_live_xxx"

path = "/api/v1/settlements/confirm"
body = json.dumps({
    "tx_id": "tx_abc123def456",
    "external_tx_id": "UNI-2024-001234",
    "callback_url": "https://api.partner.com/webhooks/bitlipa",
}, separators=(",", ":"))

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

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

TS=$(date +%s); NONCE=$(uuidgen)
BODY='{"tx_id":"tx_abc123def456","external_tx_id":"UNI-2024-001234","callback_url":"https://api.partner.com/webhooks/bitlipa"}'
SIG=$(printf '%s\nPOST\n/api/v1/settlements/confirm\n\n%s' "$TS" "$BODY" \
  | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $2}')

curl -X POST https://api.bitlipa.com/api/v1/settlements/confirm \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Bitlipa-Timestamp: $TS" \
  -H "X-Bitlipa-Nonce: $NONCE" \
  -H "X-Bitlipa-Signature: $SIG" \
  -d "$BODY"

{
  "tx_id": "tx_abc123def456",
  "status": "processing",
  "confirmed_at": "2024-01-15T10:32:00Z"
}