Authorise Checkout

POST/fina/v1/checkout/authorise

Validates the OTP entered by the buyer and finalises the payment. On success the order moves to AUTHORISED.

Retries & idempotency

Buyers get 3 OTP verification attempts (error 809 on each failure) — use Resend OTP if the code never arrived. Authorising an already-authorised order returns success again rather than an error. Allow a few seconds after Initiate Checkout for the OTP SMS to be dispatched before calling.

Down-payment plans do not go straight to AUTHORISED

When the plan requires a day-zero down payment collected by FINA (prepaid_payment.collection_method "FINA"), the order comes back as AUTHORIZATION_INITIATED with a payment_url. Redirect the buyer to that URL — they pay the down payment on the hosted page and are then redirected to your success or failure redirection URL. Once the payment succeeds FINA POSTs the signed Down Payment Webhook to your webhook_url and the order becomes AUTHORISED; use Reconcile Prepaid Payment if the confirmation is delayed.

Request

order_idstringrequired

The order_id returned by Initiate Checkout.e.g. F26070910AB3XKQ70

otp_codestringrequired

The OTP the buyer received via SMS.e.g. 1234

Response

error_codestring

Numeric code as a string; "0" on success.

errorsarray

Failure details, empty on success.

messagestring

Human-readable status.

object

The authorised order.

order_idstring

FINA's order identifier.

order_reference_idstring

Your order reference.

order_statusenum

AUTHORISED on success. AUTHORIZATION_INITIATED when a FINA-collected down payment is still outstanding — see payment_url.AUTHORISEDAUTHORIZATION_INITIATED

payment_urlstring

Hosted checkout link for the day-zero down payment; empty when nothing is owed upfront.

prepaid_amountnumber

Day-zero down payment owed by the buyer (0 if none).

transaction_idstring

Down-payment transaction reference, when applicable.

repayment_config_idstring

The repayment plan applied to the order.

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.
`808`	INVALID_ORDER	No order was found for the given order_id / order_number.	Use the order_id returned by Initiate Checkout.
`809`	OTP_VERIFICATION_FAILED	The OTP is wrong or has expired. Buyers get 3 verification attempts.	Ask the buyer to re-enter the code, or call Resend OTP and retry Authorise Checkout.
`810`	ANOTHER_ACTION_IN_PROGRESS	A concurrent action on the same order is already in flight.	Wait for the in-flight action to finish, then retry.
`811`	INVALID_ORDER_STATE	The order is not in a state that allows this operation (e.g. authorising an expired order, confirming delivery on an unauthorised order).	Check the order lifecycle; only perform operations valid for the order's current status.
`500`	INTERNAL_ERROR	An unexpected failure occurred on FINA's side.	Retry with backoff; contact FINA support if it persists.

Sandboxhttps://apibe.silqfi.xyz

POST /fina/v1/checkout/authorise

curl -X POST "https://apibe.silqfi.xyz/fina/v1/checkout/authorise" \
  -H "Authorization: bearer FINA_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "F26070910AB3XKQ70",
    "otp_code": "1234"
  }'

FINA_BEARER_TOKEN is provided by the FINA team, per environment. Contact the FINA team for the production base URL.

Response · 200 · Success

{
  "error_code": "0",
  "errors": [],
  "message": "Order authorised successfully",
  "data": {
    "order_id": "F26070910AB3XKQ70",
    "order_reference_id": "ORD-2026-0001",
    "order_status": "AUTHORISED",
    "payment_url": "",
    "prepaid_amount": 0,
    "transaction_id": "",
    "repayment_config_id": "4"
  }
}

PreviousCreate Order Next Reconcile Prepaid Payment