Create Payments Using Aman Cashier
This page will walk you through the process of creating payments with our Aman Cashier plugin. This page will teach you how to:
- Collect the order details from your client.
- Use the order data you have collected to trigger the Aman Cashier API.
- Managing the API Response for Aman Cashier.
- Redirect your client to the checkout page for Aman Cashier.
- Managing the Payment Processing Information Returned by the Aman Cashier Checkout Page.
Collect your Client's Order Information
You will have to provide your own payment details form as soon as your client's order is prepared. This form ought to gather:
- Client Information: Name, Phone, E-mail, Shipping Address.
- Order Information: Product, Quantity, Unit Price, Order Amount.
Once the necessary data has been gathered, send it to your server so that the Aman Cashier Plugin can be triggered by your application.

A sampleJSON Object that can be passed from your payment form to your server is provided below.
{
"customer":
{
"name": "customer name",
"phoneNumber": "+201xxxxxxxx",
"emailAddress": "client@mystore.com"
},
"productList": [
{
"id": "your product id",
"description": "your product description",
"name": "your product name",
"quantity": "order quantity",
"price": "your product price",
"currency": "EGP"
}],
}
Aman Create Payment
You need to use the create cashier payment API in order to begin using Aman Cashier. Should you be in the development stage, you must make a call to the create cashier payment API using POST method at the following staging endpoint API point URL
http://aman-checkout-backend.mimocodes.com/api/v1
When your payment flow has been thoroughly tested and you are prepared for production, use the following production API endpoint URL instead.
http://aman-checkout-backend.mimocodes.com/api/v1
Cashier Create Payment API HTTP POST Parameters
Your request should contain:- Header:
- Bearer PublicKey: Your Aman merchant account Public Key.
- merchant ID: Your Aman account merchant ID.
- Json object containing the payment information:
Authorization: Bearer "PublicKey"
merchantReference : 256621052822799
{
"maxPaymentsCount": 1,
"fees": 20,
"amount": 500,
"currency": "EGP",
"customer":
{
"name": "customer name",
"phoneNumber": "+201xxxxxxxx",
"emailAddress": "client@mystore.com"
},
"callbackUrl": "your callback Url",
"cancelUrl": "your cancel Url",
"returnUrl": "your return Url",
"country": "egypt",
"expireAt": "2023-12-27",
"paymentMethod": "AmanCard",
"productList": [
{
"id": "your product id",
"description": "your product description",
"name": "your product name",
"quantity": "order quantity",
"price": "your product price",
"currency": "EGP"
}],
"orderReference": "your order reference code"
}
The table below provides a detailed description of the parameters you must include in your POST request.
Below is an example of a cashier create payment request for 500 EGP.
function Cashier(transaction_data) {
const PaymentData = {
"maxPaymentsCount": 1,
"fees": 20,
"amount": 500,
"currency": "EGP",
"customer":
{
"name": "customer name",
"phoneNumber": "+201xxxxxxxx",
"emailAddress": "client@mystore.com"
},
"callbackUrl": "your callback Url",
"cancelUrl": "your cancel Url",
"returnUrl": "your return Url",
"country": "egypt",
"expireAt": "1-1-2024",
"paymentMethod": "AmanCard",
"productList": [
{
"id": "your product id",
"description": "your product description",
"name": "your product name",
"quantity": "order quantity",
"price": "your product price",
"currency": "EGP"
}],
"orderReference": "your order reference code"
};
const response = await fetch('http://aman-checkout-backend.mimocodes.com/api/v1', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'Bearer AMAN9958c094204f3469fe2f120dffbfa8309bccd507f59',
'MerchantId' : '256619092316009'
},
body: JSON.stringify(PaymentData),
});
// Return and display the result of the charge.
return response.json();
}
$data = [
'maxPaymentsCount'=> 1,
'fees' => 20,
'amount' => 500 ,
'currency' => 'EGP',
'customer' => [
'name' => 'customer name',
'phoneNumber' => '+201xxxxxxxx',
'emailAddress' => 'client@mystore.com',
],
'callbackUrl'=> 'your callback Url',
'cancelUrl'=> 'your cancel Url',
'returnUrl'=> 'your return Url',
'country' => 'egypt',
'expireAt'=> '1-1-2024',
'paymentMethod' => 'AmanCard',
'productList' => [
'0'=> [
'id' => 'your product id',
'description' => 'your product description',
'name' => 'your product name',
'quantity' => 'order quantity',
'price' => 'your product price',
'currency' => 'EGP',
]
],
'orderReference' => 'your order reference code',
];
$httpClient = new \GuzzleHttp\Client(); // guzzle 6.3
$response = $httpClient->request('POST', 'http://aman-checkout-backend.mimocodes.com/api/v1', [
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer AMAN9958c094204f3469fe2f120dffbfa8309bccd507f59',
'MerchantId' => '256619092316009'
],
'body' => json_encode( $data , true)
]);
$response = json_decode($response->getBody()->getContents(), true);
$paymentStatus = $response['type']; // get response values
# importing the requests library
import requests
# CashierAPI Endpoint
URL = "http://aman-checkout-backend.mimocodes.com/api/v1"
# defining a params dict for the parameters to be sent to the API
PaymentData = {
"maxPaymentsCount": 1,
"fees": 20,
"amount": 500,
"currency": "EGP",
"customer":
{
"name": "customer name",
"phoneNumber": "+201xxxxxxxx",
"emailAddress": "client@mystore.com"
},
"callbackUrl": "your callback Url",
"cancelUrl": "your cancel Url",
"returnUrl": "your return Url",
"country": "egypt",
"expireAt": "1-1-2024",
"paymentMethod": "AmanCard",
"productList": [
{
"id": "your product id",
"description": "your product description",
"name": "your product name",
"quantity": "order quantity",
"price": "your product price",
"currency": "EGP"
}],
"orderReference": "your order reference code"
}
# Prepare Headers
headers = {
'Content-Type' : 'application/json',
'Accept' : 'application/json',
'Authorization': 'Bearer AMAN9958c094204f3469fe2f120dffbfa8309bccd507f59',
'MerchantId' : '256619092316009'
}
# sending post request and saving the response as response object
status_request = requests.post(url = URL, params = json.dumps(PaymentData) , headers=headers)
# extracting data in json format
status_response = status_request.json()
function Cashier() {
axios.post('http://aman-checkout-backend.mimocodes.com/api/v1', {
"maxPaymentsCount": 1,
"fees": 20,
"amount": 500,
"currency": "EGP",
"customer":
{
"name": "customer name",
"phoneNumber": "+201xxxxxxxx",
"emailAddress": "client@mystore.com"
},
"callbackUrl": "your callback Url",
"cancelUrl": "your cancel Url",
"returnUrl": "your return Url",
"country": "egypt",
"expireAt": "1-1-2024",
"paymentMethod": "AmanCard",
"productList": [
{
"id": "your product id",
"description": "your product description",
"name": "your product name",
"quantity": "order quantity",
"price": "your product price",
"currency": "EGP"
}],
"orderReference": "your order reference code"
})
.then(response => {
// Get Response Contents
let type = response.data.type;
let paymentStatus = response.data.paymentStatus;
//
})
.catch(error => {
console.log(error.response.data)
})
}
$ curl http://aman-checkout-backend.mimocodes.com/api/v1 \
-H "content-type: application/json , Authorization: Bearer AMAN9958c094204f3469fe2f120dffbfa8309bccd507f59 , MerchantId: 256619092316009" \
-X POST \
-d "{
"maxPaymentsCount": 1,
"fees": 20,
"amount": 500,
"currency": "EGP",
"customer":
{
"name": "customer name",
"phoneNumber": "+201xxxxxxxx",
"emailAddress": "client@mystore.com"
},
"callbackUrl": "your callback Url",
"cancelUrl": "your cancel Url",
"returnUrl": "your return Url",
"country": "egypt",
"expireAt": "1-1-2024",
"paymentMethod": "AmanCard",
"productList": [
{
"id": "your product id",
"description": "your product description",
"name": "your product name",
"quantity": "order quantity",
"price": "your product price",
"currency": "EGP"
}],
"orderReference": "your order reference code"
}"
URL url = new URL ("http://aman-checkout-backend.mimocodes.com/api/v1");
HttpURLConnection con = (HttpURLConnection)url.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json; utf-8");
con.setRequestProperty("Authorization", "Bearer PublicKey");
con.setRequestProperty("MerchantId", "256619092316009");
con.setDoOutput(true);
String jsonInputString = "{
"maxPaymentsCount": 1,
"fees": 20,
"amount": 500,
"currency": "EGP",
"customer":
{
"name": "customer name",
"phoneNumber": "+201xxxxxxxx",
"emailAddress": "client@mystore.com"
},
"callbackUrl": "your callback Url",
"cancelUrl": "your cancel Url",
"returnUrl": "your return Url",
"country": "egypt",
"expireAt": "1-1-2024",
"paymentMethod": "AmanCard",
"productList": [
{
"id": "your product id",
"description": "your product description",
"name": "your product name",
"quantity": "order quantity",
"price": "your product price",
"currency": "EGP"
}],
"orderReference": "your order reference code"
}";
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 OPayRequest
{
public class Program
{
static void Main(string[] args)
{
PostJson("http://aman-checkout-backend.mimocodes.com/api/v1", new aman_request
{
"maxPaymentsCount" = 1,
"fees" = 20,
"amount" = 500,
"currency" = "EGP",
"customer" =
{
"name" = "customer name",
"phoneNumber" = "+201xxxxxxxx",
"emailAddress" = "client@mystore.com"
},
"callbackUrl" = "your callback Url",
"cancelUrl" = "your cancel Url",
"returnUrl" = "your return Url",
"country" = "egypt",
"expireAt" = "1-1-2024",
"paymentMethod" = "AmanCard",
"productList" = [
{
"id" = "your product id",
"description" = "your product description",
"name" = "your product name",
"quantity" = "order quantity",
"price" = "your product price",
"currency" = "EGP"
}],
"orderReference" = "your order reference code"
});
}
private static void PostJson(string uri, aman_request postParameters)
{
string postData = JsonConvert.SerializeObject(postParameters);
byte[] bytes = Encoding.UTF8.GetBytes(postData);
var httpWebRequest = (HttpWebRequest) WebRequest.Create(uri);
httpWebRequest.Method = "POST";
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 aman_request
{
public string reference { get; set; }
public string payMethod { get; set; }
public string returnUrl { get; set; }
public string callbackUrl { get; set; }
public string cancelUrl {get; set;}
public string userClientIP { get; set; }
public string expireAt { get; set; }
public product product;
public amount amount;
}
public class amount
{
public string total { get; set; }
public string currency { get; set; }
}
public class product
{
public string name { get; set; }
public string description { get; set; }
}
}
Signature is calculated using the concatenation of the PublicKey and Bearer prefix: Bearer {PublicKey}
Aman Cashier Response
Sample Response
the details included in the response you get when you call Aman Cashier Make a JSON object for the API.
Sample Aman Cashier Create API Response
{
"reference": 583850013,
"orderReference": "123457890",
"amount": 220,
"type": "invoice",
"fees": 0,
"total": 220,
"currency": "EGP",
"exchangeRate": 1,
"value": 220,
"totalValue": 220,
"cashierUrl": "http://aman-checkout.mimocodes.com/3d8848f538d83a52ca3be2d7d4237256d2ed19c39bf206f079",
"availablePaymentMethods": [
{
"name": "Aman Card",
"reference": 1,
"code": "AmanCard"
},
{
"name": "Reference Code",
"reference": 3,
"code": "ReferenceCode"
}
],
"platformType": false,
"platformVersion": false
}
Response Parameters Description
Parameter | type | Description | example |
---|---|---|---|
reference | String |
reference Id. | 583850013 |
orderReference | String |
order id. | 123457890 |
amount | long |
Pre-order amount. | 220 |
type | String |
payment type. | invoice |
fees | long |
service fees. | 10 |
total | long |
total amount to be paid. | 220 |
currency | String |
payment currency. | EGP |
exchangeRate | String |
currency exchange rate. | 1 for EGP. if any other currency this will be changed. |
valu | long |
value of the payment. | 220 |
totalValue | long |
total value to be paid. | 220 |
cashierUrl | String |
Aman Cashier URl generated for your client's current transaction. |
http://aman-checkout.mimocodes.com/3d8848f538d83a52ca3be2d7d4237256d2ed19c39bf206f079 |
availablePaymentMethods | Array |
the available payment methods. | AmanCard and ReferenceCode. |
platformType | String |
the platform you create payment from. | wooCommerce |
platformVersion | String |
The version of your platform. | 1.2.0 |
Redirect Client to Cashier URL
The next step is to direct your client to the cashierUrl
that you received in the API response after you received the response from the cashier create payment API. Your client can proceed with the payment on the cashier page after you have redirected them.

Your client can choose to pay using the following methods if you have left the payMethod
key blank in your request:
- MasterCard, VISA, or MEEZA cards.
- Obtain a reference number and pay at any POS of our Aman retail network.
Otherwise, your client will only be able to use the designated payment method if you have specified a specific payMethod
.
Payment Processing Information
Your client will be sent to the returnUrl
sent with your request if he has completed the payment at the generated cashierUrl
; if not, he will be redirected to cancelUrl
if he has chosen to cancel the payment. The payment processing details will be sent to you on the callbackUrl
that you submitted with your API request. Similar to what you would expect in response to a standard API request, a callback object is sent in JSON. The callback's body is shown below.
{
"transactionReference":583850021,
"orderReference":"WC-2023121846-71",
"merchantReference":1702916986358437,
"paymentMethod":"AmanCard"
,"amount":"510.00",
"currency":"EGP",
"status":"SUCCESS",
"createdAt":"2023-12-18 21:11:07",
"updatedAt":"2023-12-18 21:11:07",
"transactionType":"PayIn",
"transactionFees":"12.20",
"customerName":"customer name",
"customerPhoneNumber":"01234567890",
"customerEmail":"customer@mystore.com",
"customerAddress":"customer address",
"hmac":"409f3c5653f038bd822d969f984c1403dc03d0df843e55ef82205f70deb826730a7fd0a0c61be48c75bc488048227493d107c17560aaf857ef0197cea3621ae5"
}
Callback Parameters Description
Parameter | type | Description | |
---|---|---|---|
transactionReference | String |
Aman transaction number. | |
orderReference | String |
merchant order number. | |
merchantReference | String |
Aman merchant id. | |
paymentMethod | String |
Payment method (AmanCard ReferenceCode). | |
amount | String |
Transaction Amount in EGP. | |
currency | String |
Transaction currency. | |
status | String |
Transaction status (SUCCESS, Failed, etc...). | |
createdAt | String |
Transaction creation time. | |
updatedAt | String |
Transaction update time. | |
transactionType | String |
Transaction type. | |
transactionFees | String |
Transaction fees Amount in EGP. | |
customerName | String |
customer name. | |
customerPhoneNumber | String |
customer phone. | |
customerEmail | String |
customer email. | |
customerAddress | String |
customer address. | |
hmac | String |
HMAC SHA512 signature of the callback payload. Signed using your Secret Key. |
Error Handling
You get a response from Aman after making an API call, letting you know that your request was received and handled. If the Aman API is successful, it should return the status code 00
. If there is a payment processing error, you will receive an error code along with a message explaining the error's cause. Below is an example error response.
{
"code": "20000",
"message": "Duplicate merchant order number",
"data": null
}
You should construct some logic to handle any errors that a request or the system may return based on the HTTP status code of the response. Below is a list of potential error codes that you might encounter. A full list of all possible error codes can be found in the Error Codes section.
Error Code | Error Message |
---|---|
09 | Time out. |
90 | System failure. |
91 | Refund error, please try again later. |
96 | Search order error, please try again later. |
97 | Create checkout session failed. |
98 | Invalid request header with requestId. |
99 | Request channel parameters are not valid. |
20000 | Duplicate merchant order number. |