Cross-Border Payments
Send international payments with locked-in FX rates. The flow is: quote → beneficiary → transfer → webhook.
1. Request a quote
POST /v1/quotes
A quote locks an exchange rate and fee for a limited window (typically 15 minutes, returned as expires_at).
cURL
curl https://api.finlogic.com/v1/quotes \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"source_currency": "USD",
"destination_currency": "NGN",
"amount": 1000,
"amount_type": "source"
}'
| Field | Description |
|---|---|
| source_currency | ISO 4217 code of the currency you are sending. |
| destination_currency | Currency the beneficiary receives. |
| amount | Decimal amount. |
| amount_type | source to fix what you send, destination to fix what they receive. |
2. Create a beneficiary
POST /v1/beneficiaries
cURL
curl https://api.finlogic.com/v1/beneficiaries \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"type": "bank_account",
"name": "Adaeze Okafor",
"country": "NG",
"currency": "NGN",
"account_number": "0123456789",
"bank_code": "058"
}'
Beneficiaries are validated on creation (account name resolution where the rail supports it) and can be reused for future transfers.
3. Create the transfer
POST /v1/transfers
cURL
curl https://api.finlogic.com/v1/transfers \
-H "Authorization: Bearer sk_test_..." \
-H "Idempotency-Key: 1e7a3c2b-..." \
-H "Content-Type: application/json" \
-d '{
"quote_id": "qt_8f2k1x9d",
"beneficiary_id": "bn_71xk2mp0",
"reference": "INV-2041",
"narration": "July invoice settlement"
}'
Response · 201 Created
{
"id": "tr_9x2m1kd8",
"status": "processing",
"quote_id": "qt_8f2k1x9d",
"beneficiary_id": "bn_71xk2mp0",
"source_amount": 1000,
"source_currency": "USD",
"destination_amount": 1534500,
"destination_currency": "NGN",
"reference": "INV-2041",
"created_at": "2026-07-10T14:01:09Z"
}
4. Track status
GET /v1/transfers/{id}
| Status | Meaning |
|---|---|
| processing | Accepted and moving through the settlement rail. |
| completed | Funds delivered to the beneficiary. |
| failed | Delivery failed. Funds are returned to your wallet and failure_reason is populated. |
| on_hold | Compliance review in progress; resolves to completed or failed. |
Best practice: rely on the
transfer.completed / transfer.failed webhooks for final state instead of polling.