IBBA Partner API v1

Deposit wallets — how you get one

Fixed per card The address is permanent for that card and network. Later calls for the same card return the same address, it does not expire, and you may cache it. GET /topups/{order_id} returns it again at any time.

Idempotent Re-sending the same order_id returns the existing topup — it never creates a second one.

The address does not identify the order. Two open topups on the same card share one address, so a deposit is matched to an order by network + exact amount, newest first, within a 48 h window. Send the exact amount: do not round it and do not batch several topups into one transfer. If nothing matches, the deposit is held for manual review rather than credited to a guess.

How the address is provisioned

1. Cardholder has an Interlace card (issuer_id = 3) in CardHub
2. Your first POST /topups for that card creates a dedicated wallet, binds it to the card's Interlace UUID and stores the address — automatically, no IBBA intervention
3. ILN shows that address in their topup UI and reuses it forever
4. Payer sends USDT → Ezequiel detects → sweeps → credits the Interlace card
5. topup.completed fires with the final amounts

Typical integration

1. GET /cardholders/{email}/cards — pick an Interlace card
2. POST /topups — receive deposit_address, chain and fees
3. Payer funds it with the exact amount; wait for topup.completed or poll

Issuer rails (important)

Money flow (end-to-end)

A) Fixed wallet — provisioned automatically by your first POST /topups

B) POST /topups (CN-01) — the integration path

Step-by-step

Do not send real funds to sandbox addresses. Live addresses are fixed per card and network — shared by every topup on that card, which is why the exact amount is what identifies the payment.

Webhooks & events

A webhook URL is registered on the ILN live credential (https://iln.law/card/webhook), so deliveries are on. You can still integrate by polling GET /events?since={last_id} or GET /topups/{order_id} — both are populated whether or not webhooks are on, and polling is the safer belt-and-braces option while you build. To change the URL, send it to IBBA.

We POST JSON:

X-Partner-Event: topup.completed
X-Partner-Timestamp: <unix seconds>
X-Partner-Signature: HMAC-SHA256( timestamp + "\n" + raw_body, secret )  // hex lowercase
Content-Type: application/json

Partner-facing events (what you integrate)

topup.completed payload (example)

{
  "event": "topup.completed",
  "order_id": "iln-order-001",
  "status": "completed",
  "cardholder_email": "cardholder@example.com",
  "card_id": 12345,
  "amount": "100.00",
  "currency": "USD",
  "network": "ERC20",
  "sandbox": false,
  "fee_breakdown": {
    "gross_amount": "100.00",
    "rail_fee": "1.00",
    "network_fee": "2.00",
    "conversion_fee": "0.10",
    "fees_total": "3.10",
    "estimated_net_credit": "96.90"
  },
  "net_credited": "96.90",
  "gross_amount": "100.00",
  "fees_total": "3.10"
}

Internal pipeline (for ops understanding — not partner webhooks)

Polling — the path to build on today

GET /events?since={last_id} — cursor feed of the same events. Start at since=0, then pass back the next_cursor from each response. Events are recorded whether or not a webhook URL is configured, so this works right now; a single topup can also just be re-read with GET /topups/{order_id} until status is completed.

Sandbox: POST /sandbox/webhooks/replay re-sends the last event to your configured URL.

Authentication (HMAC)

Every request must include:

For GET requests the body is the empty string.

signature = HMAC_SHA256( timestamp + "\n" + body, secret )

Endpoints

Create topup (= create deposit wallet)

POST /topups
Content-Type: application/json

{
  "order_id": "iln-test-001",
  "cardholder_email": "cardholder@example.com",
  "card_id": 12345,
  "amount": 100.00,
  "network": "ERC20"
}

Success response (wallet fields highlighted)

{
  "success": true,
  "topup": {
    "order_id": "iln-test-001",
    "status": "pending",
    "cardholder_email": "cardholder@example.com",
    "card_id": 12345,
    "amount": "100.00",
    "currency": "USD",
    "network": "ERC20",
    "sandbox": false,
    "deposit_address": "0xA327Ae6Fb7529c7bE9073f174F58f2659Ae5ABb2",
    "chain": "ETH",
    "qr_code": "https://panel.quikipay.com/storage/qr_codes/d69460f3…bce8.png",
    "fee_breakdown": {
      "gross_amount": "100.00",
      "rail_fee": "1.00",
      "network_fee": "2.00",
      "conversion_fee": "0.10",
      "fees_total": "3.10",
      "estimated_net_credit": "96.90",
      "note": "Estimado. El valor final se informa en topup.completed."
    },
    "expires_at": "2026-08-26T15:21:47+00:00",
    "completed_at": null,
    "created_at": "2026-08-26T14:36:47+00:00"
  }
}

• deposit_address — the wallet to fund (ERC20 = ETH address; TRC20 = TRON address)
• chain — ETH or TRON
• qr_code — a PNG URL you can render directly; null in sandbox
• expires_at — ~45 min from creation. Nothing changes server-side when it passes: the topup stays pending, so stop waiting and create a new order_id
• fee_breakdown.estimated_net_credit — estimate; final in topup.completed

Fees (estimate)

Legacy POST /topups example gross USD 100.00 → estimated net ~USD 96.90. Final values arrive in topup.completed.

Sandbox credentials

Sandbox only. Do not use in production. Do not send real crypto to sandbox addresses.

Sandbox flow

1. GET /cardholders/{email}/cards
2. POST /topups — inspect deposit_address (dummy)
3. POST /sandbox/topups/{order_id}/simulate body {"event":"completed"}
4. GET /events?since=0 — receive topup.completed

Example (curl + bash)

BASE="https://partner-api.ibba.group/api/partner/v1"
KEY="pk_sandbox_iln_9c74a2dfb2da"
SECRET="c1c46252638f0aa2dd972f9d3aa00fb76da52eefd1262fda"
TS=$(date +%s)
BODY='{"order_id":"demo-1","cardholder_email":"...","card_id":123,"amount":100,"network":"ERC20"}'
SIG=$(printf '%s\n%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')
curl -sS "$BASE/topups" -H "Content-Type: application/json" \
  -H "X-Partner-Key: $KEY" -H "X-Partner-Timestamp: $TS" -H "X-Partner-Signature: $SIG" \
  -d "$BODY"
# Response includes topup.deposit_address — that is the wallet.

Errors