Merchant Initiated (MIT)

Merchant Initiated (MIT) Integration Guide

This document outlines the process for conducting Merchant-Initiated Transactions (MIT) using the Geidea platform. The flow is divided into two primary steps: card tokenization and initiating MIT transactions.

Step 1: Customer Card Tokenization

To perform MIT transactions, the first step is to collect the customer payment information by tokenizing the customer's card during their initial payment. Card tokenization is essential for storing the card information securely for future transactions.

Session Creation for Card Tokenization

To tokenize a card for MIT transactions, the session creation request must include additional mandatory parameters :

1. initiatedBy: The value should be set to "Internet".
2. cardOnFile: The value should be set to "True".
3. cofAgreement: An object containing the below:
   1. ID: An unique Agreement ID for each transaction.
   2. type: The value should be set to "Unscheduled".

Below is a sample Request for Tokenization Session Creation:

📘

Usage of the API environment endpoints

Please make sure you use the correct endpoint based on your environment

• KSA Environment: https://api.ksamerchant.geidea.net/
• Egypt Environment: https://api.merchant.geidea.net/
• UAE Environment: https://api.geidea.ae/

curl -X POST https://api.ksamerchant.geidea.net/payment-intent/api/v2/direct/session \
-H "accept: application/json" \
-H "authorization: Basic <encoded_auth_header>" \
-H "content-type: application/json" \
-d '{
  "amount": "<amount>",
  "currency": "<currency>",
  "timestamp": "<timestamp>",
  "merchantReferenceId": "<merchant_reference_id>",
  "signature": "<signature>",
  "paymentOperation": "Pay",
  "cardOnFile": true,
  "callbackUrl": "https://webhook.site/5dc9b06d-4166-49c2-9db5-81f9734cea46",
  "initiatedBy": "Internet",
  "cofAgreement": {
    "id": "<agreement_id>",
    "type": "unscheduled"
  }
}'

Once the payment is successful, you will receive a tokenId at the specified callback URL. Ensure that both tokenId and the agreementIdare securely stored alongside with the customer’s information.

📘

The tokenId is created as an unique Id for each card.

📘

Please refer to creating signature section here

Step 2: Initiating MIT Transactions

This step involves initiating a transaction using the previously tokenized card. The process has two parts:

2.1 Session Generation for MIT

Before initiating an MIT transaction, you must generate a new session, including the tokenId and the agreementId. Ensure that the below mandatory parameters are added to the request:

1. initiatedBy: The value should by set to "Merchant".
2. agreementId: Use the same agreement ID that was used during tokenization.
3. agreementType: The value should be set to "Unscheduled".
4. tokenId: The token received from the callback in Step 1.

Below is a sample Request for Session Creation:

curl -X POST https://api.ksamerchant.geidea.net/payment-intent/api/v2/direct/session \
-H "accept: application/json" \
-H "authorization: Basic <encoded_auth_header>" \
-H "content-type: application/json" \
-d '{
  "amount": "<amount>",
  "currency": "<currency>",
  "timestamp": "<timestamp>",
  "merchantReferenceId": "<merchant_reference_id>",
  "signature": "<signature>",
  "paymentOperation": "Pay",
  "callbackUrl": "https://webhook.site/5dc9b06d-4166-49c2-9db5-81f9734cea46",
  "initiatedBy": "Merchant",
  "agreementId": "<agreement_id>",
  "agreementType": "unscheduled",
  "tokenId": "<token_id>"
}'

2.2 Initiating the MIT Transaction

To initiate the MIT transaction, use the sessionId generated in the previous step. A new signature is also required for this session.

2.3 Hashing Signature Steps

1. Concatenate the string of {MerchantPublicKey, SessionId, TimeStamp}.
2. Hash (SHA-256) this concatenated string with (Merchant_API_Password).
3. Convert Hashed Value to Base64Str

Sample code for signature generation:

<?php

function generate_MIT_signature($merchant_public_key, $session_id, $timestamp, $api_password) {
    // Step 1: Concatenate strings
    $data_string = $merchant_public_key . $session_id . $timestamp;

    // Step 2: Generate HMAC-SHA256 hash
    $hash = hash_hmac('sha256', $data_string, $api_password, true);

    // Step 3: Base64 encode
    return base64_encode($hash);
}

?>

using System;
using System.Text;
using System.Security.Cryptography;

public class SignatureHelper
{
    public static string GenerateMITSignature(string merchantPublicKey, string sessionId, string timeStamp, string apiPassword)
    {
        // Step 1: Concatenate
        string data = merchantPublicKey + sessionId + timeStamp;

        // Step 2: HMAC-SHA256 with apiPassword as key
        byte[] keyBytes = Encoding.UTF8.GetBytes(apiPassword);
        byte[] dataBytes = Encoding.UTF8.GetBytes(data);

        using (var hmac = new HMACSHA256(keyBytes))
        {
            byte[] hashBytes = hmac.ComputeHash(dataBytes);

            // Step 3: Base64 encode
            return Convert.ToBase64String(hashBytes);
        }
    }
}

Below is a sample Request for Initiating MIT:

bash
curl -X POST https://api.ksamerchant.geidea.net/pgw/api/v2/direct/pay/token \
-H "accept: application/json" \
-H "authorization: Basic <encoded_auth_header>" \
-H "content-type: application/json" \
-d '{
  "sessionid": "<session_id>",
  "callbackUrl": "https://webhook.site/5dc9b06d-4166-49c2-9db5-81f9734cea46",
  "initiatedBy": "Merchant",
  "agreementId": "<agreement_id>",
  "agreementType": "unscheduled",
  "signature": "<signature>"
}'

🚧

Reminder to use the correct endpoint based on your environment

• KSA Environment: https://api.ksamerchant.geidea.net/
• Egypt Environment: https://api.merchant.geidea.net/
• UAE Environment: https://api.geidea.ae/

By following the steps outlined above, you can successfully tokenize customer cards and initiate MIT transactions using Geidea’s API. Ensure that all sensitive data, such as tokenId and signature are handled securely.