Overview

MOTO (Mail Order / Telephone Order) is a payment method that allows merchants to process card payments on behalf of their customers when the customer provides their card details remotely, typically over the phone or through a mail-order transaction.

Unlike standard eCommerce payments, where the customer enters their card details through an online payment page and completes the required 3D Secure (3DS) authentication, MOTO transactions are initiated by the merchant on behalf of the customer.

Geidea Payment Gateway supports MOTO transactions through the existing Create Session API, allowing merchants to initiate MOTO payments by specifying the appropriate transaction initiation parameter.

Prerequisites

Before integrating and processing MOTO transactions, merchants must ensure that the following requirements are met:

MOTO Feature Activation: The MOTO feature must be enabled on the merchant's account in Geidea PGW.
Environment Activation: The feature must be enabled for the respective environment (Sandbox or Production) in which the merchant intends to process MOTO transactions.
Geidea Support Request: Merchants must contact Geidea Support to request MOTO activation for their account.

❗️
Important
MOTO transactions cannot be initiated unless the feature is enabled on the merchant's account.

If a merchant attempts to initiate a MOTO transaction without having the feature enabled, the Create Session API will return the following error:

Parameter	Value
Response Code	`110`
Response Message	`HPP Integration error`
Detailed Response Code	`019`
Detailed Response Message	`Invalid initiated by parameter`

How to Integrate MOTO

Merchants can initiate MOTO transactions using the existing Geidea Create Session API. No separate API endpoint is required.

The integration follows the below steps:

Step 1 Create a Payment Session

Call the Create Session API using the standard request parameters required to initiate a payment session.

The key difference when initiating a MOTO transaction is the initiatedBy parameter.

Set the parameter as follows:

Parameter	Value	Description
`initiatedBy`	`moto`	Identifies the transaction as a Mail Order / Telephone Order payment.

❗️
Important

The initiatedBy parameter must be explicitly set to moto to initiate a MOTO transaction.

If the parameter is omitted or set to another value(internet or merchant), the transaction will follow the standard eCommerce payment flow.

Standard eCommerce transactions may require 3D Secure (3DS) authentication, whereas MOTO transactions follow the MOTO processing flow.

Sample Create Session Request

The following is an example of a Create Session API request for initiating a MOTO payment.

Request Payload:

{
    "amount": 1,
    "currency": "SAR",
    "language": null,
    "callbackUrl": null,
    "merchantReferenceId": null,
    "paymentOperation": "pay",
    "returnUrl": null,
    "cardOnFile": false,
    "initiatedBy": "moto",
    "uiMode": "modal",
    "timeStamp": "2026-11-03T09:45:02.641Z",
    "signature": "5Jp1wZlMDKUoeEJgzc4lrmYjEDKHg8EL6789u23FVM0="
}

Note
The above payload is provided as an example. Merchants should populate the required fields according to their integration requirements and the standard Create Session API specifications.

The signature must be generated according to Geidea's API signature generation guidelines using the actual request parameters.

Step 2 Complete the Payment

Once the Create Session API request is successfully processed:

Geidea PGW validates the request and creates a payment session.
The merchant receives the generated sessionId.
The merchant proceeds with the standard Geidea payment integration flow to process the payment using the generated session.

The merchant should follow the existing integration flow for submitting the payment details and completing the transaction.

Important Integration Considerations

Merchants should consider the following when implementing MOTO:

Consideration	Description
Feature activation	MOTO must be enabled on the merchant's account before initiating transactions.
Environment configuration	Activation is required for each environment (Sandbox and Production) in which MOTO will be used.
API endpoint	MOTO uses the existing Create Session API. No dedicated MOTO endpoint is required.
Transaction initiation	The `initiatedBy` parameter must be set to `moto`.
Standard payment flow	The remaining payment integration flow follows the existing Geidea PGW integration process.
3DS authentication	MOTO transactions follow the MOTO processing flow rather than the standard eCommerce 3DS authentication flow.

Quick Integration Checklist

Contacted Geidea Support to request MOTO activation.
Confirmed that MOTO is enabled in the Sandbox environment.
Successfully generated a payment session using the Create Session API.
Included "initiatedBy": "moto" in the Create Session request.
Successfully tested a MOTO transaction in Sandbox.
Requested MOTO activation in the Production environment.
Successfully tested a MOTO transaction in Production.