FinaDOCS

Check Eligibility

POST/fina/v1/users/check_eligibility

Check whether a buyer is registered with FINA and has available credit, and whether the buyer may transact with your merchant account. For new buyers it returns a signup_url to start onboarding.

Different envelope

This endpoint uses the { is_error, message, data } envelope. Business failures return HTTP 400 with is_error: true, unlike the checkout endpoints, which return HTTP 200 with a numeric error_code.

Request

buyer_phone_numberstringrequired

Buyer's phone number in international format without the plus sign. Normalised server-side.e.g. 966500000001

language_codeenum

Language baked into the returned signup_url. Defaults to Arabic when omitted.enar

buyer_namestring

Buyer's full name: helps pre-fill onboarding for new buyers. Defaults to the buyer's phone number when omitted.e.g. Mohammed Al-Rashid

vat_numberstring

Buyer's VAT registration number (new buyers).e.g. 300908432978431

buyer_cr_numberstring

Buyer's Commercial Registration number (new buyers).e.g. 7094220000

buyer_nidstring

Buyer's national ID (new buyers).e.g. 2247862341

buyer_emailstring

Buyer's email address (new buyers).e.g. buyer@example.com

buyer_last_6_month_avg_salesstring

Buyer's average monthly sales over the last 6 months, if you hold it, used during credit assessment.

Response

is_errorboolean

false on success.

messagestring

Human-readable status of the lookup.

object

Buyer summary payload.

eligibilityenum

The decision to branch on. ELIGIBLE: show FINA as a payment option. INELIGIBLE: see reason.ELIGIBLEINELIGIBLE

reasonenum

Why the buyer is ineligible. Empty when eligibility is ELIGIBLE. SELLER_NOT_ONBOARDED means the buyer is fine but is not onboarded with the seller you passed.BUYER_NOT_ONBOARDEDSELLER_NOT_ONBOARDED

user_statusenum

Buyer's onboarding state. Pending / NotFound: onboard the buyer via signup_url.ActivePendingNotFound

signup_urlstring

Onboarding URL for Pending / NotFound buyers. Embed it in an iframe (see Embedded Onboarding). Empty for Active buyers.

credit_amountnumber

Buyer's currently available credit, in SAR.

external_user_idstring

FINA's identifier for the buyer. Can be passed to Repayment Plan Options as customer_id.

onboarding_completedboolean

Whether the buyer has finished onboarding.

customer_namestring

Buyer's registered name.

array

Per-seller status for the merchant account the request was authorised as.

Sandbox
POST /fina/v1/users/check_eligibility
curl -X POST "https://apibe.silqfi.xyz/fina/v1/users/check_eligibility" \
  -H "Authorization: bearer FINA_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer_phone_number": "966500000001",
    "language_code": "en"
  }'

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

Response · 200 · Eligible buyer
{
  "is_error": false,
  "message": "User is onboarded successfully, credit summary fetched.",
  "data": {
    "signup_url": "",
    "user_status": "Active",
    "credit_amount": 50000,
    "external_user_id": "12955",
    "onboarding_completed": true,
    "customer_name": "Mohammed Al-Rashid",
    "eligibility": "ELIGIBLE",
    "reason": "",
    "sellers": [
      { "phone": "966567445399", "status": "ONBOARDED" }
    ]
  }
}
PreviousError HandlingNext Repayment Plan Options