--- updatedAt: 2025-06-25T21:34:30.000Z agentTools: projectIndex: https://docs.geidea.net/llms.txt --- # Create Session # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "checkout-v2", "version": "2.0" }, "servers": [ { "url": "https://api.merchant.geidea.net/payment-intent/api/" } ], "components": { "securitySchemes": { "sec0": { "type": "http", "scheme": "basic" } } }, "security": [ { "sec0": [] } ], "paths": { "/v2/direct/session": { "post": { "summary": "Create Session", "description": "", "operationId": "create-session-v2", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "currency", "signature" ], "properties": { "amount": { "type": "number", "description": "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", "default": 1850, "format": "float" }, "currency": { "type": "string", "description": "The currency of the payment. This is a 3-digit alphabetic code, following the ISO 4217 currency code standard. For example: SAR", "default": "EGP" }, "timestamp": { "type": "string", "description": "The timestamp of the moment at which the create session request has been initiated.", "default": "2/21/2024 5:16:48 AM" }, "merchantReferenceId": { "type": "string", "description": "The unique identifier for the session given added by the merchant. Must be a valid UUID.", "default": "10" }, "signature": { "type": "string", "description": "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.", "default": "tF04+uS/SE+z4Bx6JxtO7UAd/srkX9KK7pM3Ertp2iM=" }, "paymentIntentId": { "type": "string", "description": "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": { "type": "string", "description": "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.", "default": "Pay", "enum": [ "Pay", "PreAuthorize", "AuthorizeCapture" ] }, "cardOnFile": { "type": "boolean", "description": "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." }, "appearance": { "type": "object", "description": "This object allows you to modify the appearance of the Geidea Checkout payment widget.", "properties": { "showEmail": { "type": "boolean", "description": "A boolean value indicating whether the email field should be displayed on the payment page." }, "showAddress": { "type": "boolean", "description": "A boolean value indicating whether the address fields should be displayed on the payment page." }, "showPhone": { "type": "boolean", "description": "A boolean value indicating whether the customer phone field should be displayed on the payment page." }, "receiptPage": { "type": "boolean", "description": "A boolean value indicating whether the payment receipt page should be displayed after the payment is completed." }, "styles": { "type": "object", "properties": {} } } }, "language": { "type": "string", "description": "The language to be used on the checkout page.", "default": "en", "enum": [ "en", "ar" ] }, "callbackUrl": { "type": "string", "description": "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://'", "default": "https://www.callbackurl.com" }, "subscriptionId": { "type": "string", "description": "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.", "default": "02ed462c-62fc-4692-41f0-08dc3cbb381c" }, "returnUrl": { "type": "string", "description": "A URL that can be used to redirect to a different page after the transaction has been completed", "default": "https://www.geidea.net" }, "customer": { "type": "object", "description": "Customer object that specifies all details of the customer", "properties": { "email": { "type": "string", "description": "The email of the customer that can be collected in the transaction details", "default": "customer@email.com" }, "phoneNumber": { "type": "string", "description": "The phone number of the customer that can be collected in the transaction details", "default": "+966501231231" }, "address": { "type": "object", "description": "The address of the customer including the shipping & billing addresses", "properties": { "billing": { "type": "object", "description": "The billing address of the customer to be collected in the transaction details", "properties": { "country": { "type": "string", "description": "The country code for the billing address of the customer. For example, \"SAU\" for Saudi Arabia" }, "city": { "type": "string", "description": "The city name for the billing address of the customer." }, "street": { "type": "string", "description": "The street name for the billing address of the customer." }, "postalCode": { "type": "string", "description": "The postal code for the billing address of the customer." } } }, "shipping": { "type": "object", "description": "The shipping address of the customer to be collected in the transaction details", "properties": { "country": { "type": "string", "description": "The country code for the shipping address of the customer. For example, \"SAU\" for Saudi Arabia" }, "city": { "type": "string", "description": "The city name for the shipping address of the customer." }, "street": { "type": "string", "description": "The street name for the shipping address of the customer." }, "postalCode": { "type": "string", "description": "The postal code for the shipping address of the customer." } } } } } } }, "cofAgreement": { "type": "object", "description": "Agreement object to specify the details of the agreement between the merchant & a customer for a specific transaction", "properties": { "id": { "type": "string", "description": "An id that can be used to make an agreement merchant & a customer for a specific transaction", "default": "test123" }, "type": { "type": "string", "description": "The type of agreement of a specific transaction. The value that can be used is \"Unscheduled\"", "default": "Unscheduled" } } }, "tokenid": { "type": "string", "description": "Tokenid that can be passed to create session for a CIT token payment or MIT unscheduled payment" } } }, "examples": { "Request Example": { "value": { "amount": 1850, "currency": "EGP", "language": "en", "timestamp": "2/21/2024 5:16:48 AM", "callbackUrl": "https://webhook.site/8ef88a07-b575-40a4-9a27-f2e78edf931e", "merchantReferenceId": "10", "paymentIntentId": null, "paymentOperation": "Pay", "cardOnFile": false, "appearance": { "showEmail": false, "showAddress": false, "showPhone": false, "receiptPage": false, "styles": { "hideGeideaLogo": false }, "uiMode": "modal" }, "signature": "tF04+uS/SE+z4Bx6JxtO7UAd/srkX9KK7pM3Ertp2iM=" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"session\": {\n \"id\": \"8f370e23-b22a-40ed-833e-08dc85577cac\",\n \"amount\": 1850,\n \"currency\": \"EGP\",\n \"callbackUrl\": \"https://webhook.site/8ef88a07-b575-40a4-9a27-f2e78edf931e\",\n \"returnUrl\": null,\n \"expiryDate\": \"2024-06-05T13:21:22.8763081Z\",\n \"status\": \"Initiated\",\n \"merchantId\": \"4907f9f6-af43-434a-340a-08da8933ece3\",\n \"merchantPublicKey\": \"40225a89-be31-4f2e-a10a-27b2bbc4e3b3\",\n \"language\": \"en\",\n \"merchantReferenceId\": \"10\",\n \"paymentIntentId\": null,\n \"paymentOperation\": \"Pay\",\n \"cardOnFile\": false,\n \"cofAgreement\": {\n \"id\": null,\n \"type\": null\n },\n \"initiatedBy\": null,\n \"tokenId\": null,\n \"customer\": null,\n \"platform\": {\n \"name\": null,\n \"version\": null,\n \"pluginVersion\": null,\n \"partnerId\": null\n },\n \"paymentOptions\": null,\n \"recurrence\": null,\n \"order\": null,\n \"items\": null,\n \"appearance\": {\n \"merchant\": {\n \"name\": null,\n \"logoUrl\": null\n },\n \"showEmail\": false,\n \"showAddress\": false,\n \"showPhone\": false,\n \"receiptPage\": false,\n \"styles\": {\n \"headerColor\": null,\n \"hppProfile\": null,\n \"hideGeideaLogo\": false\n },\n \"uiMode\": \"modal\"\n },\n \"metadata\": {\n \"custom\": null\n },\n \"paymentMethod\": {\n \"cardNumber\": null,\n \"cardholderName\": null,\n \"cvv\": null,\n \"expiryDate\": {\n \"month\": null,\n \"year\": null\n }\n },\n \"subscription\": null\n },\n \"responseMessage\": \"Success\",\n \"detailedResponseMessage\": \"The operation was successful\",\n \"language\": \"EN\",\n \"responseCode\": \"000\",\n \"detailedResponseCode\": \"000\",\n \"signature\": \"7B/JrYqWy8DchAMVO/xYLXP0UoahQHFh2WNoPw6fQeA=\"\n}" } }, "schema": { "type": "object", "properties": { "session": { "type": "object", "properties": { "id": { "type": "string", "example": "8f370e23-b22a-40ed-833e-08dc85577cac" }, "amount": { "type": "integer", "example": 1850, "default": 0 }, "currency": { "type": "string", "example": "EGP" }, "callbackUrl": { "type": "string", "example": "https://webhook.site/8ef88a07-b575-40a4-9a27-f2e78edf931e" }, "returnUrl": {}, "expiryDate": { "type": "string", "example": "2024-06-05T13:21:22.8763081Z" }, "status": { "type": "string", "example": "Initiated" }, "merchantId": { "type": "string", "example": "4907f9f6-af43-434a-340a-08da8933ece3" }, "merchantPublicKey": { "type": "string", "example": "40225a89-be31-4f2e-a10a-27b2bbc4e3b3" }, "language": { "type": "string", "example": "en" }, "merchantReferenceId": { "type": "string", "example": "10" }, "paymentIntentId": {}, "paymentOperation": { "type": "string", "example": "Pay" }, "cardOnFile": { "type": "boolean", "example": false, "default": true }, "cofAgreement": { "type": "object", "properties": { "id": {}, "type": {} } }, "initiatedBy": {}, "tokenId": {}, "customer": {}, "platform": { "type": "object", "properties": { "name": {}, "version": {}, "pluginVersion": {}, "partnerId": {} } }, "paymentOptions": {}, "recurrence": {}, "order": {}, "items": {}, "appearance": { "type": "object", "properties": { "merchant": { "type": "object", "properties": { "name": {}, "logoUrl": {} } }, "showEmail": { "type": "boolean", "example": false, "default": true }, "showAddress": { "type": "boolean", "example": false, "default": true }, "showPhone": { "type": "boolean", "example": false, "default": true }, "receiptPage": { "type": "boolean", "example": false, "default": true }, "styles": { "type": "object", "properties": { "headerColor": {}, "hppProfile": {}, "hideGeideaLogo": { "type": "boolean", "example": false, "default": true } } }, "uiMode": { "type": "string", "example": "modal" } } }, "metadata": { "type": "object", "properties": { "custom": {} } }, "paymentMethod": { "type": "object", "properties": { "cardNumber": {}, "cardholderName": {}, "cvv": {}, "expiryDate": { "type": "object", "properties": { "month": {}, "year": {} } } } }, "subscription": {} } }, "responseMessage": { "type": "string", "example": "Success" }, "detailedResponseMessage": { "type": "string", "example": "The operation was successful" }, "language": { "type": "string", "example": "EN" }, "responseCode": { "type": "string", "example": "000" }, "detailedResponseCode": { "type": "string", "example": "000" }, "signature": { "type": "string", "example": "7B/JrYqWy8DchAMVO/xYLXP0UoahQHFh2WNoPw6fQeA=" } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": "{}" } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true } ```