---
title: "Create Session"
method: POST
path: "/v3/sessions"
tags: ["Sessions"]
---

# Create Session

`POST /v3/sessions`

Creates a session for embedded payment flows (COLLECT_DETAILS or COMPLETE_PAYMENT).

## Request body

- object
  - `PaymentMode` 'COMPLETE_PAYMENT' | 'COLLECT_DETAILS', required — Defines session mode. COLLECT_DETAILS or COMPLETE_PAYMENT
  - `Order` object, required — Order information related to the payment..
    - `Amount` number, required — The payment amount must be greater than 0.
    - `Currency` 'SAR' | 'BHD' | 'AED' | 'QAR' | 'OMR' | 'KWD' | 'JOD' | 'EGP' — The currency ISO code you want to display to the customer, by default is the same as the base currency of the country API.
    - `ExternalIdentifier` string — You may use as additional information to be stored with the transaction.
  - `SupportedNetworks` string[] — Specifies the allowed card networks for the session such as: ["visa", "masterCard", "mada", "amex"].
  - `SaveCardOptions` object — Controls card tokenization behavior.
    - `SaveToken` boolean — If true, saves the card as a token after successful payment.
    - `ShowSavedCardsInCardView` boolean — If true, saved cards will appear in the embedded card view.
    - `RetrieveSavedTokens` boolean — If true, retrieves the customer’s previously saved tokens.
  - `SupportedPaymentMethods` string[] — Payment methods to show in the embedded view such as: ["card", "knet", "googlepay", "applepay"] If not sent, all payment methods enabled on your account will appear automatically.
  - `SessionExpiry` string, date-time — The session expiration date. Must be in UTC timezone.
  - `ThreeDS` object — Enables or disables 3D Secure authentication.
    - `Enabled` boolean — If true, the user will be required to complete the OTP step.
  - `OperationType` 'AUTHORIZE' | 'PAY' | 'VERIFY' — Defines the type of payment operation.
  - `Suppliers` object[] — Required only if Multi-Vendor feature is enabled.
    - `SupplierCode` integer — The supplier code you need to associate the invoice with.
    - `ProposedDepositShare` number — The amount that the supplier will get after paying the invoice.
    - `InvoiceShare` number — Amount specified for this supplier from the total invoice value.
  - `Customer` object — Customer information that will be returned back to you in webhook events.
    - `Name` string — Customer's name.
    - `Mobile` object
      - `CountryCode` string — The maximum country code length is 4 and match the following regular expression: ^(?:(\+)|(00)|(\*)|())\d{1,4}$
      - `Number` string — The maximum mobile number length is 11 and matches the following regular expression: ^(?:(\+)|(00)|(\*)|())\d{6,14}(#?)$
    - `Email` string — Customer's email address.
    - `Reference` string — Refers to the order or transaction ID in your own system that you can link with the invoice generated for reporting purposes.
    - `CivilId` string — Extra customer identification information (optional).
  - `IntegrationUrls` object — URLs for redirecting and receiving payment status notifications.
    - `Redirection` string — URL where the user is redirected after making the payment. Use this URL to check the payment status.
    - `Webhook` string — You will get the webhook events for the created invoice on the specified Webhook URL. This includes transactions webhook, refunds webhook, capture/release webhook. The secret key for this URL will be the same as your webhook URL used in the dashboard. If you don't add this parameter, MyFatoorah sends the webhook event to the one configured in the dashboard.
  - `Language` 'EN' | 'AR' — Invoice language.
  - `MetaData` object — Custom fields stored with the transaction and returned in the webhook.
    - `UDF1` string
    - `UDF2` string
    - `UDF3` string
    - `UDF4` string
    - `UDF5` string

## Response `201`

Session created successfully

- object
  - `IsSuccess` boolean — Indicates if the request was successful.
  - `Message` string — Response message associated with the request.
  - `ValidationErrors` object[] — A model that contains two keys "Name" and "Error". This is used to indicate the validation result for all parameters you have sent in your request. This can have one or more items based on the invalid parameter count.
  - `Data` object — Session details.
    - `SessionId` string — Unique identifier of the session used in embedded integration.
    - `SessionExpiry` string — Timestamp indicating when the session will expire.
    - `EncryptionKey` string — Key used to decrypt the payment result returned in the callback when using Embedded integration (COMPLETE_PAYMENT Mode).
    - `OperationType` string — The operation associated with the created session.
    - `Order` object — Order details associated with the session.
      - `Amount` number — Order amount submitted in the session.
      - `Currency` string — Currency code submitted in the session.
      - `ExternalIdentifier` string — External identifier submitted in the session.
    - `Customer` object — Customer information returned with the session.
      - `Reference` string — Customer reference that was passed during session creation.
      - `Cards` object[] — List of token cards associated with the customer.
        - `Is3DSVerified` boolean — Indicates if the card has been verified with 3D Secure.
        - `Token` string — Token representing the saved card.
        - `Number` string — Masked card number (PAN).
        - `Brand` string — Card brand (VISA, MasterCard, etc.).

---

[API](https://skmtc.net/myfatoorah/apis/myfatoorah-api-v3.md) · [All operations](https://skmtc.net/myfatoorah/apis/myfatoorah-api-v3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/myfatoorah/myfatoorah-api-v3/revisions/994a74287a16/schema)