Transaction Creation (H2H)

This documentation explains how to create a transaction using the Omno API. The provided curl command sends a POST request to initiate a transaction. After the request, a webhook will be sent to your server containing transaction details. The client should then be redirected to complete the 3DS process.

API Endpoint

POST https://api.omno.com/transaction/h2h/create

Request Headers

Content-Type: application/json
Authorization: Bearer <AUTH_TOKEN>

Request Body

Request Parameters

amount: The transaction amount.
currency: The currency for the transaction.
lang: Language for communication.
hookUrl: URL where the webhook will be sent.
callback: URL to redirect the client after successful payment.
callbackFail: URL to redirect the client after a failed payment.
billing: Billing information.
- firstName: First name of the cardholder.
- lastName: Last name of the cardholder.
- address1: Billing address.
- city: City of billing address.
- state: State of billing address.
- country: Country of billing address.
- postalCode: Postal code of billing address.
- phone: Phone number of the cardholder.
- email: Email address of the cardholder.
orderId: Unique order identifier.
cardToken: Token of the card.
kycVerified: Indicates if KYC is verified. (Optional)
previousPaymentCount: Number of previous payments. (Used for FTD Calculation if external payments count should be considered) (Optional)
cardData: Card information.
- cardNumber: Card number.
- cardHolderName: Name on the card.
- cardExpiryDate: Expiry date of the card (MM).
- cardExpiryDate2: Expiry date of the card (YYYY).
- cardCvv: CVV of the card.
- browser: Browser information.
  - colorDepth: Color depth of the browser.
  - userAgent: User agent string of the browser.
  - language: Browser language.
  - timeZone: Time zone of the browser.
  - screenWidth: Screen width of the browser.
  - javaEnabled: Indicates if Java is enabled in the browser.
  - customerIp: Customer IP address.
  - screenHeight: Screen height of the browser.
  - windowHeight: Window height of the browser.
  - timeZoneOffset: Time zone offset of the browser.
  - windowWidth: Window width of the browser.
saveCard: Indicates if the card should be saved.
payment3dsType: (Optional) Type of 3DS process. Default is "Redirection".

The request body should be a JSON object with the following structure:

{
  "amount": 0,
  "currency": "",
  "lang": "",
  "hookUrl": "",
  "callback": "",
  "callbackFail": "",
  "billing": {
    "firstName": "",
    "lastName": "",
    "address1": "",
    "city": "",
    "state": "",
    "country": "",
    "postalCode": "",
    "phone": "",
    "email": "",
    "externalUserId": "",
    "dateOfBirth": ""
  },
  "orderId": "",
  "cardToken": "",
  "payment3dsType": "Redirection",
  "kycVerified": false,
  "previousPaymentCount": 0,
  "cardData": {
    "cardNumber": "",
    "cardHolderName": "",
    "cardExpiryDate": "",
    "cardExpiryDate2": "",
    "cardCvv": "",
    "browser": {
      "colorDepth": 0,
      "userAgent": "",
      "language": "",
      "timeZone": "",
      "screenWidth": 0,
      "javaEnabled": false,
      "customerIp": "",
      "screenHeight": 0,
      "windowHeight": 0,
      "timeZoneOffset": 0,
      "windowWidth": 0
    }
  },
  "saveCard": false
}

Example Request

