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 the seller they are checking out with on your marketplace platform. For new buyers it returns a signup_url to start onboarding.

One seller per request

seller_phones must contain exactly one seller. Passing more than one is rejected with an HTTP 400 validation error — check eligibility once per seller the buyer is checking out with.

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. 966567896789

arrayrequiredexactly one seller — passing more than one returns HTTP 400

The seller the buyer is checking out with, as a single-element array holding one phone number in international format without the plus sign. Because a marketplace hosts many sellers, this identifies which seller the buyer is transacting with. Exactly one seller is supported per request; passing more than one is rejected with a validation error.

seller_phonestring

The seller's phone number in international format without the plus sign.e.g. 966543215678

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 in seller_phones.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

Status for the seller passed in seller_phones — a single-element array.

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": "966567896789",
    "seller_phones": ["966543215678"],
    "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": 9180.76,
    "external_user_id": "12955",
    "onboarding_completed": true,
    "customer_name": "Mohammed Al-Rashid",
    "eligibility": "ELIGIBLE",
    "reason": "",
    "sellers": [
      { "phone": "966543215678", "status": "ONBOARDED" }
    ]
  }
}
PreviousError HandlingNext Repayment Plan Options