This document describes the Checkout integration procedures between Checkout service and the website for e-commerce merchants.
\nCheckout service is a fast and easy way to create a secure payment page. It allows collecting and submitting payments and sending them for processing.
\nTo use the Checkout service on the site you have to perform integration. Checkout integration provides a set of APIs that allow customizing payment processing for the business. These protocols implement acquiring payments (purchases) using specific API interaction with the merchant websites.
\n![](\"https://docs.expresspay.sa/assets/images/checkout_payment_flow.png\")
\n\nWhen a Customer wants to make a purchase on your site the following happens:
\nCustomer places an order and initiates payment on the site.
\nSite confirms the order and sends the payment processing request to the Checkout system with information about the order, payment and hash.
\nCheckout system validates the request and sends to the site the response with the redirect link.
\nThe site redirects the Customer on the Checkout page by redirect link.
\nCustomer selects the payment method, enters the payment data and confirms the payment. The payment method will be specifying automatically If only one method is available.
\nThe payment processes at Payment Gateway.
\nPayment Gateway sends a callback to the site with the payment result.
\nThe payment result is shown to the Customer.
\nThe payment could be declined in case of invalid data detection.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"21813149","collectionId":"40e00cf2-4be5-4ad4-95ba-6b1683ff8ae4","publishedId":"2s9Y5SX6Xs","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"00E6A0"},"publishDate":"2023-08-20T11:08:14.000Z"},"item":[{"name":"Initiate","event":[{"listen":"prerequest","script":{"id":"5a37bb5b-6a68-4b04-a2ef-1d8d92c088a7","exec":["var order_number = pm.environment.get(\"order_number\");","var order_amount = pm.environment.get(\"order_amount\");","var order_currency = \"SAR\";","var order_description = pm.environment.get(\"order_description\");","var merchant_pass = pm.environment.get('merchant_password');","","//formula:","var to_md5 = order_number + order_amount + order_currency + order_description + merchant_pass;","// Use the CryptoJS","","var hash = CryptoJS.SHA1(CryptoJS.MD5(to_md5.toUpperCase()).toString());","var result = CryptoJS.enc.Hex.stringify(hash);","// Set the new environment variable","postman.setEnvironmentVariable('session_hash', result);"],"type":"text/javascript","packages":{}}},{"listen":"test","script":{"id":"aecc62eb-074c-462f-a618-5a6723560004","exec":[""],"type":"text/javascript","packages":{}}}],"id":"51ada774-6275-41ee-ac0c-dd618963deef","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"action","value":"SALE","type":"text"},{"key":"edfa_merchant_id","value":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","type":"text","description":"Unique key (client_key)\nEdfapay merchant key - UUID format value
\n"},{"key":"order_id","value":"ORD001","type":"text","description":"Transaction ID in the Merchants system\nString up to 255 characters
\n"},{"key":"order_amount","value":"1.00","type":"text","description":"Format depends on currency.\nSend Integer type value for currencies with zero-exponent. Example: 1000\nSend Float type value for currencies with exponents 2, 3, 4.\nFormat for 2-exponent currencies: XX.XX Example: 100.99\nPay attention that currencies 'UGX', 'JPY', 'KRW', 'CLP' must be send in the format XX.XX, with the zeros after comma. Example: 100.00\nFormat for 3-exponent currencies: XXX.XXX Example: 100.999.\nFormat for 4-exponent currencies: XXX.XXXX Example: 100.9999
\n"},{"key":"order_currency","value":"SAR","type":"text","description":"Currency\n3-letter code
\n"},{"key":"order_description","value":"An order","type":"text","description":"Description of the transaction (product name)\nString up to 1024 characters
\n"},{"key":"req_token","value":"N","type":"text","description":"Special attribute pointing for further tokenization\nY or N (default N)
\n"},{"key":"payer_first_name","value":"FisrtName","type":"text","description":"Customer's name\nString up to 32 characters
\n"},{"key":"payer_last_name","value":"LastName","type":"text","description":"Customer's surname\nString up to 32 characters
\n"},{"key":"payer_address","value":"example@example.com","type":"text","description":"String up to 255 characters
\n"},{"key":"payer_country","value":"SA","type":"text","description":"2-letter code
\n"},{"key":"payer_city","value":"Riyadh","type":"text","description":"Customer's city\nString up to 32 characters
\n"},{"key":"payer_zip","value":"12221","type":"text","description":"ZIP-code of the Customer\nString up to 10 characters
\n"},{"key":"payer_email","value":"example@example.com","type":"text","description":"Customer's email\nString up to 256 characters
\n"},{"key":"payer_phone","value":"966565555555","type":"text","description":"Customer's phone\nString up to 32 characters
\n"},{"key":"payer_ip","value":"176.44.76.222","type":"text","description":"IP-address of the Customer\nXXX.XXX.XXX.XXX
\n"},{"key":"term_url_3ds","value":"https://successorfailurl.com","type":"text","description":"URL to which Customer should be returned after 3D-Secure\nString up to 1024 characters
\n"},{"key":"auth","value":"N","type":"text","description":"Indicates that transaction must be only authenticated, but not captured\nY or N (default N)
\n"},{"key":"recurring_init","value":"N","type":"text","description":"Initialization of the transaction with possible following recurring\nY or N (default N)
\n"},{"key":"hash","value":"{{session_hash}}","description":"Special signature to validate your request to Payment Platform Addition in Signature section.\nExample: Must be SHA1 of MD5 encoded string (uppercased): order_number + order_amount + order_currency + order_description + password
\n","type":"text"}]},"url":"https://api.edfapay.com/payment/initiate","description":"The merchant submits an authorization request and as a result of successful response receives the redirect_url - link on the Checkout page.
/payment/initiate
The authentication performs when the payment is initiated. INFO: You need to create an authentication request to start checkout process for the Customers.
\nNotification endpoint must be of method POST and able to accept form-data as the content type.
\n*Soon will be launched
\nFollowing is the request body parameters with example
\n","urlObject":{"protocol":"https","path":["payment","initiate"],"host":["api","edfapay","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"51ada774-6275-41ee-ac0c-dd618963deef"},{"name":"Status","event":[{"listen":"prerequest","script":{"id":"5811529b-97b8-4515-b082-6fc780a773af","exec":["// Must be SHA1 of MD5 encoded string (uppercased): payment_id + merchant_pass","var password = \"e3ee4e96e925b088377aa628c42f6568\";","var payment_id = \"xxxxxxxx-aa15-11ee-beec-4ac04ca8935e\";","var to_md5 = payment_id + password;","console.log(CryptoJS.MD5(to_md5.toUpperCase()).toString());","console.log(CryptoJS.SHA1(CryptoJS.MD5(to_md5.toUpperCase()).toString()));","var hash = CryptoJS.SHA1(CryptoJS.MD5(to_md5.toUpperCase()).toString());","var result = CryptoJS.enc.Hex.stringify(hash);","postman.setEnvironmentVariable('hash', result);"],"type":"text/javascript"}}],"id":"5f9bf5c5-b8f1-46ac-b48b-313edb28f336","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"order_id\": \"100\",\n \"merchant_id\": \"xxxxxxx-0f25-4e31-8097-5422e4cdabbb\",\n \"gway_Payment_id\": \"xxxxxxxx-aa15-11ee-beec-4ac04ca8935e\",\n \"hash\": \"{{hash}}\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.edfapay.com/payment/status","description":"API return's transaction status of specific payment.
\n","urlObject":{"protocol":"https","path":["payment","status"],"host":["api","edfapay","com"],"query":[],"variable":[]}},"response":[{"id":"1886c993-5097-4e38-81b0-edf8c97009ce","name":"Failure Response","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"order_id\": \"Abdul001\",\n \"merchant_id\": \"b1efc42a-67d3-4bdc-8382-7059bb665036\",\n \"hash\": \"{{hash}}\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.edfapay.com/payment/status"},"status":"Bad Request","code":400,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{\n \"statusCode\": 400,\n \"responseBody\": \"Order Not Found.\"\n}"},{"id":"af9c0d8f-6388-4ce2-a589-50cf2eb1f5d1","name":"Success Response","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"order_id\": \"oooor009\",\n \"merchant_id\": \"xxxxxxxx-0f25-4e31-8097-5422e4cdabbb\",\n \"gway_Payment_id\": \"xxxxxxxx-aa15-11ee-beec-4ac04ca8935e\",\n \"hash\": \"{{hash}}\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.edfapay.com/payment/status"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 03 Jan 2024 11:54:46 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Vary","value":"Origin"},{"key":"Vary","value":"Access-Control-Request-Method"},{"key":"Vary","value":"Access-Control-Request-Headers"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-XSS-Protection","value":"1 ; mode=block"},{"key":"Referrer-Policy","value":"no-referrer"}],"cookie":[],"responseTime":null,"body":"{\n \"statusCode\": 200,\n \"responseBody\": {\n \"date\": \"2024-01-03 08:52:34\",\n \"status\": \"settled\",\n \"order\": {\n \"number\": \"oooor009\",\n \"amount\": \"0.11\",\n \"currency\": \"SAR\",\n \"description\": \"TEST DESCRIPTION1\"\n },\n \"customer\": {\n \"name\": \"M Adnan Hashmi\",\n \"email\": \"example@example.com\"\n },\n \"payment_id\": \"xxxxxxxx-aa15-11ee-beec-4ac04ca8935e\"\n }\n}"}],"_postman_id":"5f9bf5c5-b8f1-46ac-b48b-313edb28f336"},{"name":"Refund","event":[{"listen":"prerequest","script":{"id":"b2f773a9-f394-42e3-bbb0-bac3849556b5","exec":["var payment_id = \"904776a0-4635-11ee-97c2-7a6dc1121caa\";","var amount =\"1.00\";","var merchant_pass = \"ba7718273600a88fc43a242627e57ad5\";","//formula:","var to_md5 = payment_id + amount + merchant_pass;","// Use the CryptoJS","var hash = CryptoJS.SHA1(CryptoJS.MD5(to_md5.toUpperCase()).toString());","var result = CryptoJS.enc.Hex.stringify(hash);","console.log(hash);","// Set the new environment variable","postman.setEnvironmentVariable('hash', result);","console.log(result);"],"type":"text/javascript"}}],"id":"a22777c3-a906-4d7c-b510-181a2f4ee21b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"gwayId\": \"23828b1e-5c55-11ee-9e87-aee84e39de53\",\n \"order_id\": \"Abdul001\",\n \"edfa_merchant_id\": \"b1efc42a-67d3-4bdc-8382-7059bb665036\",\n \"hash\": \"{{hash}}\",\n \"payer_ip\": \"176.44.76.222\",\n \"amount\":\"1.00\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.edfapay.com/payment/refund","description":"