Customized card form

Getting started

To integrate directly with Kashier APIs and save the card as a card token, you'll need to go through the following steps. Your system should save the returned token with your customer profile for future use in direct payments.

When the cardToken actually comes back

A cardToken is included in the response (at response.paymentMethod.card.cardToken) only when the transaction status is SUCCESS or PENDING and the request carried paymentMethod.card.save or paymentMethod.card.agreement — or the card was already stored on file (storedOnFile: "STORED"). On any other outcome the token is suppressed, so don't build on it always being present.

Step 1: Create order hash

Order hash generation uses HMAC SHA256. See the process of generating the hash.

Step 2: Pay

The request is a POST request that allows you to pay directly.

Endpoint	Value
TEST-URL	`https://test-fep.kashier.io/v3/orders/`
LIVE-URL	`https://fep.kashier.io/v3/orders/`
Method	POST

curl -X 'POST' 'https://test-fep.kashier.io/v3/orders/' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Kashier-Hash: your_generated_hash' \
  -d '{
      "apiOperation": "PAY",
      "paymentMethod": {
          "type": "CARD",
          "card": {
              "save": true,
              "expiry": {
                  "month": "05",
                  "year": "26"
              },
              "number": "XXXXXXXXXXXX0001",
              "nameOnCard": "TEST",
              "securityCode": "100"
          }
      },
      "order": {
          "reference": "",
          "amount": "1",
          "currency": "EGP",
          "description": ""
      },
      "interactionSource": "ECOMMERCE",
      "reconciliation": {
          "webhookUrl": "https://your-call-back-url.com",
          "merchantRedirect": "https://your-call-back-url.com",
          "redirect": true
      },
      "customer": {
          "reference": "24",
          "firstName": "ghanem",
          "lastName": "ghanem",
          "email": "[email protected]"
      },
      "merchantId": "MID-2-670"
  }'

order.reference is your own merchant order ID, and interactionSource must be ECOMMERCE, MOTO, or RECURRING. See the field reference below for the rest.

Body parameters

Parameter	Description
merchantId (String)	Merchant account number or merchant ID
number (string)	Card PAN number
nameOnCard (string)	Cardholder name
year (string)	Card expiry year
month (string)	Card expiry month
securityCode (string)	Card Verification Value/Code
save (bool)	If you want to save the card as a token to pay with later. When the transaction succeeds, a token is included in the response body and webhook response. Webhook
enable3DS (bool)	Whether to run 3D Secure for this payment. Send it at `paymentMethod.card.enable3DS` — not directly under `paymentMethod`. When absent it is treated as `true`, so an `ECOMMERCE` card pay runs 3DS and returns `AUTHENTICATION_INITIATED` rather than a final status.
apiOperation (string)	Should be: PAY
connectedAccount.merchantId (string)	Make payments on behalf of your connected account by sending the Sub Merchant/Connected Account merchant ID in the JSON body: `"connectedAccount": { "merchantId": "MID-452-644" }`. The value must start with `MID-`.
order (JSON object)	Contains the order details `{"reference": "1","amount": "1", "currency": "EGP", "description": "" }` - currency (String): order currency (ISO: "EGP", "USD", "GBP" "EUR") - amount (string): order amount - reference (string): order identifier - description (string): order description
merchantRedirect (string)	merchantRedirect should be URI encoded
redirect (bool)	Redirect to the merchantRedirect URL after the transaction has been completed, whether it is unsuccessful or successful
serverWebhook (string)	Pass an endpoint to receive server-to-server notifications. Setting this up on your application is as easy as creating a new page that accepts unauthenticated POST requests. The event object is sent as JSON in the request body. Webhook
interactionSource (string)	Mandatory; must be `MOTO`, `RECURRING`, or `ECOMMERCE` based on the business case
customer (JSON object)	Contains the customer details `{"reference": "24","firstName": "ghanem","lastName": "ghanem","email": "[email protected]"}` - reference (String): customer reference ID to associate it with the card (required) - firstName (string): first name of the customer (optional) - lastName (string): last name of the customer (optional) - email (string): email of the customer (optional) - mobilePhone (string): mobile number of the customer (optional) - nationalId (string): national ID of the customer (optional)
metaData (JSON object)	Additional data you can send and receive via webhooks and responses

Note

The customer object is required in case of card save:true.

Response structure at MOTO with NON-3DS

