Documentation

Netract API reference

Every ledger movement in Netract is available programmatically. Requests are JSON over HTTPS, authenticated with an organization API key, and writes are idempotent on your supplied reference.

Authentication

curl https://api.netract.io/v1/invoices \
  -H "Authorization: Bearer ntr_live_••••••••" \
  -H "Content-Type: application/json" \
  -d '{ "client_name": "Northwind Labs Inc.", "currency": "USD", "amount": 42000 }'

Endpoints

POST/v1/invoices

Create an international invoice

Reserves a collection reference on the UK corporate node for the requested currency, persists the invoice in DRAFT → SENT, and returns a public tracking token your client can open without authentication.

Request

{
  "client_name": "Northwind Labs Inc.",
  "client_email": "ap@northwindlabs.com",
  "client_country": "US",
  "currency": "USD",
  "amount": 42000.00,
  "due_date": "2026-04-18",
  "description": "Platform engineering retainer — March"
}

Response

{
  "id": "inv_9c1f4ad2",
  "invoice_number": "INV-2041",
  "status": "SENT",
  "collection_reference": "NTR-8F42-2041",
  "tracking_token": "9c1f4ad2b77e41c0",
  "virtual_account": {
    "currency": "USD",
    "bank_name": "Airwallex UK",
    "account_number": "41628037",
    "routing_number": "026073150",
    "swift_bic": "AIPTGB21XXX"
  }
}

POST/api/public/webhooks/payment-collection

Inbound settlement webhook

Called by the global banking partner when a Western payer settles. The request must carry an HMAC-SHA256 signature over the raw body. On success the invoice moves to PAID, the organization vault balance is credited, and an INBOUND_INVOICE transaction is written atomically.

Request

POST /api/public/webhooks/payment-collection
x-netract-signature: sha256=<hex hmac of raw body>
content-type: application/json

{
  "event": "payment.settled",
  "collection_reference": "NTR-8F42-2041",
  "currency": "USD",
  "amount": 42000.00,
  "rail": "FEDWIRE",
  "provider_reference": "AWXPAY-8842K",
  "settled_at": "2026-03-31T14:02:11Z"
}

Response

{
  "received": true,
  "invoice_status": "PAID",
  "transaction_id": "txn_5f81aa0c",
  "vault_balance": { "currency": "USD", "available": 184250.00 }
}

GET/v1/fx/quote

Quote a localized payout

Returns the live floating conversion rate, the platform processing fee, and the net local amount. Quotes are advisory until confirmed on the payout call, which re-prices and records the executed rate.

Request

GET /v1/fx/quote?currency=USD&amount=9000

Response

{
  "currency": "USD",
  "gross_amount": 9000.00,
  "fee_rate": 0.01,
  "fee_amount": 90.00,
  "net_source_amount": 8910.00,
  "rate": 141.8620,
  "local_currency": "ETB",
  "local_amount": 1263991.02
}

POST/v1/withdrawals

Trigger an on-demand Birr payout

Verifies the caller's organization, asserts balance sufficiency, deducts the platform fee, converts at the executed rate, and dispatches the transfer to the selected local channel. Writes an OUTBOUND_WITHDRAWAL transaction with the rate and fee stored immutably.

Request

{
  "currency": "USD",
  "amount": 9000.00,
  "channel": "TELEBIRR",
  "account_identifier": "0912345678",
  "account_name": "Addis Systems PLC"
}

Response

{
  "transaction_id": "txn_5518qa",
  "status": "COMPLETED",
  "fee_amount": 90.00,
  "rate": 141.8620,
  "local_amount": 1263991.02,
  "provider_reference": "CHAPA-TX-5518QA",
  "channel": "TELEBIRR"
}

Invoice state machine

State	Meaning
DRAFT	Created, not yet issued to the payer.
SENT	Issued with an active collection reference and tracking link.
PAID	Settled in full; funds credited to the FX retention vault.
PARTIALLY_WITHDRAWN	Some of the settled proceeds have been localized.
FULLY_WITHDRAWN	All settled proceeds localized; invoice lifecycle closed.

Get API access KYB requirements