API Reference

Complete reference for the FawrySDK global object and its classes.

FawrySDK (Global)

The SDK is exposed as a global FawrySDK object when loaded via script tag.

Methods

`FawrySDK.generateSessionId()`

Generate a unique session ID (UUID v4) for a payment request.

var sid = FawrySDK.generateSessionId();
// e.g. "3f2504e0-4f89-11d3-9a0c-0305e82c3301"

Returns: string – UUID v4 string

`FawrySDK.configureLogging(options)`

Configure optional remote diagnostics. If logApiUrl is omitted, empty, or never set, the SDK does not send any log HTTP requests.

FawrySDK.configureLogging({
    logApiUrl: 'https://your-domain.com/api/fawry-log'
});

Parameters:

Name	Type	Required	Description
`logApiUrl`	`string` \| `null`	No	Full URL for `POST` requests with JSON `{ message, data }`

`FawrySDK.requestSale(paymentOptionType)`

Create a builder for a card sale (purchase) request.

var builder = FawrySDK.requestSale(FawrySDK.PaymentOptionType.CARD);

Parameters:

Name	Type	Required	Description
`paymentOptionType`	`PaymentOptionType`	Yes	Must be `PaymentOptionType.CARD`

Returns: CardSaleBuilder

`FawrySDK.requestRefund(paymentOptionType)`

Create a builder for a card refund request.

var builder = FawrySDK.requestRefund(FawrySDK.PaymentOptionType.CARD);

Parameters:

Name	Type	Required	Description
`paymentOptionType`	`PaymentOptionType`	Yes	Must be `PaymentOptionType.CARD`

Returns: CardRefundBuilder

`FawrySDK.requestVoid(paymentOptionType)`

Create a builder for a card void request.

var builder = FawrySDK.requestVoid(FawrySDK.PaymentOptionType.CARD);

Parameters:

Name	Type	Required	Description
`paymentOptionType`	`PaymentOptionType`	Yes	Must be `PaymentOptionType.CARD`

Returns: CardVoidBuilder

`FawrySDK.requestInquiry()`

Create a builder for a transaction inquiry request.

var builder = FawrySDK.requestInquiry();

Returns: InquiryBuilder

`FawrySDK.requestClearCache()`

Create a builder for a clear cache request.

var builder = FawrySDK.requestClearCache();

Returns: ClearCacheBuilder

`FawrySDK.handleCallback()`

Process the callback redirect from the SoftPOS app. Should be called on your callback page. This method is also called automatically when the page URL contains sid= or sId= parameters.

FawrySDK.handleCallback().then(function(result) {
    console.log(result.isSuccess());
});

Returns: Promise<PaymentResult | RefundResult | VoidResult | InquiryResult>

Builders

All builders share a fluent (chainable) API. Call setter methods to configure the request, then call .send() to execute it.

Common Methods (All Builders)

These methods are available on every builder:

Method	Type	Required	Description
`.setSignature(value)`	`string`	Yes	Signature from your backend
`.setSid(value)`	`string`	Yes	Session ID from `generateSessionId()`
`.setClientTimeStamp(value)`	`number`	Yes	Timestamp (e.g., `Date.now()`)
`.setPartnerCode(value)`	`string`	Yes	Your Fawry partner code
`.setMerchantAccountNumber(value)`	`string`	Yes	Your merchant account number
`.setCallbackUrl(value)`	`string`	No	Custom callback URL (defaults to `{origin}/callback.html`)
`.setAccountNumber(value)`	`string`	No	Alternative to `setMerchantAccountNumber`
`.setMerchantToken(value)`	`string`	No	Merchant token
`.setBtc(value)`	`number`	Yes	Business transaction code (from Fawry; no SDK default)
`.setPrintReceipt(value)`	`boolean`	No	Print receipt on terminal (default: `false`)
`.setDisplayInvoice(value)`	`boolean`	No	Display invoice on terminal (default: `false`)
`.setExtras(value)`	`object`	No	Extra info key-value pairs
`.send()`	–	–	Execute the request. Returns `Promise<PaymentResult>`

CardSaleBuilder

Created via FawrySDK.requestSale(PaymentOptionType.CARD).

Additional Methods:

Method	Type	Required	Description
`.setAmount(value)`	`string`	Yes	Payment amount (use the same string as for signature generation)
`.setCurrency(value)`	`string`	No	Currency code (default: `'EGP'` if omitted)
`.setOrderId(value)`	`string`	No	Your order/reference ID
`.setTips(value)`	`number`	No	Tips amount
`.setPromoCode(value)`	`string`	No	Promotional code
`.setReceiptNumber(value)`	`string`	No	Receipt number
`.setSplitPayment(value)`	`boolean`	No	Enable split payment
`.setChainUID(value)`	`string`	No	Chain UID for split payments
`.setDiscountInfo(value)`	`object`	No	Discount details
`.setInstallmentInfo(value)`	`object`	No	Installment plan details
`.setMetadata(value)`	`object`	No	Custom metadata key-value pairs

