Introduction

This is the most commonly known type of integration that you need to accelerate your business applications. The payment gateway integration will be done in simple few steps, minimum development efforts, and with various capabilities.

How it Works

To directly create a charge , submit a request to create a charge using the Create a Charge endpoint

there is two options to get your payment page

1- Ecom prepared payment page to show the charge details and select the payment page from it .

2- Use payment network payment page directly ( this require you to send the target payment method at the charge create request)

3- Merchant should call the find charge details by payment token getting from the initiate charge response

Pay Process

After receiving the charge response , it will include the payment url the you should redirect your client to it , it will be either Ecom prepared payment page or the payment gateway page itself ( based on your selection in the creation of charge process)

Step one : initiate charge :Example of request (initiate charge) :

❗️
X-Ecom-Mid and API token is required in each request and The payment token is required for the get payment details

📘
Create Charge endpoint: https://api-sandbox.ecom.io/eapi/v1/api/charges

curl --request POST \
     --url https://api-sandbox.ecom.io/eapi/v1/api/charges \
     --header 'X-Ecom-Api-Token: pk_test_xxxxxx' \
     --header 'X-Ecom-Mid: 123456' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": {
    "currency": "KWD",
    "value": 10
  },
  "options": {
    "mode": "INDIRECT",
    "paymentMethod": "KNET"
  },
  "urls": {
    "successUrl": "https://www.success.com/pay",
    "errorUrl": "https://www.error.com/pay"
  },
  "description": "pay order",
  "language": "ar",
  "references": {
    "merchantReference": "ref"
  },
  "customer": {
    "fullName": "name",
    "phoneCode": "+965"
  }
}
'

