Server To Server Notification V2

Throughout its entire roadmap, Your FawryPay transactions shall experience several status updates. Depending on the specific nature of your core business, the status of your clients’ transactions can range from created, paid, cancelled, expired, shipped to delivered. Whenever the status of one of your transactions has been altered, FawryPay will send an informative HTTP POST request to your preconfigured endpoint on your own application server with the current detailed status of your transaction. Note that your endpoint need to be set during your registration process as a merchant with FawryPay (Register as a merchant). You can optionally implement a service to receive this request so that you can avail the service to the customer or update your stock automatically. You will need to provide your endpoints (callback notification URL) for both development and production environments.

Assuming you have providedhttp://MerchantURL/merchatCallbakPage as your callback URL, FawryPay server to serve API V2 will send the follwoing HTTP POST request with the following body parameters whenever the status of your transaction has been altered:

Detailed description of the parameters associated with FawryPay server to server notification API V2 are given in the table below.

Parameter		type	Description	example
requestId		`String`	UUID generated Request id	c72827d084ea4b88949d91dd2db4996e
fawryRefNumber		`String`	The reference number of this order in atFawry system which is displayed to the customer and used during the payment	9990076204
merchantRefNumber		`String`	The reference number of this order at merchant's system.	9990076204
customerName		`String`	Customer Name.	FirstName LastName
customerMobile		`Integer`	Customer Cell Phone	01xxxxxxxxx
customerMail		`Email String`	Customer email to which payment confirmation will be sent.	example@domain.com
customerMerchantId		`String`	The Profile id for the customer in the merchant system	ACD23658
paymentAmount		`Decimal`	The amount value received from merchant to be paid by the customer, merchant can use it to verify that the customer pay the required amount to enable the service to the customer	350.50
orderAmount		`Decimal`	The payment Amount without the fees.	780.75
fawryFees		`Decimal`	The fees added by fawry for the order amount.	10.00
shippingFees		`Decimal`	Shipping fees amount if applicable	5.50
orderStatus		`String`	The updated status of your transaction.	NEW, PAID, CANCELED REFUNDED, EXPIRED PARTIAL_REFUNDED, FAILED
paymentMethod		`String`	The configured payment method for the merchant	PAYATFAWRY, CARD
paymentTime		`Date-Time`	The actual time for the payment if the Order Status is PAID	1676356569911
authNumber		`Integer`	The transaction number in the bank	96322541122558
paymentRefrenceNumber		`String`	Unique number registered in FawryPay system to keep track of the payment	369552233
orderExpiryDate		`Decimal`	The order expiry in hours for this order if the merchant need to set specific expiry for this order if not set we will use the configured expiry hour per merchant	3.5
orderItems		`String`	A list of order items associated to the order	123456
failureErrorCode		`Integer`	Contains the error code in case of failure.	9965
failureReason		`String`	Contains an error message describing the failure reason.	Wrong Signature
messageSignature		`String`	The SHA-256 digested for the following concatenated string fawryRefNumber + merchantRefNum + Payment amount(in two decimal format 10.00)+Order amount(in two decimal format 10.00)+Order Status + Payment method + Payment reference number ( if exist as in case of notification for order creation this element will be empty) + secureKey	ab34dcddfab34dcddfab34dcddfab34 dcddfab34dcddfab34dcddfab34dcddf
threeDSInfo `JSON Array`
	eci	`String`	The 3-D Secure Electronic Commerce Indicator, which is set to '05' when the cardholder authenticates OK, and '08' when the cardholder is not enrolled. (These values may change depending on the locale or issuer).	Possible value returned by Visa: 05: 3DS authentication was successful; transactions are secured by 3DS. 06: authentication was attempted but was not or could not be completed; possible reasons being either the card or its Issuing Bank has yet to participate in 3DS. 07: 3DS authentication is either failed or could not be attempted; possible reasons being both card and Issuing Bank are not secured by 3DS, technical errors, or improper configuration. Possible value returned by MasterCard: 02: 3DS authentication is successful; both card and Issuing Bank are secured by 3DS. 01: 3DS authentication was attempted but was not or could not be completed; possible reasons being either the card or its Issuing Bank has yet to participate in 3DS, or cardholder ran out of time to authorize. 00: 3DS authentication is either failed or could not be attempted; possible reasons being both card and Issuing Bank are not secured by 3DS, technical errors, or improper configuration.
	xid	`String`	unique transaction identifier that is generated by the merchant to identify the 3DS transaction.	VDj97t1qRJWM0ErrY2PtrBiSMQw=
	enrolled	`String`	This field is only included if the card is within an enrolled range. It will take values (Y - Yes, N - No, U - Unavailable for Checking).	Y
	status	`String`	This field is only included if payment authentication was used and a PARes was received by the MPI. It will take values (Y - Yes, N - No, A - Attempted Authentication, U - Unavailable for Checking).	Y
	batchNumber	`String`	A date supplied by the acquirer to indicate when this transaction will be settled. If the batch has today's date then it will be settled the next day. When the acquirer closes the batch at the end of the day, the date will roll over to the next processing day's date.	0
	command	`String`	Indicates the type of transaction type. It must be equal to 'pay'.	pay
	message	`String`	Approved or not	Approved
	verSecurityLevel	`String`	The Verification Security Level is generated at the card issuer as a token to prove that the cardholder was enrolled and authenticated OK. It is shown for all transactions except those with authentication status “Failure”. This field contains the security level to be used in the AUTH message. '05' - Fully Authenticated. '06' - Not authenticated, (cardholder not participating), liability shift. '07' - Not authenticated. Usually due to a system problem, for example the merchant password is invalid.	05
	verStatus	`String`	The status codes used by the Payment Server. response code value to show whether the card authentication was successful or not. The response code values are mentioned in the table below.	Y
	verType	`String`	Either '3DS' or 'SPA'.	3DS
	verToken	`String`	this value is generated by the card issuer as a token to prove that the cardholder authenticated OK. This is a base64 encoded value.	gIGCg4SFhoeIiYqLjI2Oj5CRkpM=
	version	`String`	The version of the Payment Client API being used. The current version is 1.	1
	receiptNumber	`String`	Mezza receipt number.	1123456
	sessionId	`String`	Hosted checkout session ID. Incase the authentication required a session id.	SESSION0002818019663G5075633E86
