3. Initiate Pay

Once the merchant request has been verified, this API is used to safely handle payment requests by encrypting card data using AES and RSA encryption.

API Endpoints

Direct Pay Production Base URL /InitiatePay

Direct Pay Sandbox Base URL /InitiatePay

Sample Request & Response

The following fields ought to be included in the request body:

 "Initiate pay request{
     "ReferenceId" : "xxxxxxxxx",//The validate request response contained a 15-digit reference ID.
     "MerchantId": xxxxxx, //merchant code
     "ECardData" = "encryptedCard", //card data should be encrypted using
      32BIT AES Encryption 
     "ECardKey" = "encryptedKey", // Encrypt the 32 digit AES key using the RSA public key
     "ACS_CallbackURL"= "call back url for 3DS"+ReferenceId   //optional
     }
     
 };

{
  "authentication": {
    "3ds1": {
      "veResEnrolled": "Y"
    },
    "3ds2": {
      "directoryServerId": "DS12345",
      "methodCompleted": true,
      "methodSupported": "true",
      "protocolVersion": "2.1.0",
      "requestorId": "REQ12345",
      "requestorName": "Merchant",
      "3dsServerTransactionId": "3DSTX12345",
      "acsTransactionId": "ACSTX12345",
      "dsTransactionId": "DSTX12345",
      "transactionStatus": "Success"
    },
    "acceptVersions": "2.1.0",
    "channel": "Browser",
    "purpose": "Authentication",
    "redirect": {
      "customized": {
        "3DS": {
          "methodPostData": "data",
          "methodUrl": "https://acs.bank.com/3ds-method",
          "acsUrl": "https://acs.bank.com/acs-url",
          "cReq": "creq12345",
          "transactionId": "12345"
        }
      },
      "domainName": "https://merchant.com",
      "html": "<html>...3DS Authentication...</html>"
    },
    "redirectHtml": "<html>...3DS Authentication...</html>",
    "version": "2.1.0",
    "3ds": {
      "methodPostData": "data",
      "methodUrl": "https://acs.bank.com/3ds-method",
      "acsUrl": "https://acs.bank.com/acs-url",
      "cReq": "creq12345"
    },
    "method": "Redirect",
    "payerInteraction": "Active"
  },
  "correlationId": "corr-12345",
  "device": {
    "browser": "Chrome",
    "ipAddress": "192.168.1.1"
  },
  "error": null,
  "merchant": "98765",
  "order": {
    "orderId": "ORD12345",
    "amount": "100.00",
    "currency": "USD"
  },
  "response": {
    "status": "Success",
    "message": "Authentication successful"
  },
  "result": "Success",
  "sourceOfFunds": {
    "type": "CreditCard",
    "cardBrand": "Visa"
  },
  "timeOfLastUpdate": "2024-12-26T10:00:00Z",
  "timeOfRecord": "2024-12-26T10:00:00Z",
  "transaction": {
    "transactionId": "TX12345",
    "amount": "100.00",
    "currency": "USD",
    "status": "Completed"
  },
  "version": "1.0"
}

Field Name

Type

Description

ReferenceId

String

15-digit reference id received in the validate requet response

MerchantId

String

Merchant code

ECardData

String

The encrypted card data encrypted using AES encryption with a 32-bit key. Explained below

ECardKey

String

ACS_CallbackURL

String

Explanation of the `ECardData` Encryption Object

The ECardData field in the request is an encrypted representation of the sensitive card details. The following explains the object that is encrypted using AES encryption before being included in the API request:

{
    "CardNumber": "xxxxxxxxxxxxxxxx",//16-digit card number
    "CardName": "John Doe", //Name mentioned on card
    "CardExpiry": "mm/yy", //month/year format
    "CardCVV": "xxx" //3 decimal number
}

