Create payment session

curl -X POST "https://test-api.kashier.io/v3/payment/sessions" \  -H "Content-Type: application/json" \  -d '{    "expireAt": "2030-01-01 00:00:00+00:00",    "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": "YOUR_MID",    "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"  }'

{  "status": "CREATED",  "failureAttempts": 0,  "capturedAmount": 0,  "refundedAmount": 0,  "_id": "67adc07584f10c00121f6739",  "merchantId": "MID-XXXX-XXXX",  "expireAt": "2025-01-28 17:27:32.359000+00:00",  "maxFailureAttempts": 3,  "paymentParams": {    "display": "en",    "paymentType": "credit",    "amount": "100.00",    "currency": "EGP",    "order": "as8f64a5",    "merchantRedirect": "https://your-website.com/redirect",    "type": "one-time",    "allowedMethods": "card,wallet",    "redirectMethod": null,    "iframeBackgroundColor": "#FFFFFF",    "metaData": {      "customKey": "customValue",      "displayNotes": {        "key": "value"      }    },    "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",    "hash": "3a657fb8e653c024a4abdd31b084082c8bbd4d9438f98451ca42a4abeb49766d",    "storeName": "Demo",    "store": "Demo"  },  "apiKey": "{{merchant_api_key}}",  "history": [    {      "status": "CREATED",      "date": "2025-02-13 09:50:45.360000+00:00"    }  ],  "webhookNotifications": [],  "createdAt": "2025-02-13 09:50:45.363000+00:00",  "updatedAt": "2025-02-13 09:50:45.363000+00:00",  "__v": 0,  "sessionUrl": "https://payments.kashier.io/session/67adc07584f10c00121f6739?mode=test"}

Creates a payment session. The response contains a sessionUrl that is used to redirect the customer to the payment page — you can use it as the src attribute in a link or iframe.

Authorization

secretKey apiKey

Authorization<token>

Merchant secret key used to identify the merchant, obtained from Kashier's dashboard. Pass the raw secret key value in the Authorization header (NOT a "Bearer" token).

In: header

api-key<token>

API key obtained from the merchant dashboard under the Integrations section. The API key is different for the live and test environments, so make sure to use the correct one for each.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

expireAt*string

When the payment session expires. Must be a future ISO 8601 timestamp.

maxFailureAttempts*integer

Maximum number of payment attempts.

paymentType?string

Payment type, e.g. credit.

amount*string

Order amount, e.g., 100.

currency*string

Order currency, e.g., EGP.

Value in

"EGP"
"USD"
"GBP"
"EUR"

order*string

Unique order identifier. (The docs' body table names this field orderId, but request and response examples use order.)

merchantId*string

Merchant account number or merchant ID, e.g., MID-123-123.

mode?string

Mode of operation, test or live, e.g., mode="test". (Documented in the body table but not present in the docs' request example.)

metaData?

Order metadata. displayNotes is a nested key/value object whose note will be displayed on the PaymentUI screen, e.g. {"customKey": "customValue", "displayNotes": {"key": "value"}}.

description?string

Order description; must be less than 120 characters.

allowedMethods?string

Defines allowed payment methods. Default: card, bank_installments, wallet, bnpl. If you want to display only a specific provider (for example, Valu or QNB), you can do so by specifying it within array brackets alongside its payment method. For example: bnpl[valu], bank_installments[qnb], and so on.

defaultMethod?string

To determine which method you want PaymentUI to open on. By default PaymentUI opens on card method. defaultMethod accepts the pattern "method,provider/abbreviation". Example: for the installment method use bank_installments; to open PaymentUI on certain installment plans of NBE bank use bank_installments,NBE.

merchantRedirect*string

merchantRedirect should be URI encoded: urlencode(https://www.your_website.com/redirect)

serverWebhook?string

Pass an endpoint to receive server-to-server notifications. Your application only needs a page that accepts unauthenticated POST requests; the event object is sent as JSON in the request body.

redirectMethod?|

The redirection method after payment. Default method is get, ex: redirectMethod="post"

failureRedirect?boolean

To choose to redirect after first payment failure or not. Its value is TRUE or FALSE; default value is TRUE.

connectedAccount?string

Used in case of making payments on behalf of your Connected Account by passing the Sub Merchant/Connected Account Merchant Id, e.g. connectedAccount="MID-452-644".

type*string

Defines the type of Kashier origin. Default: external.

brandColor?string

Specifies branding color using a hex or rgba value. Default: rgba(45, 164, 78, 0.9).

display*string

Specifies the display language of the I-frame. Options: ar or en.

Value in

"ar"
"en"

iframeBackgroundColor?string

Background color of the payment iframe, e.g. #FFFFFF.

manualCapture?boolean

TRUE: Authorize first, then capture/release. FALSE: Direct capture without authorization.

customer*

Customer information. It should include customer.reference, which will be used to link the merchant's customer with the payment's customer, and it should only be included when saveCard is optional or forced.

saveCard?string

Defines if card information is saved. Options: optional or forced.

Value in

"optional"
"forced"

retrieveSavedCard?boolean

Whether to retrieve the customer's saved cards on the payment page.

interactionSource?string

Must be MOTO or ECOMMERCE when using a token or saving a card for repeat payments.

Value in

"MOTO"
"ECOMMERCE"

enable3DS?boolean

TRUE: Enables 3DS for saved card payments. FALSE: Disables 3DS.

notes?string

Add any additional information about this payment. This could include special instructions, or context for the recipient.

Authorization

Request Body

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Create payment session

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`