Get Payment Status V2
Pull information about your transactions whenever needed.
FawryPay delivers the Get Payment Status API as a responsive API for merchants who wishes to pull the status of their transactions whenever needed. Our valued merchants can use Get Payment Status API to retrieve the payment status for the charge request, usingGET method.
FawryPay Sample GET Request:
A sample GET where you can pull your transaction status updates whenever needed is provided below.
HTTP GET Parameters
Detailed description of the parameters that you need to incorporate into you GET request are given in the table below.
Parameter | type | Description | example |
---|---|---|---|
merchantCode | String |
The merchant code provided by FawryPay team during the account setup. | is0N+YQzlE4== |
merchantRefNumber | String |
The merchant reference number for the required order. | 9990076204 |
signature | String |
The request signature it contains the SHA-256 digest value for merchantCode + merchnatRefNumber + secureKey | a5701a2e1e865bf863f0c781829f709ea…. |
Example API Calls
An example call of get payment status API is given below.
function FawryPayGetPaymentStatus(transaction_data) {
const PaymentData = {
merchantCode: transaction_data.merchantCode,
merchantRefNumber: transaction_data.merchantRefNumber,
signature: transaction_data.signature
};
// Use fetch to send the Payment Data to FawryPay Get Payment status API.
// https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch
const response = await fetch('https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/status/v2', {
method: 'GET',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(PaymentData),
});
// Return and display the result of the charge.
return response.json();
}
$merchantCode = '1tSa6uxz2nTwlaAmt38enA==';
$merchantRefNumber = '23124654641';
$merchant_sec_key = '259af31fc2f74453b3a55739b21ae9ef'; // For the sake of demonstration
$signature = hash('sha256' , $merchantCode . $merchantRefNumber . $merchant_sec_key);
$httpClient = new \GuzzleHttp\Client(); // guzzle 6.3
$response = $httpClient->request('GET', 'https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/status/v2', [
'query' => [
'merchantCode' => $merchantCode,
'merchantRefNumber' => $merchantRefNumber,
'signature' => $signature
]
]);
$response = json_decode($response->getBody()->getContents(), true);
$paymentStatus = $response['payment_status']; // get response values
# importing the requests library
import requests
# importing Hash Library
import hashlib
# FawryPay Get Payment Status api-endpoint
URL = "https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/status/v2"
# Payment Data
merchantCode = "1tSa6uxz2nRbgY+b+cZGyA=="
merchantRefNumber = "23124654641"
merchant_sec_key = "259af31fc2f74453b3a55739b21ae9ef"
signature = hashlib.sha256(merchantCode + merchantRefNumber + merchant_sec_key).hexdigest()
# defining a params dict for the parameters to be sent to the API
PaymentData = {'merchantCode':merchantCode,'merchantRefNumber':merchantRefNumber,'signature':signature}
# sending get request and saving the response as response object
status_request = requests.get(url = URL, params = PaymentData)
# extracting data in json format
status_response = status_request.json()
// you Need to install sha256 and axios and import both inside js or by script tag
// sha256 from https://cdnjs.cloudflare.com/ajax/libs/js-sha256/0.9.0/sha256.min.js
//axios from https://cdn.jsdelivr.net/npm/axios/dist/axios.min.js
import { sha256 } from 'js-sha256';
import axios from 'axios';
function FawryPayGetPaymentStatus() {
let merchantCode = "1tSa6uxz2nRbgY+b+cZGyA==";
let merchantRefNumber = "23124654641";
let merchant_sec_key = "259af31fc2f74453b3a55739b21ae9ef";
let signature_body = merchantCode.concat(merchantRefNumber,merchant_sec_key);
let sha256 = new jsSHA('SHA-256', 'TEXT');
sha256.update(signature_body);
let hash_signature = sha256.getHash("HEX");
axios.get('https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/status/v2', {
merchantCode: merchantCode,
merchantRefNumber: merchantRefNumber,
signature: hash_signature
})
.then(response => {
// Get Response Contents
let type = response.data.type;
let paymentStatus = response.data.paymentStatus;
//
})
.catch(error => {
console.log(error.response.data)
})
}
$ curl https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/status/v2 \
-d merchantCode = 1tSa6uxz2nRbgY+b+cZGyA== \
-d merchantRefNumber = 23124654641 \
-d signature = 3f527d0209f4fa5e370caf46f66597c6a7c04580c827ca1f29927ec0d9215131 \
-X GET
URL url = new URL ("https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/status/v2");
HttpURLConnection con = (HttpURLConnection)url.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Content-Type", "application/json; utf-8");
con.setRequestProperty("Accept", "application/json");
con.setDoOutput(true);
String jsonInputString = "{
"merchantCode": "1tSa6uxz2nRbgY+b+cZGyA==",
"merchantRefNumber": "23124654641",
"signature": "3f527d0209f4fa5e370caf46f66597c6a7c04580c827ca1f29927ec0d9215131"
}";
try(OutputStream os = con.getOutputStream()) {
byte[] input = jsonInputString.getBytes("utf-8");
os.write(input, 0, input.length);
}
try(BufferedReader br = new BufferedReader(
new InputStreamReader(con.getInputStream(), "utf-8"))) {
StringBuilder response = new StringBuilder();
String responseLine = null;
while ((responseLine = br.readLine()) != null) {
response.append(responseLine.trim());
}
System.out.println(response.toString());
}
using System;
using System.IO;
using System.Linq;
using System.Net;
using System.Text;
using Newtonsoft.Json;
namespace FawryPayRequest
{
public class Program
{
static void Main(string[] args)
{
PostJson("https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/status/v2", new fawrypay_request
{
merchantCode = "1tSa6uxz2nRbgY+b+cZGyA==",
merchantRefNumber = "23124654641",
signature = "3f527d0209f4fa5e370caf46f66597c6a7c04580c827ca1f29927ec0d9215131"
});
}
private static void PostJson(string uri, fawrypay_request postParameters)
{
string postData = JsonConvert.SerializeObject(postParameters);
byte[] bytes = Encoding.UTF8.GetBytes(postData);
var httpWebRequest = (HttpWebRequest) WebRequest.Create(uri);
httpWebRequest.Method = "GET";
httpWebRequest.ContentLength = bytes.Length;
httpWebRequest.ContentType = "text/json";
using (Stream requestStream = httpWebRequest.GetRequestStream())
{
requestStream.Write(bytes, 0, bytes.Count());
}
var httpWebResponse = (HttpWebResponse) httpWebRequest.GetResponse();
if (httpWebResponse.StatusCode != HttpStatusCode.OK)
{
string message = String.Format("GET failed. Received HTTP {0}", httpWebResponse.StatusCode);
throw new ApplicationException(message);
}
}
}
public class fawrypay_request
{
public string merchantCode { get; set; }
public string merchantRefNumber { get; set; }
public string signature { get; set; }
}
}
Regardless of the choice of your preferred language, any of the code snippets above should produce a GET request containing the following JSON object in the request header:
{
"merchantCode":"dJWmdV+lPIE=",
"merchantRefNumber":"99662223332490123",
"signature":"67a3266b15ddbb9ce7a1eb8fa5c4f928defac59bc4f528e69f496f8e12fe4f4e"
}
FawryPay Sample Response:
Whenever you call FawryPay get payment status API V2, you may expect a response in the form of JSON object which contains all your up-to-date transaction information.
Sample Successful PAYATFAWRY Response
Sample Error Response
Response Parameters Description
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 | 19-05-2020 11:45:23 | |
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
|
||||
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
|
||||
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 | String |
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. |
GEThttps://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/status/v2
Response
// API Response Data Should Appear here
// This is a sample successful Response
{
"type":"PaymentStatusResponse",
"referenceNumber":"100162801",
"merchantRefNumber":"23124654641",
"paymentAmount":20,
"paymentDate":1514747471138,
"expirationTime":151654747115,
"paymentStatus":"PAID",
"paymentMethod":"PAYATFAWRY",
"statusCode":200,
"statusDescription":"Operation done successfully"
}
Next steps
Was this page helpful?
Thank you for helping improve FawryPay's documentation. If you need help or have any questions, please consider contacting support.