Payment Generation API Documentation

Prerequisites

Ensure you have:

A valid bearer_token from the Machine to Machine Authorization service.
Configured endpoints for receiving callbacks.

API Endpoint

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

This endpoint is used for creating new payment transactions.

Request Headers

Content-Type: application/json
Accept: */*
Authorization: Bearer <bearer_token>

Request Body

Include the following JSON structure in your request with the necessary details:

{
    "amount": "10",
    "currency": "USD",
    "callback": "https://example.com/client_redirect_page",
    "callbackFail": "https://example.com/client_redirect_page_fail",
    "lang": "eng",
    "hookUrl": "https://example.com/callback",
    "cardToken": "dummyCardToken123",
    "orderId": "dummyOrderId456",
    "billing": {
        "firstName": "John",
        "lastName": "Doe",
        "address1": "456 Elm Street",
        "city": "Springfield",
        "state": "IL",
        "country": "US",
        "postalCode": "62704",
        "phone": "1234567890",
        "email": "[email protected]",
        "externalUserId": "userID789"
    },
    "paymentHistory": [
        {
            "paymentId": "PaymentId001",
            "amount": 5,
            "currency": "USD",
            "date": "2024-01-10",
            "status": "success",
            "paymentMethod": "Credit Card"
        },
        {
            "paymentId": "PaymentId002",
            "amount": 7,
            "currency": "USD",
            "date": "2024-01-11",
            "status": "failed",
            "paymentMethod": "Debit Card"
        }
    ]
}

Handling the API Response

Upon successful request, the API will respond with a JSON object containing the payment ID and URLs for redirecting the client.

Example Response

{
    "paymentId": "3295D8EC6FCC49C93",
    "paymentUrl": "https://api.omno.com/transaction/paymentpage/3295D8EC6FCC49C93",
    "paymentUrlIframe": "https://api.omno.com/transaction/paymentpage/iframe/3295D8EC6FCC49C93"
}

Instructions for Merchants

Redirect to Payment URL: Use the paymentUrl from the response to redirect the client to the payment page.
Iframe Integration: Alternatively, you can embed an iframe in your application using the paymentUrlIframe.
Notification Handling: The merchant will receive notifications on the hookUrl provided in the request for every payment status update. Ensure your system is configured to handle these callbacks.

.NET Core Integration Example

Step 1: Create a Console Application

Create a new console application in .NET Core.

Step 2: Add the Required Packages

Ensure that the System.Net.Http package is installed for HTTP operations.

Step 3: Write the Code

Here is a sample code snippet to make the POST request:

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

namespace PaymentApiIntegration
{
    class Program
    {
        static async Task Main(string[] args)
        {
            var client = new HttpClient();
            var bearerToken = "your_bearer_token"; // Replace with your bearer token
            client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", bearerToken);

            var json = @"{
                'amount': '10',
                'currency': 'USD',
                // Add other parameters...
            }";

            var content = new StringContent(json, Encoding.UTF8, "application/json");

            try
            {
                var response = await client.PostAsync("https://api.omno.com/transaction/create", content);
                if (response.IsSuccessStatusCode)
                {
                    var responseContent = await response.Content.ReadAsStringAsync();
                    Console.WriteLine("Response: " + responseContent);
                }
                else
                {
                    Console.WriteLine("Error: " + response.StatusCode);
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine("Exception: " + ex.Message);
            }
        }
    }
}

Replace "your_bearer_token" with the bearer token obtained from the authorization service, fill in the JSON body with the required transaction details.

Step 4: Run Your Application

Execute your application. If everything is set up correctly, your application will make a POST request to the Payment Generation API, and you should receive a response.

Processing the Response

After making the API request, parse the response to obtain the paymentId, paymentUrl, and paymentUrlIframe. Use this information to redirect the client or set up the iframe as per your application flow.

Security and Best Practices

Keep your bearer token and other sensitive information secure.
Implement robust input validation and error handling.
Ensure your callback endpoint for hookUrl is secure and capable of handling notifications.

Next Steps

Explore additional API features to enhance your application's payment-handling capabilities.