Create Order
/fina/v1/checkout/initiateInitiates a BNPL checkout session on behalf of one of your marketplace sellers, creates the order, and triggers an OTP SMS to the buyer. As a marketplace platform you identify both the buyer and the seller (sub-merchant) fulfilling the order.
Buyer & seller
Marketplace checkout involves three parties: your platform (authenticated by the bearer token), the buyer (payment.buyer.phone_number), and the seller — the sub-merchant on your marketplace fulfilling the order — identified by payment.seller.phone_number. The seller must be onboarded to FINA before you can transact on their behalf.
Registering your checkout_flow
payment.checkout_flow carries your marketplace's own identifier — not a fixed value. Share the identifier you want to use with the FINA team while integrating; FINA adds it to the system and validates every Create Order request against it. The examples on this page use "AROMA_WHOLESALE", the marketplace from the interactive demo.
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 tenure 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.
Request
The checkout payload.
Integration channel. Always "MARKETPLACE" for this guide.MARKETPLACE
Your marketplace's identifier — e.g. "AROMA_WHOLESALE". Share the value you want to use with the FINA team while integrating: FINA adds it to the system and validates every Create Order request against it. Requests carrying an unregistered checkout_flow are rejected.
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.
The seller (sub-merchant) on your marketplace fulfilling this order. Required for marketplace checkout — this is what distinguishes it from direct-merchant checkout, where the merchant is always the seller.
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": {
"buyer": {
"phone_number": "966567896789"
},
"seller": {
"phone_number": "966543215678"
},
"order": {
"order_reference_id": "ORD-REF-1013",
"total_amount": 515.00,
"discount_amount": 0,
"tax_amount": 65.22,
"shipping_amount": 15.00,
"items": [
{
"title": "Test Product",
"sku": "SKU-001",
"quantity": 1,
"unit_price": 434.78,
"total_amount": 500.00,
"tax_amount": 65.22,
"discount_amount": 0,
"reference_id": "ITEM-001",
"size": "M",
"size_type": "standard",
"color": "black",
"category": "apparel",
"product_material": "cotton",
"product_url": "https://example.com/p/sku-001",
"image_url": "https://example.com/img/sku-001.jpg"
}
]
},
"billing_address": {
"first_name": "Test",
"address": "King Fahd Rd",
"city": "Riyadh",
"zip": "12211",
"phone_number": "966594298432",
"country_code": "SA",
"country_name": "Saudi Arabia"
},
"shipping_address": {
"first_name": "Test",
"address": "King Fahd Rd",
"city": "Riyadh",
"zip": "12211",
"phone_number": "966594298432",
"country_code": "SA",
"country_name": "Saudi Arabia"
},
"platform": "MARKETPLACE",
"currency_code": "SAR",
"country_code": "SA",
"description": "Test marketplace checkout",
"checkout_flow": "AROMA_WHOLESALE"
}
}'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-REF-1013",
"order_status": "CREATED",
"payment_url": "",
"prepaid_amount": 0,
"transaction_id": "",
"repayment_config_id": "4"
}
}