CardRefundBuilder

Created via FawrySDK.requestRefund(PaymentOptionType.CARD).

Additional Methods:

Method	Type	Required	Description
`.setAmount(value)`	`string`	Yes	Refund amount (same string as for signature)
`.setTransactionFCRN(value)`	`string`	No	Original transaction FCRN
`.setOrderId(value)`	`string`	No	Order/reference ID
`.setSplitPayment(value)`	`boolean`	No	Enable split payment
`.setChainUID(value)`	`string`	No	Chain UID for split payments

CardVoidBuilder

Created via FawrySDK.requestVoid(PaymentOptionType.CARD).

Additional Methods:

Method	Type	Required	Description
`.setTransactionFCRN(value)`	`string`	No	Original transaction FCRN
`.setOrderId(value)`	`string`	No	Order/reference ID
`.setSplitPayment(value)`	`boolean`	No	Enable split payment
`.setChainUID(value)`	`string`	No	Chain UID for split payments

InquiryBuilder

Created via FawrySDK.requestInquiry().

Additional Methods:

Method	Type	Required	Description
`.setIdType(value)`	`IdType`	Yes	Type of ID to query by
`.setTransactionId(value)`	`string`	No	The transaction ID to look up
`.setFromDate(value)`	`string`	No	Start date filter
`.setToDate(value)`	`string`	No	End date filter

ClearCacheBuilder

Created via FawrySDK.requestClearCache().

Additional Methods:

Method	Type	Required	Description
`.setClearSecurityKeys(value)`	`boolean`	Yes	Clear security keys (`true` or `false`)
`.setClearProfile(value)`	`boolean`	Yes	Clear profile data (`true` or `false`)

Constants

PaymentOptionType

FawrySDK.PaymentOptionType.CARD  // 'card'

OperationType

FawrySDK.OperationType.PURCHASE     // 'purchase'
FawrySDK.OperationType.REFUND       // 'refund'
FawrySDK.OperationType.VOID         // 'void'
FawrySDK.OperationType.INQUIRY      // 'inquiry'
FawrySDK.OperationType.CLEAR_CACHE  // 'clearCache'

IdType

Used with the Inquiry builder:

FawrySDK.IdType.FCRN      // 'FCRN' - Fawry Cash Register Number
FawrySDK.IdType.CORRUID   // 'CORRUID' - Correlation UUID
FawrySDK.IdType.ORDER_ID  // 'ORDER_ID' - Your order ID

Response Models

PaymentResult / RefundResult / VoidResult / InquiryResult

All result types extend SoftPOSResultBase and share the same structure:

result.sid                              // Session ID (string)
result.header                           // ResponseHeader
result.body                             // ResponseBody
result.isSuccess()                      // boolean (statusCode 1 or 3)
result.getMessageCode()                 // string ('purchase', 'refund', 'void', 'inquiry')
result.getTransactionType()             // string

ResponseHeader

result.header.messageCode               // string
result.header.requestUuid               // string
result.header.serialNumber              // string
result.header.serverTimestamp            // string
result.header.status                    // ResponseStatus
result.header.userName                  // string

ResponseStatus

result.header.status.statusCode         // number (1 = success, 0 = failure, 3 = reversed)
result.header.status.statusDesc         // string
result.header.status.hostStatusCode     // number
result.header.status.hostStatusDesc     // string

ResponseBody

result.body.fcrn                        // string - Fawry transaction reference
result.body.amount                      // string
result.body.balance                     // string
result.body.currency                    // string
result.body.fawryReference              // string
result.body.paymentOption               // string
result.body.transactionType             // string
result.body.signature                   // string
result.body.receiptInfo                 // ReceiptInfo
result.body.fees                        // object

ReceiptInfo

result.body.receiptInfo.authId          // string - Authorization ID
result.body.receiptInfo.rrn             // string - Retrieval Reference Number
result.body.receiptInfo.merchantId      // string
result.body.receiptInfo.terminalId      // string
result.body.receiptInfo.batchNumber     // string
result.body.receiptInfo.tips            // number
result.body.receiptInfo.cardInfo        // CardInfo

CardInfo

result.body.receiptInfo.cardInfo.primaryAccountNumber  // string (masked PAN)
result.body.receiptInfo.cardInfo.cardAcctId            // string
result.body.receiptInfo.cardInfo.appName               // string (e.g. 'VISA')
result.body.receiptInfo.cardInfo.expiryDate             // string