Sample code to encrypt ECardData// Some code

 
string aesKeyText = "jcIkNa3ybrNVWxe1GSxycA1ru4GoEETO"; // Generate a 32bit random AES Key
byte[] aesKey = Encoding.UTF8.GetBytes(aesKeyText);
byte[] IV = new byte[16]; // 16-byte IV initialized to zeros

var cardData = new
{
    CardNumber = "XXXXXXXXXXXXXXXXX",
    CardName = "John Doe",
    CardExpiry = "MM/YY",
    CardCVV = "XXX"
};

string serializedCardData = JsonConvert.SerializeObject(cardData);
string encryptedData = EncryptStringToBytes_Aes(serializedCardData, aesKey, IV);



public static string EncryptStringToBytes_Aes(string plainText, byte[] Key, byte[] IV)
{
    
    using (Aes aesAlg = Aes.Create())
    {
        aesAlg.Key = Key;
        aesAlg.IV = IV;
        aesAlg.Mode = CipherMode.CBC;
        aesAlg.Padding = PaddingMode.PKCS7;

        using (var encryptor = aesAlg.CreateEncryptor(aesAlg.Key, aesAlg.IV))
        using (var msEncrypt = new MemoryStream())
        {
            using (var csEncrypt = new CryptoStream(msEncrypt, encryptor, CryptoStreamMode.Write))
            using (var swEncrypt = new StreamWriter(csEncrypt))
            {
                swEncrypt.Write(plainText);
            }
            return Convert.ToBase64String(msEncrypt.ToArray());
        }
    }
}


string aesKeyText = "jcIkNa3ybrNVWxe1GSxycA1ru4GoEETO"; //AES KEY Used to encrypt the card data
string publicKeys = "RSA Public Key"   //Previously generated merchant keys

// Encrypt the AES key using the RSA public key
string encryptedKey = RSA_Encrypt(aesKeyText, publicKeys);

public string RSA_Encrypt(string textToEncrypt, string publicKeyString)
{
    if (string.IsNullOrWhiteSpace(textToEncrypt)) throw new ArgumentNullException(nameof(textToEncrypt));
    if (string.IsNullOrWhiteSpace(publicKeyString)) throw new ArgumentNullException(nameof(publicKeyString));

    var bytesToEncrypt = Encoding.UTF8.GetBytes(textToEncrypt);

    using var rsa = new RSACryptoServiceProvider(2048);
    try
    {
        rsa.FromXmlString(publicKeyString);
        var encryptedData = rsa.Encrypt(bytesToEncrypt, true);
        return Convert.ToBase64String(encryptedData);
    }
    finally
    {
        rsa.PersistKeyInCsp = false;
    }
}

ACS_CallbackURL

The provider will handle the 3D Secure callback if it is empty, and the user will be sent to the callback URL that was supplied in step 1. For more info about redirection refer here.
If provided, the 3D Secure callback will be sent to the merchant's specified URL, and the merchant must call the API at here for further processing.

Previous2. Validate Request Next4. Process Payment

Last updated 2 months ago

"Initiate pay request{ "ReferenceId" : "xxxxxxxxx",//The validate request response contained a 15-digit reference ID. "MerchantId": xxxxxx, //merchant code "ECardData" = "encryptedCard", //card data should be encrypted using 32BIT AES Encryption "ECardKey" = "encryptedKey", // Encrypt the 32 digit AES key using the RSA public key "ACS_CallbackURL"= "call back url for 3DS"+ReferenceId //optional } };

