Initiate Transaction

The Initiate Transaction process involves securely encrypting and submitting the card details for payment processing.

API flags can be used as follows for different types of transactions:

paymentMethod	apiType	paymentMode	secureCard	skipCVVandOTP	skipCVVOnlyFlag	Remarks
card	hosted	card	TRUE	FALSE	FALSE	Customer will enter card details on merchant and authenticate using CVV and OTP
card	hosted	card	TRUE	TRUE	FALSE	Customer digitalCard will be used and authentication will not happen
card	hosted	card	TRUE	FALSE	TRUE	Customer will enter card details on merchant and authenticate using OTP only
card	hosted	card	TRUE	TRUE	TRUE	Returns an error
card	hosted	token	FALSE	FALSE	FALSE	Customer digitalCard will be used and authentication will happen with CVV and OTP
card	hosted	token	FALSE	TRUE	FALSE	Customer digitalCard will be used and authentication will not happen
card	hosted	token	FALSE	FALSE	TRUE	Customer digitalCard will be used and authentication will happen with OTP only
card	hosted	token	FALSE	TRUE	TRUE	Returns an error

Encrypt Card Data

• Use the card encryption key fetched from the merchant dashboard to encrypt the card details using AES encryption.
• After encrypting the card details, send the encrypted data along with other necessary transaction information in the payload for the transaction initiation API.
• The card data should be formatted as follows:

const crypto = require("crypto");

function encryptData(data, aesKey) {
  const iv = crypto.randomBytes(16).toString("hex");
  const cipher = crypto.createCipheriv("aes-256-cbc", Buffer.from(aesKey, "hex"), Buffer.from(iv, "hex"));
  cipher.setAutoPadding(true);
  const encryptedData = Buffer.concat([
    cipher.update(JSON.stringify(data), "utf8"),
    cipher.final(),
  ]).toString("hex");
  return iv + "." + encryptedData;
}

Using Card Details

// AES key fetched from the merchant dashboard
const aesKey = '<your-card-encryption-key>';
// Card data to be encrypted
const data = {
  "cardNumber": "4111111111111111",
  "cardExpMonth": "02",
  "cardExpYear": "27",
  "cardCVV": "123"
};
const encryptedCardDetails = encryptData(data, aesKey);

Using Tokenized Card

// AES key fetched from the merchant dashboard
const aesKey = '<your-card-encryption-key>';
const data = {
  "cardCVV": "123",
  "digitalCardId": "685b168ebf56f28d31f64428"
};
const encryptedCardDetails = encryptData(data, aesKey);

Request Parameters

Parameter	Mandatory	Description	Type	Example
orderId	Yes	The unique identifier for the order.	String	"wb-158c4274-a7f0-4540-a5c2-44a03b5a0696"
encryptedCardDetails	Yes	The encrypted card details, obtained by encrypting the card data using AES-256-CBC encryption.	String	<encrypted card details>
paymentMethod	Yes	The payment method used for the transaction. For this example, it is card.	String	"card"
cardHolderName	Yes	The name of the cardholder.	String	"test"
redirectionUrl	Yes	The URL to which the user will be redirected after completing the transaction.	String	"https://api.uat.gateway.ompay.com/pg/v1/transactions/test/callback"
paymentMode	Yes	Specifies the method used for processing the payment.	Enum	"card" | "token"
secureCard	No	Indicates whether the card details are tokenized and stored in a secure vault for future use.	Boolean	true
skipCVVandOTP	Yes	Indicates whether the flow proceeds without requiring CVV and OTP.	Boolean	true
skipCVVOnlyFlag	Yes	Indicates whether the flow proceeds with OTP verification only, skipping CVV.	Boolean	true
apiType	Yes	Specifies the type of API being called.	String	hosted

Example Request and Response

Using card details

