IBBA Partner API v1

ILN / Versatec — Sandbox integration guide
Base URL: https://partner-api.ibba.group/api/partner/v1

Sandbox credentials

Sandbox only. Do not use in production. Rotate before go-live.

API Key	`pk_sandbox_iln_9c74a2dfb2da`
Secret	`c1c46252638f0aa2dd972f9d3aa00fb76da52eefd1262fda`
Mode	`sandbox`
Min amount	USD 50.00

Authentication (HMAC)

Every request must include:

Header	Description
`X-Partner-Key`	Your API key
`X-Partner-Timestamp`	Unix seconds (max skew 300s)
`X-Partner-Signature`	`HMAC-SHA256( timestamp + "\n" + raw_body, secret )` hex lowercase

For GET requests the body is empty string.

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

Fees (estimate)

Fee	Value
Rail	1.00% of gross
Network	USD 2.00 (USDT)
Conversion	0.10% of gross

Example gross USD 100.00 → estimated net credit USD 96.90.

Endpoints

Method	Path	Description
GET	`/cardholders/{email}/cards`	List cards for cardholder
POST	`/topups`	Create topup (idempotent by `order_id`)
GET	`/topups/{order_id}`	Get topup status
GET	`/topups`	List topups (paginated)
GET	`/events?since=0`	Poll events (cursor = last id)
POST	`/sandbox/topups/{order_id}/simulate`	Sandbox: simulate `completed` or `expired`
POST	`/sandbox/webhooks/replay`	Sandbox: replay last webhook (needs `webhook_url` configured)

Create topup

POST /topups
Content-Type: application/json

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

network: ERC20 or TRC20. Sandbox returns dummy deposit addresses — do not send real funds.

Sandbox flow

GET /cardholders/{email}/cards
POST /topups with unique order_id
POST /sandbox/topups/{order_id}/simulate body {"event":"completed"}
GET /events?since=0 — receive topup.completed

Webhooks (optional)

Provide your HTTPS webhook URL to IBBA. We POST JSON with headers:

X-Partner-Event: topup.completed
X-Partner-Timestamp: <unix>
X-Partner-Signature: HMAC_SHA256( timestamp + "\n" + body, secret )

Event types: topup.completed, topup.expired.

Errors

HTTP	message
401	missing_partner_auth_headers, invalid_timestamp, timestamp_expired, invalid_api_key, invalid_signature
403	ip_not_allowed, sandbox_only
404	not_found, cardholder_not_found
422	amount_below_minimum, card_not_found, invalid_network

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"

Contact IBBA for live credentials and webhook URL registration.
Doc generated 2026-08-10 — Partner API v1