Marketplace Integration
Offer FINA as a payment option to buyers purchasing from the sellers on your platform. The flow mirrors the Direct Merchant integration — the same /fina/v1 endpoints — but every call is seller-aware: you identify which of your sellers the buyer is transacting with.
Seller-aware calls
A direct merchant is the seller, so the seller is resolved from your bearer token. A marketplace hosts many sellers, so three calls take an explicit seller identity:
- Check Eligibility — pass
seller_phones(a single-seller array) to get the buyer's onboarding status with that seller. - Repayment Plans — pass
seller_phone_numberandplatform: "MARKETPLACE". - Create Order — include a
payment.sellerblock pluscheckout_flow— your marketplace's own identifier, e.g."AROMA_WHOLESALE".
Your checkout_flow must be registered first
payment.checkout_flow carries your marketplace's own identifier — there is no shared default value. Before integrating, share the identifier you want to use with the FINA team; FINA adds it to the system and validates every Create Order request against it. An unregistered checkout_flow gets the order rejected.
Everything else is identical to Direct Merchant — the order-scoped calls (Authorise, Resend OTP, Confirm Delivery, Add Invoice, Get Customer Invoices) act on an order_id.
Buyer journey
The buyer walks through five steps at your seller's checkout, each backed by one API call:
- 1
Eligibility check
When the buyer reaches the payment page, call Check Eligibility. Active buyers see FINA as a payment option; new buyers are onboarded via the signup_url iframe.
POSTCheck Eligibility - 2
Repayment plan selection
Fetch the repayment plans available for the order amount and let the buyer pick one. Disable plans where has_enough_credits is false.
GETRepayment Plan Options - 3
Order placement
The buyer selects FINA and a repayment plan, then places the order. Initiate Checkout resolves the plan, creates the order, and sends an OTP to the buyer via SMS.
POSTInitiate Checkout - 4
OTP entry
Prompt the buyer for the OTP. If it never arrived, resend it — up to 3 times per order.
POSTResend OTP - 5
Authorisation
Submit the OTP with the order_id. On success the order is confirmed and the buyer's journey ends; on failure the buyer can retry (3 attempts).
POSTAuthorise Checkout
Post-order operations — your side
The buyer's journey ends at authorisation. These calls happen later, from your backend, as the seller fulfils the order — the buyer never sees them:
Order lifecycle
Orders move through these statuses; each order operation is only valid in specific states (otherwise you get error 811):
- CREATED — Initiate Checkout succeeded; OTP sent to the buyer via SMS.
- AUTHORIZATION_INITIATED — Down-payment plans only — OTP verified; the FINA-hosted down payment is pending at payment_url.
- AUTHORISED — Buyer's OTP verified via Authorise Checkout; payment confirmed (and any FINA-collected down payment settled).
- OUT_FOR_DELIVERY — Order handed to delivery (when applicable).
- DELIVERED — Merchant confirmed delivery with proof of delivery.
Exceptions
- EXPIRED — Order was not authorised within ~30 minutes of creation.
- CANCELLED — Order was cancelled before completion.
- REFUNDED — Order was refunded after authorisation.
Unauthorised orders expire after ~30 minutes. Buyers get 3 OTP attempts and 3 resends per order.