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",
  "callbackUrl": "https://webhook.site/5dc9b06d-4166-49c2-9db5-81f9734cea46",
  "initiatedBy": "Internet",
  "cardOnFile": true,
  "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",
  "cardOnFile": true,
  "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.

Pseudocode for Signature Generation:

FUNCTION generate_MIT_signature(merchant_public_key, sessionid, api_password)

  // Step 1: Concatenate merchant_public_key and sessionid to create the data string
  SET data_string = CONCAT(merchant_public_key, sessionid)

  // Step 2: Encode api_password and data_string as bytes for HMAC generation
  ENCODE api_password as bytes
  ENCODE data_string as bytes

  // Step 3: Generate HMAC hash using SHA-256 algorithm with api_password as the key
  COMPUTE hash_bytes = HMAC-SHA256(api_password, data_string)

  // Step 4: Base64-encode the resulting hash
  ENCODE hash_bytes using Base64 to generate the signature

  // Step 5: Return the generated signature
  RETURN signature

END FUNCTION

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.