{
  "response": {
      "apiOperation": "PAY",
      "operation": "pay",
      "currency": "EGP",
      "result": "SUCCESS",
      "status": "CAPTURED",
      "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
      "amount": 100,
      "creationTime": "2023-10-16T12:00:49.746Z",
      "lastUpdatedTime": "2023-10-16T12:00:50.137Z",
      "merchantCurrency": "EGP",
      "reference": "1697457648576",
      "totalAuthorizedAmount": 100,
      "totalCapturedAmount": 100,
      "totalDisbursedAmount": 0,
      "totalRefundedAmount": 0,
      "authentication": {},
      "paymentMethod": {
          "type": "CARD",
          "card": {
              "cardBrand": "Mastercard",
              "storedOnFile": "TO_BE_STORED",
              "number": "512345******2346",
              "nameOnCard": "Mohamed Khaled",
              "expiry": {
                  "month": "12",
                  "year": "25"
              },
              "cardToken": "9d8332cb-6195-40ea-aed0-86c3aa60fbaa"
          }
      },
      "metaData": {
          "customerName": "Noura Mosaad",
          "merchantWebhook": "https://your-website.com/paymentWebhook",
          "redirect": true
      },
      "customer": {
          "reference": "01163550555"
      },
      "timestamp": "2022-12-15T13:54:01.606Z",
      "reconciliation": {
          "webhookUrl": "https://your-call-back-url.com",
          "merchantRedirect": "https://your-call-back-url.com?paymentStatus=SUCCESS&cardDataToken=9d8332cb-6195-40ea-aed0-86c3aa60fbaa&maskedCard=512345******2346&merchantOrderId=1697457648576&orderId=27a86389-83be-4107-b51d-33ad767078a2&cardBrand=Mastercard&orderReference=TEST-ORD-96353&transactionId=TX-2498912113&amount=100&currency=EGP&mode=test&signature=dde46b3a9b4fc05478f6a35dd62f82a2a3c0b6ace73997dfdcebda0abd7b8cc3",
          "redirect": true
      },
      "merchantId": "MID-123-123",
      "order": {
          "amount": 100,
          "currency": "EGP",
          "callbackURL": "https://your-call-back-url.com",
          "systemOrderId": "27a86389-83be-4107-b51d-33ad767078a2"
      },
      "merchantRedirectUrl": "https://your-call-back-url.com?paymentStatus=SUCCESS&cardDataToken=9d8332cb-6195-40ea-aed0-86c3aa60fbaa&maskedCard=512345******2346&merchantOrderId=1697457648576&orderId=27a86389-83be-4107-b51d-33ad767078a2&cardBrand=Mastercard&orderReference=TEST-ORD-96353&transactionId=TX-2498912113&amount=100&currency=EGP&mode=test&signature=dde46b3a9b4fc05478f6a35dd62f82a2a3c0b6ace73997dfdcebda0abd7b8cc3",
      "apiKeyId": "5d0003fc77c68a0018b05a6f",
      "method": "card",
      "creationDate": "2023-10-16T15:00:48.946Z",
      "orderId": "27a86389-83be-4107-b51d-33ad767078a2",
      "merchantOrderId": "1697457648576",
      "orderReference": "TEST-ORD-96353",
      "paymentType": "ext-default",
      "interactionSource": "MOTO",
      "transactionId": "TX-2498912113",
      "transactionResponseCode": "00",
      "transactionResponseMessage": {
          "en": "Approved",
          "ar": "تمت الموافقة"
      }
  },
  "messages": {
      "en": "Approved",
      "ar": "تمت الموافقة"
  },
  "status": "SUCCESS",
  "showCaptcha": false
  }

You can receive the transaction response in the webhook.

Response structure at Ecommerce with 3DS