<?php
$url = 'https://api-sandbox.ecom.io/eapi/v1/api/charges';
$headers = [
    'X-Ecom-Api-Token: pk_test_xxxxxx',
    'X-Ecom-Mid: 123456',
    'accept: application/json',
    'content-type: application/json'
];
$data = [
    'amount' => [
        'currency' => 'KWD',
        'value' => 10
    ],
    'options' => [
        'mode' => 'INDIRECT',
        'paymentMethod' => 'KNET'
    ],
    'urls' => [
        'successUrl' => 'https://www.success.com/pay',
        'errorUrl' => 'https://www.error.com/pay'
    ],
    'description' => 'pay order',
    'language' => 'ar',
    'references' => [
        'merchantReference' => 'ref'
    ],
    'customer' => [
        'fullName' => 'name',
        'phoneCode' => '+965'
    ]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

const axios = require('axios');

const url = 'https://api-sandbox.ecom.io/eapi/v1/api/charges';
const headers = {
    'X-Ecom-Api-Token': 'pk_test_xxxxxx',
    'X-Ecom-Mid': '123456',
    'accept': 'application/json',
    'content-type': 'application/json'
};
const data = {
    amount: {
        currency: 'KWD',
        value: 10
    },
    options: {
        mode: 'INDIRECT',
        paymentMethod: 'KNET'
    },
    urls: {
        successUrl: 'https://www.success.com/pay',
        errorUrl: 'https://www.error.com/pay'
    },
    description: 'pay order',
    language: 'ar',
    references: {
        merchantReference: 'ref'
    },
    customer: {
        fullName: 'name',
        phoneCode: '+965'
    }
};

axios.post(url, data, { headers })
    .then(response => {
        console.log(response.data);
    })
    .catch(error => {
        console.error(error);
    });

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

class Program
{
    private static readonly HttpClient client = new HttpClient();

    static async Task Main()
    {
        var url = "https://api-sandbox.ecom.io/eapi/v1/api/charges";
        var request = new HttpRequestMessage(HttpMethod.Post, url);

        request.Headers.Add("X-Ecom-Api-Token", "pk_test_xxxxxx");
        request.Headers.Add("X-Ecom-Mid", "123456");
        request.Headers.Add("accept", "application/json");
        
        var data = new
        {
            amount = new { currency = "KWD", value = 10 },
            options = new { mode = "INDIRECT", paymentMethod = "KNET" },
            urls = new { successUrl = "https://www.success.com/pay", errorUrl = "https://www.error.com/pay" },
            description = "pay order",
            language = "ar",
            references = new { merchantReference = "ref" },
            customer = new { fullName = "name", phoneCode = "+965" }
        };

        var json = JsonSerializer.Serialize(data);
        request.Content = new StringContent(json, Encoding.UTF8, "application/json");

        try
        {
            var response = await client.SendAsync(request);
            response.EnsureSuccessStatusCode();
            var responseBody = await response.Content.ReadAsStringAsync();
            Console.WriteLine(responseBody);
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}

HTTP Method: POST

Headers:

X-Ecom-Mid: 123456: The merchant ID (Mid)

X-Ecom-Api-Token

Request Body:

The body contains the payment details:

-amount : Specifies the payment amount and currency.

.currency: The currency code for the payment. In this case, it is set to KWD (Kuwaiti Dinar).

value: The payment amount. Here, the amount is 10 KWD.

-optionsContains additional payment options.

mode: Set to INDIRECT, which means the customer will be redirected to an e-com payment page to complete the payment.

paymentMethod: Specifies the payment method to be used. In this case, it is set to KNET, which is a popular payment gateway in Kuwait.

-urlsContains URLs for handling payment success or failure.

successUrl: The URL to which the customer will be redirected after a successful payment.

Example: https://www.success.com/pay

errorUrl: The URL to which the customer will be redirected if the payment fails or is canceled.

Example: https://www.error.com/pay

-descriptionA brief description of the payment.

Example: "pay order"

-languageSpecifies the language for the payment page.

Example: "ar" (Arabic)

-referencesContains merchant-specific reference information.

merchantReference: A unique identifier for the transaction, provided by the merchant.

Example: "ref"

-customerContains customer details.

fullName: The full name of the customer.

Example: "name"

phoneCode: The phone code for the customer's phone number.

Example: "+965" (Kuwait's country code)

Example of response (Charge) :

{
  "data": {
    "paymentStatus": "INITIATED",
    "timezone": "Asia/Kuwait",
    "createdAt": "1737813032",
    "expiry": {
      "expiryPeriod": "MILLISECONDS",
      "period": 10000000,
      "expiryDate": "1737823032"
    },
    "ecomId": "123456789",
    "txnType": "charge",
    "paymentUrl": " https://www.pay.ecom.io",
    "paymentToken": "6936dd92-5069-4efe-95ec-36e3993523dc"
  }
}

data The main container for the response data.
paymentStatus Indicates the current status of the payment.

Value: "INITIATED"

This means the payment has been successfully initiated, and the customer can now be redirected to the payment page.

timezone: Specifies the timezone used for timestamps in the response.Value: "Asia/Kuwait"

All timestamps (e.g., createdAt, expiryDate) are based on this timezone.

createdAt: The timestamp when the payment was initiated.Value: "1737813032"

This is a Unix timestamp (in seconds) representing the date and time in the specified timezone (Asia/Kuwait).

expiry: Contains details about the payment's expiry.expiryPeriod: The unit of time used for the expiry period.

Value: "MILLISECONDS"

period: The duration after which the payment will expire.

Value: 10000000 (10,000,000 milliseconds, which is equivalent to 10,000 seconds or approximately 2.78 hours).

expiryDate: The timestamp when the payment will expire.

Value: "1737823032"

This is a Unix timestamp (in seconds) representing the expiry date and time in the specified timezone (Asia/Kuwait).

ecomId : A unique identifier for the payment transaction, generated by the e-com platform.

Value: "123456789"

txnType : Specifies the type of transaction.

Value: "charge"

This indicates that the transaction is a payment charge.

paymentUrlThe URL to which the customer should be redirected to complete the payment.

Value: "https://www.pay.ecom.io"

This is the e-com payment page where the customer can enter their payment details.

paymentToken A unique token associated with the payment.

Value: "6936dd92-5069-4efe-95ec-36e3993523dc"

This token can be used to retrieve payment details or track the payment status later.

Step two : return payment token after payment , merchant will receive payment token on his callback url

example : "[www.example.com/E_LINKS/pending?language=en&paymentToken=a7cf00eb-9d6d-40f0-96e9-28785c952fbc]"

Step three : find charge details by payment token:

📘
Find charge details endpoint: https://api-sandbox.ecom.io/eapi/v1/api/charges

Example of request (find charge)

HTTP Method: GET

Headers:

X-Ecom-Mid: 123456: The merchant ID (Mid)

X-Ecom-Api-Token

Params:

paymentToken

Example of request (find charge)

{
  "data": {
    "amount": {
      "value": 100.505,
      "currency": "KWD"
    },
    "options": {
      "mode": "DIRECT",
      "paymentMethod": "CREDIT_CARD",
      "templateId": "12xaasdasdasd34"
    },
    "urls": {
      "successUrl": "https://www.host.com/pay",
      "errorUrl": "https://www.host.com/pay"
    },
    "customer": {
      "fullName": "Ali",
      "phoneCode": "+965",
      "phoneNumber": "66778899",
      "email": "example@example.com"
    },
    "references": {
      "merchantReference": "string",
      "references2": "string"
    },
    "description": "pay order",
    "order": {
      "ref": "151a3637-7f36-4952-9b10-4ed452c91bb6",
      "placedAt": "2025-02-04T09:09:22.200Z",
      "products": [
        {
          "nameEn": "Product Name English",
          "nameAr": "Product Name English",
          "qty": 2,
          "price": 5
        }
      ]
    },
    "language": "en",
    "metadata": {
      "key1": "string",
      "key2": "string",
      "key3": "string",
      "key4": "string",
      "key5": "string"
    },
    "id": "123456789",
    "status": "INITIATED",
    "product": "E_API",
    "source": {
      "paymentMethod": "KNET"
    },
    "paymentNetwork": {
      "status": "CAPTURED",
      "paymentMethod": "KNET",
      "ecomId": "f6538020-a3e5-497b-ba8f-eca840d411ce",
      "transactionId": "bcd6474e-3297-49ce-aa24-a870e2683c57",
      "transactionDate": "2025-02-04T09:09:22.487Z",
      "paymentId": "fa1c6faa-0a10-41be-8f90-a2205edf7243",
      "trackingId": "147625b3-235a-495f-b4aa-d83c1aad16d9",
      "referenceId": "da672435-9c51-4688-bfea-de70b101a243",
      "authorizationId": "32961191-3cdc-4c44-85b3-aeb68f395b2b",
      "orderId": "29f8d9df-3439-4d4a-9bc4-5954acb7b375"
    },
    "ecomReference": "123456789",
    "createdAt": "2022-01-01T00:00:00.000Z",
    "expiresAt": "2022-01-01T00:00:00.000Z",
    "paymentUrl": "https://www.pay.ecom.io",
    "merchant": {
      "mid": "13232",
      "fullNameAr": "John Doe",
      "fullNameEn": "John Doe",
      "email": "test@example.com",
      "phoneNumber": "123456789",
      "logoUrl": "https://example.com/logo.png",
      "websiteLink": "https://example.com",
      "description": "John Doe"
    },
    "availablePaymentMethods": [
      "KNET"
    ]
  }
}