Installment plans

To retrieve installment plans and pay with one:

Step 1: Get available banks

Whenever you are ready for production, use the following production API endpoint URL instead.

curl -X 'GET'
  'https://test-api.kashier.io/merchant/installments/banks/plans?mid=MID-0000-000&amount=500'

Full parameter and response reference → Get available banks.

Query parameters

BNPL availability flags

Alongside banks, the response carries boolean flags showing which BNPL providers are available for the merchant, computed from real provisioning for that merchant:

These BNPL providers use their own dedicated payment flow — they are not paid via the installments.planId card path described in Step 3 below.

Step 2: Get plans for a specific bank

Whenever you are ready for production, use the following production API endpoint URL instead.

curl -X 'GET'
  'https://test-api.kashier.io/merchant/installments/plans?mid=MID-0000-000&amount=10000&currency=EGP&fiId=FI-13'

Full parameter and response reference → Get plans for specific bank.

Query parameters

The response renames the Step 1 minimum: what Step 1 calls minimunInstallmentAmount is returned here as Minimum installment amount.

Step 3: Pay with a plan

Once you have a Merchant Plan ID (e.g. INSPLAN-53) from Step 2, pay with it by adding installments.planId to a normal card payment request. This is the same POST /v3/orders request used for any card payment — the plan is validated before the card is charged.

Whenever you are ready for production, use the following production API endpoint URL instead.

curl -X 'POST' 'https://test-fep.kashier.io/v3/orders/' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Kashier-Hash: your_generated_hash' \
  -d '{
      "apiOperation": "PAY",
      "installments": {
          "planId": "INSPLAN-53"
      },
      "paymentMethod": {
          "type": "CARD",
          "card": {
              "number": "5484571234560000",
              "expiry": {
                  "month": "05",
                  "year": "26"
              },
              "nameOnCard": "TEST",
              "securityCode": "100"
          }
      },
      "order": {
          "reference": "PM-89451648984",
          "amount": "10000",
          "currency": "EGP",
          "description": ""
      },
      "interactionSource": "ECOMMERCE",
      "reconciliation": {
          "webhookUrl": "https://your-call-back-url.com",
          "merchantRedirect": "https://your-call-back-url.com",
          "redirect": true
      },
      "customer": {
          "reference": "24"
      },
      "merchantId": "MID-0000-000"
  }'

Body parameters

How the plan is validated

When installments is present, the payment is treated as an installment agreement (as opposed to a regular card charge), and the plan is validated before the card is charged:

1. installments.planId must match a known master plan. This check runs in every mode, test included.
2. The plan must be active.
3. The card's BIN must fall inside the plan's binRanges (the same ranges returned as Supported BINs in Step 2).
4. The plan must actually be provisioned and active for your merchant account.

If any check fails, the request is rejected before the card is charged, with one of the error codes below.

Validate the card BIN against Supported BINs in your own UI before submitting, so the customer is not shown a plan their card cannot use.

Pay-time errors

Response

Once validation passes, the normal card payment flow runs unchanged — including 3DS, capture, and the response shape. See Customized card form for the full response structure, and 3D Secure handling for the 3DS redirect flow.

You can find how much the customer will pay monthly for every plan in the Installment amount per month parameter of the Step 2 response.

BNPL installment providers

Beyond bank card installments (Steps 1–3 above), Kashier supports several standalone BNPL (buy-now-pay-later) providers. Each is its own paymentMethod.type, with its own dedicated payment flow — none of them are paid via the installments.planId card path.

Availability

Of these, three are surfaced as availability flags on the Step 1 banks response — allowValu, allowOcto, and allowSouhoola. Mogo, Tru, Forsa, and Contact don't have a documented availability flag of their own on that response; whether one of them is usable for a given merchant depends on that merchant's own provisioning rather than a flag here.

Contact

Contact (paymentMethod.type: "contact", provider contact online / contact_pos on POS) is a BNPL provider, not a cash or kiosk method. It's initiated with get_categories / validate_balance and then progresses through tenure selection, OTP, pay, and refund (including a dedicated otp_refund step).