Initiate Checkout
/fina/v1/checkout/initiateInitiates a BNPL checkout session for the buyer's chosen repayment plan, creates the order, and triggers an OTP SMS to the buyer.
Plan selection & consistency
payment.repayment_config_id drives plan selection. When commission_config.use_config is true, commission_config.tenure_in_days must match the selected plan's length and merchant_share must match the value sent to Repayment Plan Options — otherwise the order is rejected with error 877. If repayment_config_id is omitted, FINA falls back to the default plan for commission_config.tenure_in_days.
Down-payment plans
If the chosen plan returned requires_prepaid_collection: true, the buyer owes the day-zero prepaid_amount upfront. Indicate how it is collected via payment.prepaid_payment.collection_method: "FINA" (FINA collects it from the buyer on a hosted payment page) or "MERCHANT" (you collect it and pass the reference in payment.prepaid_utr). For FINA collection, also send success_redirection_url and failure_redirection_url (always as a pair, both on the domain whitelisted with FINA for embedded onboarding) — the buyer lands on one of them after the hosted payment — and optionally webhook_url + webhook_secret for a signed server-to-server confirmation. The amount is echoed back in the response.
Request
The checkout payload.
Integration channel. Always "MERCHANT_DIRECT" for this guide.MERCHANT_DIRECT
Order currency. Optional — SAR is the only supported currency.
Order country. Optional — SA is the only supported country.
The buyer's chosen plan from Repayment Plan Options. Falls back to the default plan when omitted.
Free-text order description.
The buyer placing the order.
Your merchant details. Optional — FINA resolves the seller from your bearer token and overwrites anything you send here.
Order contents and totals.
Billing address.
Shipping address.
Commission arrangement for the order.
Required when the selected plan has requires_prepaid_collection: true.
Your payment reference for the collected down payment — required when collection_method is MERCHANT.
Response
Numeric code as a string; "0" on success.
Failure details, empty on success.
Human-readable status.
The created order.
FINA's order identifier — used by all subsequent order operations.
Echo of your reference.
Always "CREATED" on success. OTP has been sent to the buyer.
Payment link for FINA-collected down payments; empty otherwise.
Day-zero down payment owed by the buyer (0 if none).
Down-payment transaction reference, when applicable.
The plan actually applied to the order — echoes your selection, or the default plan when you omitted one.
Errors
Returned as HTTP 200 with a non-zero error_code — see Error Handling.
| Code | Name | Description | Resolution |
|---|---|---|---|
400 | INVALID_PARAMS | A required field is missing or a value failed validation (e.g. totals don't reconcile, invalid phone format, unknown field value). | Check errors[] for the failing field. Ensure order.total_amount equals the sum of items[].total_amount plus shipping_amount minus discount_amount. |
801 | ORDER_ALREADY_EXISTS | An order with the same order_reference_id already exists. order_reference_id is the idempotency anchor. | Use a fresh order_reference_id for new orders; reuse the existing order for retries. |
802 | SELLER_NOT_VALID | The merchant resolved from the bearer token is not recognised for this operation. | Verify the bearer token belongs to the correct merchant account. |
803 | SELLER_INACTIVE | The merchant account exists but is not active. | Contact the FINA team to activate the merchant account. |
804 | ANOTHER_CHECKOUT_IN_PROGRESS | A concurrent checkout for the same buyer is already in flight. | Wait for the in-flight checkout to finish, then retry. |
805 | CUSTOMER_NOT_ONBOARDED | The buyer has not completed FINA onboarding. | Run Check Eligibility and take the buyer through the signup_url onboarding flow. |
806 | CUSTOMER_CREDIT_LIMIT_EXCEEDED | The buyer's available credit does not cover this order. | Offer a plan with a down payment, reduce the order amount, or hide FINA for this purchase. |
876 | MISSING_PLAN_SELECTION | No repayment plan could be resolved for the order. | Pass a repayment_config_id returned by Repayment Plan Options. |
877 | INVALID_PLAN_SELECTION | The repayment_config_id is invalid, or commission_config.tenure_in_days / merchant_share do not match the selected plan. | Send a repayment_config_id from Repayment Plan Options and keep commission_config consistent with that plan. |
878 | PLAN_NOT_CONFIGURED | No repayment plan is configured for the requested tenure_in_days / channel. | Only offer plans returned by Repayment Plan Options; contact FINA to configure more. |
881 | BG_DOC_EXPIRED | The buyer's credit agreement document has expired. | Send the buyer through onboarding again via Check Eligibility's signup_url. |
500 | INTERNAL_ERROR | An unexpected failure occurred on FINA's side. | Retry with backoff; contact FINA support if it persists. |
https://apibe.silqfi.xyzcurl -X POST "https://apibe.silqfi.xyz/fina/v1/checkout/initiate" \
-H "Authorization: bearer FINA_BEARER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"payment": {
"currency_code": "SAR",
"country_code": "SA",
"description": "Wholesale coffee order",
"platform": "MERCHANT_DIRECT",
"repayment_config_id": 4,
"buyer": {
"phone_number": "966500000001"
},
"order": {
"order_reference_id": "ORD-2026-0001",
"source_order_number": "SRC-ORD-2026-0001",
"total_amount": 100,
"sub_total": 80,
"tax_amount": 12,
"shipping_amount": 8,
"discount_amount": 0,
"items": [
{
"title": "Arabica Coffee Beans 1kg",
"reference_id": "SKU-CFE-1KG",
"sku": "SKU-CFE-1KG",
"quantity": 2,
"unit_price": 40,
"tax_amount": 12,
"tax_percentage": 15,
"total_amount": 92,
"size": "1kg"
}
]
},
"billing_address": {
"first_name": "Mohammed",
"last_name": "Al-Rashid",
"phone_number": "966500000001",
"address": "King Fahd Road, Al Olaya",
"city": "Riyadh",
"region": "Riyadh",
"zip": "12211",
"country_code": "SA",
"country_name": "Saudi Arabia"
},
"shipping_address": {
"first_name": "Mohammed",
"last_name": "Al-Rashid",
"phone_number": "966500000001",
"address": "King Fahd Road, Al Olaya",
"city": "Riyadh",
"region": "Riyadh",
"zip": "12211",
"country_code": "SA",
"country_name": "Saudi Arabia"
},
"commission_config": {
"use_config": true,
"tenure_in_days": 30,
"merchant_share": 50
},
"prepaid_payment": {
"collection_method": "FINA",
"success_redirection_url": "https://merchant.example/checkout/fina/success",
"failure_redirection_url": "https://merchant.example/checkout/fina/failure",
"webhook_url": "https://api.merchant.example/webhooks/fina/prepaid",
"webhook_secret": "whsec_9f2c1b4e"
}
}
}'FINA_BEARER_TOKEN is provided by the FINA team, per environment. Contact the FINA team for the production base URL.
{
"error_code": "0",
"errors": [],
"message": "Order created successfully",
"data": {
"order_id": "F26070910AB3XKQ70",
"order_reference_id": "ORD-2026-0001",
"order_status": "CREATED",
"payment_url": "",
"prepaid_amount": 26.25,
"transaction_id": "",
"repayment_config_id": "4"
}
}