Introduction

This document helps developers integrate with Payorb – the Payorb payment platform.

Terminology:

1. Payment Platform (PP) – The Payorb Payment system
2. Merchant – Site integrating with Payorb
3. API Key – Also called Secret Key, provided after successful onboarding. Used to generate the secure HMAC hash for API requests.

This integration has two parts:

1. Payorb Pay APIs invoked by Merchant site:
   1. Create Order
   2. Create Payout Order
   3. Verify Order
2. Merchant API implemented per Payorb Pay specification:
   1. Callback

Before development, register with PP, complete onboarding & KYC, and set payout limits. PP will provide a merchant ID and API key. Whitelist your IP for testing.

API calls use standard HTTPS POST (application/json). Provide these redirect URLs:

• → {YOURDOMAIN}/success
• → {YOURDOMAIN}/pending
• → {YOURDOMAIN}/failed

Flow Diagram

Authentication

Every API call requires a HmacSHA256 signature generated with your private key. The server generates its own HMAC and compares it with yours — mismatches are discarded. The signature is sent as an HTTP header named signature.

Example Java implementation:

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;

public class HashGenerator {
    public static String generateHash(String secretKey, String payload) throws Exception {
        Mac shaHMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKeySpec = new SecretKeySpec(
            secretKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
        shaHMAC.init(secretKeySpec);
        byte[] hash = shaHMAC.doFinal(payload.getBytes(StandardCharsets.UTF_8));
        StringBuilder hexString = new StringBuilder();
        for (byte b : hash) {
            String hex = Integer.toHexString(0xff & b);
            if (hex.length() == 1) hexString.append('0');
            hexString.append(hex);
        }
        return hexString.toString();
    }
    public static void main(String[] args) {
        try {
            String secretKey = "your-secret-key";
            String payload = "example-payload-data";
            String hash = generateHash(secretKey, payload);
            System.out.println("Generated Hash: " + hash);
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

POST create-order INR

Creates a payment order in the system and returns a payment URL to redirect the user. After payment completion or cancellation, the user is redirected to your callback URL, from which you can retrieve payment details via the Verify Order API.

payURL: Reach out to PP for the create-order URL

Headers

Body (raw JSON)

{
    "payerInfo": {
        "fname": "testaccount",
        "lname": "testaccount",  // optional
        "address": "Hyderabad",  // optional
        "pin": "500085",  // optional
        "city": "Hyderabad",  // optional
        "mobile": "+91-547-845-4960",  // optional
        "state": "Telangana",  // optional
        "email": "[email protected]"
    },
    "transaction": {
        "amount": 1500.00,
        "merchantId": "1f169e08-53dd-4bbf-a3df-c52583c6d508",
        "orderId": "f7c057f1-81f1-4b58-9ca2-beec4fc35262",
        "paymentMethod": "UPI",
        "currency": "INR"
    },
    "additionalData": {  // optional
        "service": "",  // optional
        "bankType": ""  // optional
    }
}

POST create-payout-order INR

Generates a payout (withdrawal) order on the Payment Platform.

Note: Choose a bank from the Available Banks list. Choose a payment method from the Supported Payment Methods list.

Headers

Body (raw JSON)

{
    "accountNumber": "879645613213456",
    "ifscCode": "SBIN78945612",
    "amount": 1200.00,
    "transactionType": "PAY_OUT",
    "bank": "SBI",
    "bnfNickName": "pay",
    "payeeName": "John Doe",
    "orderId": "6d029a1e-f5be-4be8-95de-c905ad46436a",
    "phoneNumber": "7894561234",
    "pinCode": "500068",
    "emailId": "[email protected]",
    "merchantId": "1f1db3f2-e217-40c6-ac8c-b7f1cc804308",
    "paymentMethod": "NEFT",
    "currency": "INR"
}

POST verify-order

Reconfirms a successfully processed order and obtains further details on the order placed.

Headers

Body (raw JSON)

{
    "merchantId": "1f1db3f2-e217-40c6-ac8c-b7f1cc8043084",
    "merchantOrderId": "ac8cb3f2-ac8c-40c6-e217-b7f1cc8043084",
    "orderId": "e217b3f2-e217-40c6-ac8c-b7f1cc8043084",
    "transactionUserUtr": "112233445566"  // optional
}

GET callbackrequest

Implemented by the Merchant and called by PP to send order status. Upon success, the Merchant must call Verify Order to reconfirm and get full details. Respond with success: true/false per the response below.

Note: Consider the transaction's final status only after verify-order.

Query Parameters

GET balance

Verifies the available merchant balance before initiating a payout.

Headers

Error Codes

Available Banks (INR)

• Canara Bank
• DCB Bank
• Federal Bank
• HDFC Bank
• Punjab National Bank
• Indian Bank
• ICICI Bank
• Syndicate Bank
• Karur Vysya Bank
• Union Bank of India
• Kotak Mahindra Bank
• IDFC First Bank
• Andhra Bank
• Karnataka Bank
• ICICI Corporate Bank
• Axis Bank
• UCO Bank
• South Indian Bank
• Yes Bank
• Standard Chartered Bank
• State Bank of India
• Indian Overseas Bank
• Bandhan Bank
• Central Bank of India
• Bank of Baroda
• UPI

Supported Payment Methods (INR)

• UPI
• NEFT
• IMPS
• BANK

Supported Payment Methods (LKR)

• IPAY

Bank transfers use the IPAY gateway for Sri Lankan Rupee transactions.

Supported Payment Methods (PKR)

• EASYPAISA
• JAZZCASH

Pakistani Rupee transactions use EASYPAISA or JAZZCASH mobile wallets.