---
title: "Create Session"
method: POST
path: "/payment-intent/api/v2/direct/session"
---

# Create Session

`POST /payment-intent/api/v2/direct/session`

## Headers

- `deviceBrand` string
- `deviceModel` string
- `deviceType` string
- `language` string
- `sdkVersion` string
- `OSVersion` string

## Request body

- object
  - `amount` number, float, required — The total amount value of the payment. This parameter is required, and the format is a double - a number with 2 digits after the decimal point. For example 19.99
  - `currency` string, required — The currency of the payment. This is a 3-digit alphabetic code, following the ISO 4217 currency code standard. For example: SAR
  - `timestamp` string — The timestamp of the moment at which the create session request has been initiated.
  - `merchantReferenceId` string — The unique identifier for the session given added by the merchant. Must be a valid UUID
  - `signature` string, required — A parameter to ensure the security and authenticity of API communications. It involves generating a signature using the contents of the API request and secret keys, which is then sent along with the request.
  - `paymentIntentId` string — If you have previously generated a payment intent, you can use this parameter to link your order to the payment intent. This will process a payment for the specified payment intent.
  - `paymentOperation` 'Pay' | 'PreAuthorize' | 'AuthorizeCapture' — The type of payment operation to be performed. This is an optional parameter - if not submitted, the Geidea gateway will process a 'Pay' operation by default.
  - `cardOnFile` boolean — Indicates whether to store the payment method for future use. If you pass 'true' in this field, Geidea will save the card and will return a tokenId in the callback after the order. This tokenId can be used later to process a payment for the same customer using the saved payment method.
  - `metadata` object — Object that contain parameter to pass additional custom data
    - `custom` string — Custom value that can be passed in the request
  - `appearance` object — This object allows you to modify the appearance of the Geidea Checkout payment widget.
    - `merchant` object — An object containing parameters for merchant details customization on HPP
      - `name` string — A value indicating the name the merchant name displayed on HPP
      - `logoUrl` string — A value indicating the merchant logo Url to be passed and displayed on HPP
    - `showEmail` boolean — A boolean value indicating whether the email field should be displayed on the payment page.
    - `showAddress` boolean — A boolean value indicating whether the address fields should be displayed on the payment page.
    - `showPhone` boolean — A boolean value indicating whether the customer phone field should be displayed on the payment page.
    - `receiptPage` boolean — A boolean value indicating whether the payment receipt page should be displayed after the payment is completed.
    - `uiMode` 'modal' | 'dropin' | 'redirection' — Specifies the appearance of the HPP. Use 'dropin' to display a simplified version without the merchant logo and name. Use 'modal' to show the full version, including the merchant logo and name.
    - `styles` object — This object will allow you to style the HPP page to be displayed differently
      - `headerColor` string — Hexadecimal color value that will allow you to update the header color of HPP
      - `hppProfile` string — A value that changes the shape of the HPP. Available types are: simple or compressed
      - `hideGeideaLogo` boolean — A boolean value indicating whether to hide Geidea Logo from the bottom of the HPP page. Default is false
  - `language` 'en' | 'ar' — The language to be used on the checkout page.
  - `callbackUrl` string — The URL where the payment gateway should send the callback after the transaction is completed. It must have a valid SSL certificate and start with 'https://'
  - `subscriptionId` string — The subscription Id for which the payment is initiated. Must be a valid GUID. Subscription ID (generated from the create subscription API) can be passed in the request to capture the card on file details during the first transaction and later Geidea will auto-debit the customers as per the set frequency and interval based on securely stored token.
  - `returnUrl` string — A URL that can be used to redirect to a different page after the transaction has been completed
  - `customer` object — Customer object that specifies all details of the customer
    - `email` string — The email of the customer that can be collected in the transaction details
    - `phoneNumber` string — The phone number of the customer that can be collected in the transaction details
    - `phoneCountryCode` string — Country Code of the phone number of the customer
    - `firstName` string — A value indicating the customer's first name
    - `lastName` string — A value indicating the customer's last name
    - `address` object — The address of the customer including the shipping & billing addresses
      - `billing` object — The billing address of the customer to be collected in the transaction details
        - `country` string — The country code for the billing address of the customer. For example, "SAU" for Saudi Arabia
        - `city` string — The city name for the billing address of the customer.
        - `street` string — The street name for the billing address of the customer.
        - `postalCode` string — The postal code for the billing address of the customer.
      - `shipping` object — The shipping address of the customer to be collected in the transaction details
        - `country` string — The country code for the shipping address of the customer. For example, "SAU" for Saudi Arabia
        - `city` string — The city name for the shipping address of the customer.
        - `street` string — The street name for the shipping address of the customer.
        - `postalCode` string — The postal code for the shipping address of the customer.
  - `cofAgreement` object — Agreement object to specify the details of the agreement between the merchant & a customer for a specific transaction
    - `id` string — An id that can be used to make an agreement merchant & a customer for a specific transaction
    - `type` string — The type of agreement of a specific transaction. The value that can be used is "Unscheduled"
  - `initiatedBy` 'Internet' | 'Merchant' — A value indicating whether the request is started from Customer(Internet) or Merchant.
  - `tokenid` string — Tokenid that can be passed to create session for a CIT token payment or MIT unscheduled payment
  - `platform` object — Details of the platform used to run the payment page
    - `name` string — Name of the platform the payment page is launched on
    - `version` string — Version number of the platform
    - `pluginVersion` string — The plugin version of the payment page
    - `partnerId` string
  - `paymentOptions` object[] — A list of available of option to make available on the payment page
    - `label` 'Valu' | 'Souhoola' | 'GooglePay' | 'StcPay' | 'Tamara' | 'Tabby' | 'MeezaDigital' | 'bankinstallment' | 'card' — Label to show the payment method option as on the payment page
    - `paymentMethods` 'meezadigital' | 'valu' | 'souhoola' | 'googlepay' | 'stcpay' | 'tamara' | 'tabby' | 'bankinstallment' | 'card' — The payment method to display on the payment page. For example, 'visa', 'mastercard',... etc
  - `hideWallets` string[] — This parameter hides the device payment, and it should be passed correctly apple-pay / google-pay / samsung-pay
  - `order` object — The object indicating details of the order
    - `integrationType` string — A value indicating the type of integration of the payment gateway for this order
    - `description` string — A value to add a description of the order
    - `summary` object — An object indicating summary details of the orders
      - `subTotal` unknown
      - `shipping` string — The shipping details of the order
      - `vat` unknown
    - `statementDescriptor` object — A value indicating the statement details
      - `name` string — A value for the customer name
      - `phone` string — A value of the customer's phone number
    - `items` object[] — List of item objects
      - `merchantitemId` string — Id of the merchant's item
      - `name` string — The name of the item
      - `description` string — Description of the item
      - `categories` string — Categories that the item belongs to
      - `count` string — Quantity of the item
      - `price` unknown
      - `sku` string — The SKU of the item
  - `callbackHeaders` '{"key":"value"}', json