curl -X POST --location "<https://api.omno.com/transaction/h2h/create>" \\
    -H "Content-Type: application/json" \\
    -H "Authorization: Bearer <AUTH_TOKEN>" \\
    -d '{
          "amount": 1000,
          "currency": "USD",
          "lang": "en",
          "hookUrl": "<https://yourserver.com/hook>",
          "callback": "<https://yourserver.com/callback>",
          "callbackFail": "<https://yourserver.com/callbackFail>",
          "billing": {
            "firstName": "John",
            "lastName": "Doe",
            "address1": "123 Street",
            "city": "Cityville",
            "state": "State",
            "country": "US",
            "postalCode": "12345",
            "phone": "1234567890",
            "email": "[email protected]",
            "externalUserId": "user123",
            "dateOfBirth": "1980-01-01"
          },
          "orderId": "order123",
          "cardToken": "token123",
          "payment3dsType": "Redirection",
          "kycVerified": true,
          "previousPaymentCount": 5,
          "cardData": {
            "cardNumber": "4111111111111111",
            "cardHolderName": "John Doe",
            "cardExpiryDate": "12",
            "cardExpiryDate2": "2024",
            "cardCvv": "123",
            "browser": {
              "colorDepth": 24,
              "userAgent": "Mozilla/5.0",
              "language": "en-US",
              "timeZone": "-300",
              "screenWidth": 1920,
              "javaEnabled": true,
              "customerIp": "192.168.1.1",
              "screenHeight": 1080,
              "windowHeight": 800,
              "timeZoneOffset": -300,
              "windowWidth": 1200
            }
          },
          "saveCard": true
        }'

Webhook Response

After the request is processed, a webhook will be sent to the specified hookUrl with the transaction details. The JSON structure of the webhook response is as follows:

{
  "id": "BBFD4C1A48CC4CA6BA13D80AF933612B",
  "status": "Pending3DS",
  "amount": 10.0,
  "currency": "EUR",
  "createdAt": "2024-05-21 07:39:05",
  "psp": "CyberSource (Visa/MC)",
  "cardMask": "553979********7812",
  "cardholder": "cardholder",
  "expirationDate": "09/2024",
  "country": "France",
  "cardBrand": "MC",
  "customerId": "9bd1d9aa-18d5-46a0-970a-9484defb51d4",
  "paymentResult": "",
  "initialAmount": 10.0,
  "initialCurrency": "EUR",
  "isApm": false,
  "paymentLog": [
    {
      "amount": 10.0,
      "merchantId": "de80d8d6-5b80-42f6-8883-5cd064b7ded9",
      "customerId": "9bd1d9aa-18d5-46a0-970a-9484defb51d4",
      "currency": "EUR",
      "paymentTransactionStatus": "Created",
      "transactionRequestType": "JustPay",
      "paymentId": "BBFD4C1A48CC4CA6BA13D80AF933612B",
      "country": "France",
      "hookUrl": "<https://demo.hook.online/api/omno/hook>",
      "callback": "<https://demo.hook.online/api/omno/callback>",
      "lang": "en",
      "initialTransaction": false,
      "createdAt": "2024-05-21 07:39:12",
      "orderId": "a9528558-ecfe-4edd-b9d8-fe42648599e1",
      "initialAmount": 10.0,
      "initialCurrency": "EUR"
    }
  ],
  "billingData": {
    "firstName": "Name",
    "lastName": "Lastname",
    "address1": "Address",
    "city": "PARIS",
    "state": "PARIS",
    "country": "FR",
    "postalCode": "75012",
    "phone": "33 07657812312",
    "email": "[email protected]"
  },
  "paymentTransactionRequests": [],
  "paymentSystemLog": [
    {
      "paymentId": "BBFD4C1A48CC4CA6BA13D80AF933612B",
      "type": "TransactionCountForMerchantSuitability",
      "logData": {
        "result": true,
        "pspMaxTransactionCountPerDay": 999999999,
        "merchantId": "de80d8d6-5b80-42f6-8883-5cd064b7ded9",
        "pspMaxTransactionCountPerMonth": 999999999,
        "transactionCountPerDay": 0,
        "transactionCountPerMonth": 55427,
        "pspName": "Wipay EUR MC Trusted"
      }
    }
  ],
  "orderId": "a9528558-ecfe-4edd-b9d8-fe42648599e1",
  "3dsRedirectUrl": ""
}

Completing the Payment

After receiving the webhook, you need to redirect the client to the 3dsRedirectUrl to complete the payment. Once the 3DS process is finished, the client will be redirected to the callback URL if successful, or to the callbackFail URL if the payment fails.

Required Fields

Billing Information: billing object
Card Data: cardData object
Browser Data: browser object within cardData

Ensure that all required fields are filled correctly to avoid transaction issues.

This documentation provides an overview of creating a transaction using the Omno API, handling webhooks, and redirecting the client for 3DS authentication.