{
  "response": {
      "apiOperation": "PAY",
      "operation": "3dsecure_verify",
      "currency": "EGP",
      "result": "SUCCESS",
      "status": "AUTHENTICATION_INITIATED",
      "authenticationStatus": "AUTHENTICATION_AVAILABLE",
      "creationTime": "2023-10-16T11:53:51.094Z",
      "lastUpdatedTime": "2023-10-16T11:53:51.059Z",
      "totalAuthorizedAmount": 0,
      "totalCapturedAmount": 0,
      "totalRefundedAmount": 0,
      "authentication": {
          "channel": "PAYER_BROWSER",
          "purpose": "PAYMENT_TRANSACTION",
          "redirectHtml": "<div id=\"initiate3dsSimpleRedirect\" xmlns=\"http://www.w3.org/1999/html\"> <iframe id=\"methodFrame\" name=\"methodFrame\" height=\"100\" width=\"200\"> </iframe> <form id=\"initiate3dsSimpleRedirectForm\" method=\"POST\" action=\"https://mtf.gateway.mastercard.com/acs/mastercard/v2/method\" target=\"methodFrame\"> <input type=\"hidden\" name=\"threeDSMethodData\" value=\"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9tdGYuZ2F0ZXdheS5tYXN0ZXJjYXJkLmNvbS9jYWxsYmFja0ludGVyZmFjZS9nYXRld2F5Lzk2MDc0YmNhNmNlNGU1ZWZlMmZhNDExM2Y5MjdkOWQ2ZGUwY2ZiOTg5NGI5ZDU0ODYwZjc1NDI0OTg1MWZhNzkiLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjhmY2EyMmQ2LTNjOTktNDQ2NC04YmNjLWIyMmVmNTBhMzY2ZSJ9\" /> </form> <script id=\"initiate-authentication-script\"> var e=document.getElementById(\"initiate3dsSimpleRedirectForm\"); if (e) { e.submit(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } } </script> </div>",
          "version": "3DS2",
          "redirectUrl": "https://checkout.kashier.io/3dsRedirect/bdcab401-d3eb-4cb1-80a7-6bc59f595961?methodUrl=https://mtf.gateway.mastercard.com/acs/mastercard/v2/method&methodPostData=eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9tdGYuZ2F0ZXdheS5tYXN0ZXJjYXJkLmNvbS9jYWxsYmFja0ludGVyZmFjZS9nYXRld2F5Lzk2MDc0YmNhNmNlNGU1ZWZlMmZhNDExM2Y5MjdkOWQ2ZGUwY2ZiOTg5NGI5ZDU0ODYwZjc1NDI0OTg1MWZhNzkiLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjhmY2EyMmQ2LTNjOTktNDQ2NC04YmNjLWIyMmVmNTBhMzY2ZSJ9&mode=test"
      },
      "paymentMethod": {
          "type": "CARD",
          "card": {
              "cardBrand": "Mastercard",
              "storedOnFile": "TO_BE_STORED",
              "number": "512345******2346",
              "nameOnCard": "Mohamed Khaled",
              "expiry": {
                  "month": "12",
                  "year": "25"
              },
              "cardToken": "9d8332cb-6195-40ea-aed0-86c3aa60fbaa"
          }
      },
      "metaData": {
          "customerName": "Noura Mosaad",
          "merchantWebhook": "https://your-website.com/paymentWebhook",
          "redirect": true
      },
      "customer": {
          "reference": "01163550555"
      },
      "timestamp": "2022-12-15T13:54:01.606Z",
      "reconciliation": {
          "webhookUrl": "https://your-call-back-url.com",
          "merchantRedirect": "https://your-call-back-url.com?&signature=",
          "redirect": true
      },
      "merchantId": "MID-123-123",
      "order": {
          "amount": 100,
          "currency": "EGP",
          "callbackURL": "https://your-call-back-url.com",
          "systemOrderId": "bdcab401-d3eb-4cb1-80a7-6bc59f595961"
      },
      "description": "order description",
      "merchantRedirectUrl": "https://your-call-back-url.com?&signature=",
      "apiKeyId": "5d0003fc77c68a0018b05a6f",
      "method": "card",
      "creationDate": "2023-10-16T14:53:50.593Z",
      "orderId": "bdcab401-d3eb-4cb1-80a7-6bc59f595961",
      "merchantOrderId": "1697457230044",
      "orderReference": "TEST-ORD-96349",
      "paymentType": "ext-default",
      "interactionSource": "ECOMMERCE",
      "transactionId": "TX-2498912112",
      "transactionResponseCode": "AUTHENTICATION_IN_PROGRESS",
      "transactionResponseMessage": {
          "en": "Authentication in progress",
          "ar": "المصادقة قيد التقدم"
      }
  },
  "messages": {
      "en": "Authentication in progress",
      "ar": "المصادقة قيد التقدم"
  },
  "status": "SUCCESS",
  "showCaptcha": false
}

After a successful response, you should redirect to authentication.redirectUrl to generate the 3DS page. As soon as the transaction has completed, it will redirect to merchantRedirectUrl if reconciliation.redirect was equal to true; otherwise use 3D Secure handling.

You can receive the transaction response after 3DS processing in the webhook.

Meeza cards

Meeza (Egypt's national card scheme) is not a separate payment method — it's a card brand that Kashier detects from the card number and routes automatically. You submit a Meeza card exactly like any other card: paymentMethod.type: "CARD" with the PAN, expiry, and security code. There's no "meeza" value to send anywhere.

Kashier identifies a Meeza card by its BIN prefix (9 or 50) and picks the acquiring rail for you — normally the UPG gateway online, or the ISO 8583 rail on POS. If your account has an MPGS credential provisioned, Meeza traffic is routed to MPGS instead and follows the standard MPGS card flow (3DS, auth/capture, void, refund) described above.

Meeza is blocked on subscriptions/recurring

A Meeza card routed over UPG cannot be used for a subscription-origin (recurring) payment — the request fails with a MEEZA_NOT_ALLOWED error, because Meeza-over-UPG cards aren't tokenizable for recurring the way MPGS Visa/Mastercard cards are. See Recurring payments for the tokenizable card flow.

Meeza transactions use the same response/reason-code dictionary, statuses, and webhook shape as any other card — there's no Meeza-specific code table.

Pay with token

To make a payment transaction with a card token that has been saved, see Pay with card token.

Field reference

On this page