## Response `200`

200

- object
  - `session` object
    - `id` string
    - `amount` integer
    - `currency` string
    - `callbackUrl` string
    - `returnUrl` unknown
    - `expiryDate` string
    - `status` string
    - `merchantId` string
    - `merchantPublicKey` string
    - `language` string
    - `merchantReferenceId` string
    - `paymentIntentId` unknown
    - `paymentOperation` string
    - `cardOnFile` boolean
    - `cofAgreement` object
      - `id` unknown
      - `type` unknown
    - `initiatedBy` unknown
    - `tokenId` unknown
    - `customer` object
      - `id` string
      - `referenceId` string
      - `create` boolean
      - `setDefaultMethod` boolean
      - `email` string
      - `phoneNumber` string
      - `firstName` string
      - `lastName` string
      - `address` object
        - `billing` object
          - `country` string
          - `city` string
          - `street` string
          - `postalCode` string
        - `shipping` object
          - `country` string
          - `city` string
          - `street` string
          - `postalCode` string
    - `platform` object
      - `name` unknown
      - `version` unknown
      - `pluginVersion` unknown
      - `partnerId` unknown
    - `paymentOptions` unknown
    - `recurrence` object — If not passed in the original session creation. The default value will be null
      - `amount` integer
      - `currency` string
      - `cycleInterval` string
      - `frequency` integer
      - `typeOfPayment` string
      - `startDate` string
      - `endDate` string
      - `numberOfPayments` integer
      - `minimumDaysBetweenPayments` integer
      - `description` string
    - `order` object
      - `integrationType` string
      - `description` string
      - `summary` object
        - `subTotal` integer
        - `shipping` integer
        - `vat` integer
      - `statementDescriptor` object
        - `name` string
        - `phone` string
      - `items` object[]
        - `merchantItemId` string
        - `name` string
        - `description` string
        - `categories` string
        - `count` integer
        - `price` integer
        - `sku` string
    - `appearance` object
      - `merchant` object
        - `name` unknown
        - `logoUrl` unknown
      - `showEmail` boolean
      - `showAddress` boolean
      - `showPhone` boolean
      - `receiptPage` boolean
      - `styles` object
        - `headerColor` unknown
        - `hppProfile` unknown
        - `hideGeideaLogo` boolean
    - `metadata` object
      - `custom` unknown
    - `paymentMethod` object
      - `cardNumber` unknown
      - `cardholderName` unknown
      - `cvv` unknown
      - `expiryDate` object
        - `month` unknown
        - `year` unknown
    - `subscription` object
      - `number` string
      - `typeOfPayment` string
      - `occurenceType` string
      - `subscriptionid` string
      - `description` string
      - `startDate` string
      - `endDate` string
      - `cycleInterval` string
      - `cycleFrequencey` integer
      - `numberOfPayments` integer
      - `recurringPaymentAmount` unknown
      - `currency` string
  - `responseMessage` string
  - `detailedResponseMessage` string
  - `language` string
  - `responseCode` string
  - `detailedResponseCode` string

## Other responses

- `400` — 400

---

[API](https://skmtc.dev/geidea/apis/checkout-v2.md) · [All operations](https://skmtc.dev/geidea/apis/checkout-v2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/geidea/checkout-v2/revisions/873e534eeb01/schema)