Skip to main content

Payment Request

Send your customer to the Omniware hosted payment page. After completion, Omniware redirects them back to your return_url with the result.

Endpoint​

POST https://pgbiz.omniware.in/v2/paymentrequest
Content-Type: application/x-www-form-urlencoded

In production you usually render an HTML form with these fields as hidden inputs and auto-submit from the browser, so the customer lands directly on the payment page.

Request parameters​

Identity & order​

api_keystring (36)required

Your merchant key.

order_idstring (30)required

Your reference number for this transaction. Must be unique per merchant. Omniware rejects duplicate order_ids.

modestring (4)

LIVE or TEST. Optional — defaults to whatever your account is configured for.

amountdecimal(12,2)required

Payment amount.

currencystring (3)required

ISO 4217 code — typically INR.

descriptionstring (255)required

Short description of the product/service. Visible to the customer.

Customer details​

namestring (255)required
emailstring (255)required
phonestring (30)required
address_line_1string (255)
address_line_2string (255)
citystring (255)required
statestring (255)
countrystring (100)required
zip_codestring (20)required

URLs​

return_urlstring (255)required

Omniware POSTs here after a successful transaction.

return_url_failurestring (255)

Optional separate URL for failed transactions.

return_url_cancelstring (255)

Optional separate URL for transactions the customer cancels.

User-defined fields​

udf1string (255)
udf2string (255)
udf3string (255)
udf4string (255)
udf5string (255)

Behaviour controls​

timeout_durationstring (10)

Page timeout in seconds.

payment_optionsstring (50)

Comma-separated list of methods to show: cc, nb, w, atm, upi, dp. Order also controls the tab order on the page.

payment_page_display_textstring (100)

Text shown under the logo on the payment page.

allowed_bank_codesstring (250)

Comma-separated bank codes to restrict the available banks. See Bank codes.

allowed_emi_tenurestring (50)

Comma-separated EMI tenures in months, e.g. 3,6,9.

allowed_binsstring (250)

Comma-separated 6-digit card BINs to allow. Cards not in the list are blocked.

percent_tdr_by_userdecimal(5,2)

Percentage of TDR paid by the customer (surcharge model). Max 100.

flatfee_tdr_by_userdecimal(10,2)

Flat fee paid by the customer (surcharge model).

show_convenience_feestring (1)

y/n — whether to show the surcharge separately to the customer.

enable_auto_refundstring (1)

y/n — auto-refund on delayed-success transactions.

Splits & products​

split_enforce_strictstring (1)

y/n. If y, settlement is held until Split Settlement is called.

split_infostring (500)

JSON describing how to split this payment between vendors:

{"vendors":[
  {"vendor_code":"2VEN449","split_amount_fixed":"20"},
  {"vendor_code":"2VEN450","split_amount_fixed":"20"}
]}
product_detailsstring (2048)

JSON describing the goods being paid for. Used for EMI subvention and reporting:

{
  "manufacturer": "Samsung",
  "category": "Phone",
  "sub_category_1": "Smart Phone",
  "sub_category_2": "Highend",
  "model_name": "Samsung Galaxy S10 Pro"
}
emi_infostring (100)

JSON with subvention metadata if EMI details need to be forwarded to the issuer:

{
  "subvention": "0.0",
  "aggregator_name": "BENOW",
  "bank_merchant_id": null,
  "bank_term_id": null,
  "bank_sku_code": null
}
offer_codestring (100)

Predefined offer code if a discount applies to this EMI.

Signature​

hashstring (255)required

SHA-512 hash of the request. See Hash calculation.

Request example​

curl -X POST https://pgbiz.omniware.in/v2/paymentrequest \
  -d "api_key=YOUR_API_KEY" \
  -d "order_id=ORD-1001" \
  -d "amount=149.00" \
  -d "currency=INR" \
  -d "description=Order 1001" \
  -d "name=Amit Kumar" \
  -d "email=amit@example.com" \
  -d "phone=9900990099" \
  -d "city=Bangalore" \
  -d "country=IND" \
  -d "zip_code=560001" \
  -d "return_url=https://yoursite.com/payment/return" \
  -d "hash=$HASH"

Response​

After the customer completes (or fails / cancels) the payment, Omniware POSTs the result back to the matching return_url.

{
  "transaction_id": "HDVISC1299876438",
  "payment_mode": "Credit Card",
  "payment_channel": "Visa",
  "payment_datetime": "13-06-2018 16:45:39",
  "response_code": 0,
  "response_message": "SUCCESS",
  "error_desc": null,
  "order_id": "ORD-1001",
  "amount": "149.00",
  "currency": "INR",
  "description": "Order 1001",
  "name": "Amit Kumar",
  "email": "amit@example.com",
  "phone": "9900990099",
  "address_line_1": "Address Line 1",
  "address_line_2": "Address Line 2",
  "city": "Bangalore",
  "state": "Karnataka",
  "country": "IND",
  "zip_code": "560001",
  "udf1": null, "udf2": null, "udf3": null, "udf4": null, "udf5": null,
  "tdr_amount": "1.93",
  "tax_on_tdr_amount": "0.35",
  "amount_orig": "149.00",
  "cardmasked": "437748******0069",
  "emi_tenure": 6,
  "emi_rate_of_interest": "13.99",
  "hash": "..."
}

Response field reference​

FieldDescription
transaction_idOmniware's unique alphanumeric transaction ID. The 3rd–6th characters are the bank code.
payment_modeHigh-level mode — Credit Card, Debit Card, Netbanking, Wallet, UPI, etc.
payment_channelSpecific channel — Visa, HDFC Bank, Paytm, etc.
payment_datetimeDD-MM-YYYY HH:MM:SS.
response_code0 for success; non-zero values map to error codes.
response_messageHuman-readable status.
error_descDetailed bank-side error message, if any. null on success.
order_idEcho of your reference.
amountSame as request. In the surcharge model, this is what the customer paid.
currency, descriptionEchoes.
name … zip_codeAll customer fields you posted on the request, echoed back verbatim.
udf1–udf5Echoes.
tdr_amountTDR charged on this transaction. Returned only if your account is configured to surface it.
tax_on_tdr_amountGST on the TDR. Returned with tdr_amount.
amount_origOriginal requested amount (different from amount only in customer-surcharge mode).
cardmaskedMasked PAN, e.g. 437748******0069. Returned only if your account is enabled for it.
emi_tenureEMI tenure in months. Returned when send_emi_details is enabled on your account, or when emi_info was passed on the request.
emi_rate_of_interestEMI interest rate. Same conditions as emi_tenure.
hashOmniware's hash over the rest of the response — always recompute and compare.

The tdr_amount, tax_on_tdr_amount, amount_orig, cardmasked, emi_tenure, and emi_rate_of_interest fields are returned only if your merchant account is explicitly enabled to receive them. Otherwise they are absent (or null). Speak to your relationship manager if you need any of them surfaced.

warning

Always verify the response hash. A failed redirect can be tampered with by the user before it reaches your server. The numeric response_code is authoritative — 0 is success, anything else is failure. See Error codes.

Transaction ID format​

HDVISC1299876438 — the 3rd to 6th characters (VISC) are the bank code, which maps to the payment mode and channel. See Bank codes for the full table.

Next​