curl --location --request POST '{{baseUrl}}/transaction/initiate' \
--header 'Authorization: Basic <base64-encoded-clientId:clientSecret>' \
--header 'Content-Type: application/json' \
--header 'X-Signature: <generated_signature>' \
--header 'X-MERCHANT-BROWSER-FINGERPRINT: 8357426ac73fcd60b17355ab7de60421' \
--header 'X-MERCHANT-USER-AGENT: <user-agent>' \
--header 'X-MERCHANT-DOMAIN: https://www.xyz.com' \
--header 'X-MERCHANT-IP: 123.123.123.123' \
--data-raw '{
  "orderId": "wb-158c4274-a7f0-4540-a5c2-44a03b5a0696",
  "encryptedCardDetails": "<encrypted card details>",
  "paymentMethod": "card",
  "cardHolderName": "test",
  "redirectionUrl": "https://api.uat.gateway.ompay.com/pg/v1/transactions/test/callback",
  "paymentMode": "card",
  "secureCard": true,
  "skipCVVOnlyFlag": false,
  "skipCVVandOTP": false,
  "apiType": "hosted"
}'

Success Response without Card Tokenization

{
  "resCode": 200,
  "status": "success",
  "data": {
    "paymentId": "pay798378b8c272451f90cb2b491a86ed17",
    "orderId": "wb-70c20048-9dc8-4fc3-858e-0a3a5c742190",
    "receiptId": "R12345678910",
    "paymentStatus": "pending",
    "amount": 100,
    "currency": "OMR",
    "redirectionData": {
      "method": "POST",
      "formData": "<form action=\"https://certpayments.oabipay.com/trxns/VPAS.htm?actionVPAS=VbvVEReqProcessHTTP&paymentId=202517568254223?PaymentID=pay798378b8c272451f90cb2b491a86ed17\" method=\"POST\" id=\"omannet_re_direct\" name=\"omannet_re_direct\">\n</form>\n<script type=\"text/javascript\">\n document.getElementById('omannet_re_direct').submit();\n</script>"
    }
  }
}

Using tokenized card

curl --location --request POST '{{baseUrl}}/transaction/initiate' \
--header 'Authorization: Basic <base64-encoded-clientId:clientSecret>' \
--header 'Content-Type: application/json' \
--header 'X-Signature: <generated_signature>' \
--header 'X-MERCHANT-BROWSER-FINGERPRINT: 8357426ac73fcd60b17355ab7de60421' \
--header 'X-MERCHANT-USER-AGENT: <user-agent>' \
--header 'X-MERCHANT-DOMAIN: https://www.xyz.com' \
--header 'X-MERCHANT-IP: 123.123.123.123' \
--data-raw '{
  "orderId": "wb-158c4274-a7f0-4540-a5c2-44a03b5a0696",
  "encryptedCardDetails": "<encrypted card details>",
  "paymentMethod": "card",
  "cardHolderName": "test",
  "redirectionUrl": "https://api.uat.gateway.ompay.com/pg/v1/transactions/test/callback",
  "paymentMode": "token",
  "skipCVVandOTP": false,
  "skipCVVOnlyFlag": true,
  "apiType": "hosted"
}'

Success Response with Card Tokenization

{
  "resCode": 200,
  "status": "success",
  "data": {
    "paymentId": "pay798378b8c272451f90cb2b491a86ed17",
    "orderId": "wb-70c20048-9dc8-4fc3-858e-0a3a5c742190",
    "receiptId": "R12345678910",
    "paymentStatus": "pending",
    "amount": 100,
    "currency": "OMR",
    "redirectionData": {
      "formData": "<form action=\"https://certpayments.oabipay.com/trxns/VPAS.htm?actionVPAS=VbvVEReqProcessHTTP&paymentId=202517568254223?PaymentID=pay798378b8c272451f90cb2b491a86ed17\" method=\"POST\" id=\"omannet_re_direct\" name=\"omannet_re_direct\">\n</form>\n<script type=\"text/javascript\">\n document.getElementById('omannet_re_direct').submit();\n</script>"
    },
    "securedCardDetails": {
      "customerId": "4bf4f6a2-ba0a-420f-89a9-e718007ab11a",
      "digitalCardId": "685a421bca91e50caa13300c"
    }
  }
}

Failure Responses

ResCode	Status	Description/Error Message
404	failure	No route found. Please try again with another card.
404	failure	No route found. Please try with an alternative payment method.
404	failure	No route found for this merchant. Please contact support.
409	failure	Sales transactions are not allowed for this merchant. Please contact support.
422	failure	FRM validation failed
409	failure	Transaction is already in progress
401	failure	Missing Authorization header
401	failure	Invalid or inactive client credentials
500	failure	Internal server error