Learn how your customers holding a Fawry Yellow Card can pay in installments using only their mobile number and an OTP — with no card details required at checkout.
Introduction
MyFawry Taqseet is a standalone payment method that enables end customers holding a Fawry Yellow Card to complete installment payments directly on your checkout. Instead of entering card details (PAN, expiry date, and CVV), the customer selects an installment plan, enters the mobile number linked to their Yellow Card, and confirms the payment with a one-time password (OTP).
This method is designed to give Yellow Card holders a faster, simpler installment experience while keeping card data completely off your checkout page. After successful OTP confirmation, the payment follows the same downstream payment and settlement flow as the existing Yellow Card installment experience — no additional integration is required on your side beyond the standard payment verification.
How It Works
Method display: When your customer reaches checkout, FawryPay checks whether your merchant account is enabled for MyFawry Taqseet / Yellow Card installments in the promo engine. Only if enabled, the MyFawry Taqseet tab is displayed as a standalone payment method.
Plan selection On selecting MyFawry Taqseet, the customer is shown the available installment plans for the Yellow Card account type, sourced from the promo engine, and selects one.
Mobile number entry The card-info inputs (PAN, expiry, CVV) are not shown. Instead, the customer enters the mobile number linked to their Yellow Card. The number format is validated inline before submission.
Eligibility validation FawryPay verifies that the mobile number is linked to a Yellow Card and that the installment service is available for that customer on the selected plan (active service, plan eligibility, and sufficient limit).
OTP confirmation If validation succeeds, an OTP is sent to the customer's mobile number. The customer enters the OTP to confirm and complete the payment.
Settlement After successful OTP confirmation, the transaction follows the same downstream payment and settlement flow as the existing Yellow Card installment experience. Verify the final state via the Get Payment Status V2 API or the Server Notification V2 webhook.
1. Make a MyFawry Taqseet Charge Request
Whenever your client selects MyFawry Taqseet as the preferred payment method and picks an installment plan, your application should submit the client's mobile number and the selected plan along with the charge details to your server. Your server then constructs the charge request and submits it to FawryPay.
Staging endpoint
Meanwhile, whenever you are ready for production, you should use the following production API endpoint URL instead
Detailed description of the parameters that you need to incorporate into your POST request are given in the
table below.
Parameter
type
required
Description
merchantCode
String
required
The merchant code provided by FawryPay team during the account setup.
merchantRefNum
Integer
required
The unique reference number for the charge request in merchant system.
customerProfileId
Integer
optional
The unique customer profile ID in merchant system. This can be the user ID.
paymentMethod
String
required
Payment Method: MYFAWRYTAQSEET.
installmentPlanId
String
required
The identifier of the installment plan selected by the customer, as returned by the promo engine for the Yellow Card account type.
customerName
String
optional
The customer name in merchant system.
customerMobile
String
required
The customer mobile in merchant system: 01xxxxxxx
customerEmail
String
optional
The customer e-mail in merchant system: test@email.com
amount
Decimal
required
The charge amount: must in the form of xx.xx
description
String
required
Item description.
orderWebHookUrl
URL String
optional
WebHook Url used to notify your application back end when an event happens in this order like order paid , expired or refund for more details about the request message please check Server To Server Notification V2
language
String
required
Language: "ar-eg" - "en-gb". This key will control the language of the notification message to the customer
chargeItems
JSON Array
itemId
String
required
The ID for the charge item
description
String
required
Description of charge item.
price
Decimal
required
Price per unit charge item.
quantity
Decimal
required
Quantity of the charge items.
signature
String
required
The SHA-256 digested for the following concatenated string "merchantCode + merchantRefNum + customerProfileId (if exists) + paymentMethod + amount (two decimals) + secureKey"
Sample Request Data
{
"merchantCode": "1tSa6uxz2nTwlaAmt38enA==",
"merchantRefNum": "2312465464",
"paymentMethod": "MYFAWRYTAQSEET",
"customerMobile": "01234567891", // mobile linked to the Yellow Card
"installmentPlanId": "YC-12M-001", // plan selected from the promo engine
"customerProfileId": "777777",
"customerName": "Ahmed Ali",
"customerEmail": "example@gmail.com",
"amount": "580.55",
"currencyCode": "EGP",
"language": "ar-eg",
"chargeItems": [
{
"itemId": "897fa8e81be26df25db592e81c31c",
"description": "Item Description",
"price": "580.55",
"quantity": "1"
}
],
"signature": "2ca4c078ab0d4c50ba90e31b3b0339d4...",
"description": "Example Description"
}
2. OTP Confirmation
When the submitted mobile number matches a linked Yellow Card and the installment service is available for that customer on the selected plan, FawryPay sends an OTP to the customer's mobile number. The customer enters the OTP on the checkout to confirm and complete the payment.
The OTP behavior (wrong OTP, expired OTP, resend, and timeout) follows the existing standard FawryPay OTP handling and messaging — there is no Taqseet-specific OTP logic to implement.
After OTP success: the transaction proceeds through the same downstream payment and settlement flow as the existing Yellow Card installment experience. Nothing changes for your reconciliation or settlement processes.
3. Verify the Payment
As with all FawryPay payment methods, do not rely solely on the on-screen result. Confirm the final order state using either (ideally both) of the following:
Poll the order status using the referenceNumber returned in the charge response. Possible values: UNPAID, PAID, EXPIRED, CANCELED, REFUNDED.
Validation & Error Scenarios
The table below summarizes the validation rules and error scenarios your integration and support teams should expect:
Mechanism
Description
Merchant not enabled for Yellow Card installments in the promo engine
Hidden MyFawry Taqseet does not appear on checkout at all.
Invalid mobile number format
Inline validation The error is shown inline on the checkout, before submission. No request is sent.
Mobile number not linked to any Yellow Carde
Validation fails No OTP is sent. A clear error message is displayed and the customer can re-enter the number.
Mobile number linked, but installment service not available (inactive service / not eligible for the selected plan / insufficient limit)
Validation fails An appropriate message is displayed and no OTP is sent.
Wrong OTP / expired OTP / resend / OTP timeout
Standard OTP handling Handled with the existing FawryPay OTP behavior and messaging (as-is behavior).
Valid mobile number + valid OTP
Success Payment is completed and the success message is displayed in the checkout language (including Arabic).
Best Practices
Validate the mobile number format on the client side before submitting, to give the customer immediate feedback. Always render the installment plans dynamically from the promo engine response rather than hard-coding tenors or rates, since plans are managed centrally and can change without notice. Make sure your checkout supports Arabic end-to-end — plan labels, validation errors, and the success message — as this flow is heavily used by Arabic-speaking customers. Finally, use the Server Notification V2 webhook in parallel with status polling so your backend receives the confirmed payment state even if the customer closes the browser after OTP confirmation.