invoiceInfo `JSON Array`
	number	`String`	Number of the invoice.	28176849
	businessRefNumber	`String`	Business Reference Number of the invoice.	w0dd2fss41d2d2qs556
	dueDate	`String`	Due Date of the invoice.	2021-06-19
	expiryDate	`Timestamp`	Expiry Date of the invoice.	1625062277000
installmentInterestAmount		`Decimal`	Customer Paid amount as Interest fees	100.00
installmentMonths		`Integer`	Number of Months for the instalment	6

verStatus values:

Parameter		Description
Y		The cardholder was successfully authenticated.
E		The cardholder is not enrolled.
N		The cardholder was not verified.
U		The cardholder's Issuer was unable to authenticate due to a system error at the Issuer.
F		An error exists in the format of the request from the merchant. For example, the request did not contain all required fields, or the format of some fields was invalid.
A		Authentication of your Merchant ID and Password to the Directory Server Failed.
D		Error communicating with the Directory Server, for example, the Payment Server could not connect to the directory server or there was a versioning mismatch.
C		The card type is not supported for authentication.
M		This indicates that attempts processing was used. Verification is marked with status M – ACS attempts processing used. Payment is performed with authentication. Attempts is when a cardholder has successfully passed the directory server but decides not to continue with the authentication process and cancels.
S		The signature on the response received from the Issuer could not be validated. This should be considered a failure.
T		ACS timed out. The Issuer's ACS did not respond to the Authentication request within the time out period.
P		Error parsing input from Issuer.
I		Internal Payment Server system error. This could be caused by a temporary DB failure or an error in the security module or by some error in an internal system.

FawryPay check on the http response status so return empty response and in case of http response status 200 the call back will be marked as delivered else FawryPay will keep sending the HTTP request for a preconfigured number of retries.

Server To Server Notification V2

FawryPay Example HTTP POST request to the merchant callback URL

HTTP POST Request Parameters

Expected Body Response

Was this page helpful?

Questions? Contact Support.