Payment sessions

Kashier's payment sessions make transactions more secure and efficient. With a single API call, you can create payments without exposing sensitive data in query strings, and session history tracking lets you monitor every action in real time. This page walks through creating a session, sending the customer to pay, and confirming the result.

Step 1: Create a payment session

curl --location 'https://test-api.kashier.io/v3/payment/sessions' \
  --header 'Authorization: YOUR_TEST_SECRET_KEY' \
  --header 'api-key: YOUR_TEST_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "expireAt": "2030-01-28T17:27:32.359Z",
  "maxFailureAttempts": 3,
  "paymentType": "credit",
  "amount": "100.00",
  "currency": "EGP",
  "order": "8f64saf6sa4",
  "merchantRedirect": "https://your-website.com/redirect",
  "display": "en",
  "type": "one-time",
  "allowedMethods": "card,wallet",
  "redirectMethod": null,
  "iframeBackgroundColor": "#FFFFFF",
  "metaData": {
      "customKey": "customValue",
      "displayNotes": {"key": "value"}
  },
  "merchantId": "MID-XXXX-XXX",
  "failureRedirect": false,
  "brandColor": "#FF5733",
  "defaultMethod": "card",
  "description": "Payment for order ORD123456",
  "manualCapture": false,
  "customer": {
      "email": "[email protected]",
      "reference": "894321"
  },
  "saveCard": "optional",
  "retrieveSavedCard": true,
  "interactionSource": "ECOMMERCE",
  "enable3DS": true,
  "serverWebhook": "https://your_webhook_url",
  "notes": "Special handling required"
}'

Headers

Full parameter and response reference → Create payment session.

Step 2: Send the customer to pay

The response to the create call includes a sessionUrl. You have two options for getting the customer to it:

• Redirect — send the customer's browser straight to sessionUrl. Kashier handles the checkout UI and returns them to your merchantRedirect URL afterward.
• Embed — render sessionUrl inside your own page in an iframe instead of redirecting away:

<iframe src="https://payments.kashier.io/session/67adc07584f10c00121f6739?mode=test"></iframe>

This embed flow was formerly documented as the "Payment UI Builder".

Merchant details

• Merchant ID
• API key
• Secret key

Order details

• Order ID — unique order reference between merchant and Kashier
• Amount
• Currency

Payment method

Select the payment methods to enable:

• Card
• Wallet
• Bank installment
• Buy now pay later

Redirect settings

• Redirect URL
• Redirect method — Get or Post
• Redirect failure — True or False

Display settings

• Display language — English or Arabic
• Display mode — Test or Live
• Brand color — e.g. #00bcbc

Getting the result out of an embedded checkout

When you embed rather than redirect, the customer never leaves your page, so there is no redirect landing you can read the outcome from. The checkout talks back to the page that hosts it with window.postMessage. Add a message listener on your page and switch on e.data.message.

What you receive depends on how you embedded it.

If you embed with Kashier's checkout script, the script sits between the checkout and your page and re-emits a small, clean set:

If you render sessionUrl in your own <iframe>, as in the snippet above, there is no script in between and you receive the checkout page's own messages directly:

A minimal listener for the raw-iframe case:

window.addEventListener('message', (e) => {
  switch (e.data?.message) {
    case 'contentLoaded':
      // checkout is ready — hide your spinner
      break;
    case 'paymentSuccess':
      // show a provisional success state, then confirm server-side
      break;
    case 'closeIframe':
      // customer dismissed the checkout — remove your overlay
      break;
    case 'urlRedirection':
      window.location.replace(e.data.params.redirectUrl);
      break;
  }
});

Step 3: Verify the result

curl --location 'https://test-api.kashier.io/v3/payment/sessions/:sessionId/payment' \
  --header 'Authorization: YOUR_TEST_SECRET_KEY'

Headers

Full parameter and response reference → Get payment session.

Next steps