{ "authentication": { "3ds1": { "veResEnrolled": "Y" }, "3ds2": { "directoryServerId": "DS12345", "methodCompleted": true, "methodSupported": "true", "protocolVersion": "2.1.0", "requestorId": "REQ12345", "requestorName": "Merchant", "3dsServerTransactionId": "3DSTX12345", "acsTransactionId": "ACSTX12345", "dsTransactionId": "DSTX12345", "transactionStatus": "Success" }, "acceptVersions": "2.1.0", "channel": "Browser", "purpose": "Authentication", "redirect": { "customized": { "3DS": { "methodPostData": "data", "methodUrl": "https://acs.bank.com/3ds-method", "acsUrl": "https://acs.bank.com/acs-url", "cReq": "creq12345", "transactionId": "12345" } }, "domainName": "https://merchant.com", "html": "<html>...3DS Authentication...</html>" }, "redirectHtml": "<html>...3DS Authentication...</html>", "version": "2.1.0", "3ds": { "methodPostData": "data", "methodUrl": "https://acs.bank.com/3ds-method", "acsUrl": "https://acs.bank.com/acs-url", "cReq": "creq12345" }, "method": "Redirect", "payerInteraction": "Active" }, "correlationId": "corr-12345", "device": { "browser": "Chrome", "ipAddress": "192.168.1.1" }, "error": null, "merchant": "98765", "order": { "orderId": "ORD12345", "amount": "100.00", "currency": "USD" }, "response": { "status": "Success", "message": "Authentication successful" }, "result": "Success", "sourceOfFunds": { "type": "CreditCard", "cardBrand": "Visa" }, "timeOfLastUpdate": "2024-12-26T10:00:00Z", "timeOfRecord": "2024-12-26T10:00:00Z", "transaction": { "transactionId": "TX12345", "amount": "100.00", "currency": "USD", "status": "Completed" }, "version": "1.0" }

{ "CardNumber": "xxxxxxxxxxxxxxxx",//16-digit card number "CardName": "John Doe", //Name mentioned on card "CardExpiry": "mm/yy", //month/year format "CardCVV": "xxx" //3 decimal number }

string aesKeyText = "jcIkNa3ybrNVWxe1GSxycA1ru4GoEETO"; // Generate a 32bit random AES Key byte[] aesKey = Encoding.UTF8.GetBytes(aesKeyText); byte[] IV = new byte[16]; // 16-byte IV initialized to zeros var cardData = new { CardNumber = "XXXXXXXXXXXXXXXXX", CardName = "John Doe", CardExpiry = "MM/YY", CardCVV = "XXX" }; string serializedCardData = JsonConvert.SerializeObject(cardData); string encryptedData = EncryptStringToBytes_Aes(serializedCardData, aesKey, IV); public static string EncryptStringToBytes_Aes(string plainText, byte[] Key, byte[] IV) { using (Aes aesAlg = Aes.Create()) { aesAlg.Key = Key; aesAlg.IV = IV; aesAlg.Mode = CipherMode.CBC; aesAlg.Padding = PaddingMode.PKCS7; using (var encryptor = aesAlg.CreateEncryptor(aesAlg.Key, aesAlg.IV)) using (var msEncrypt = new MemoryStream()) { using (var csEncrypt = new CryptoStream(msEncrypt, encryptor, CryptoStreamMode.Write)) using (var swEncrypt = new StreamWriter(csEncrypt)) { swEncrypt.Write(plainText); } return Convert.ToBase64String(msEncrypt.ToArray()); } } }

string aesKeyText = "jcIkNa3ybrNVWxe1GSxycA1ru4GoEETO"; //AES KEY Used to encrypt the card data string publicKeys = "RSA Public Key" //Previously generated merchant keys // Encrypt the AES key using the RSA public key string encryptedKey = RSA_Encrypt(aesKeyText, publicKeys); public string RSA_Encrypt(string textToEncrypt, string publicKeyString) { if (string.IsNullOrWhiteSpace(textToEncrypt)) throw new ArgumentNullException(nameof(textToEncrypt)); if (string.IsNullOrWhiteSpace(publicKeyString)) throw new ArgumentNullException(nameof(publicKeyString)); var bytesToEncrypt = Encoding.UTF8.GetBytes(textToEncrypt); using var rsa = new RSACryptoServiceProvider(2048); try { rsa.FromXmlString(publicKeyString); var encryptedData = rsa.Encrypt(bytesToEncrypt, true); return Convert.ToBase64String(encryptedData); } finally { rsa.PersistKeyInCsp = false; } }