1Pay

API REFERENCE

Introduction

1Pay payment API is a software-to-software interface, not a user interface. With APIs, applications talk to each other without any user knowledge or intervention.

1Pay provides a simple http interface listing information of interest to perform transaction. This interface can be accessed on port 80/443. 1Pay payment gateway links merchants/sellers website to process online payments. Like most gateways, 1Pay Payment Gateway handles all major net banking, credit, debit and cash cards.

To initiate a transaction, the merchant generates a POST REQUEST (which is a particular mode of interaction on internet). The request must include mandatory and optional parameters. The mandatory fields include hash (checksum), transaction id (order reference number generated at merchant’s end), amount, email, phone number and other merchant specific data.

When the POST request reaches 1Pay PG the, customer would be re-directed to payment gateway’s payment page. Customer now selects the particular payment option on payment gateway’s page (Credit Card/Debit Card/Net Banking etc) and clicks on ‘Pay Now’. Now, payment gateway re-directs the customer to the chosen bank. The customer goes through the necessary authorization/authentication process at bank’s login page, and the bank gives the success/failure response back to payment gateway.

When the transaction POST request hits the payment gateway server, Payment gateway marks the transaction status on the basis of response received from Bank. Payment gateway provides the final transaction response to the merchant through a POST RESPONSE. In the POST RESPONSE sent by gateway, merchant would receive the status of the transaction. Merchant needs to call the verify transaction API after receiving the response from payment. This is done to strictly avoid any tampering attempt by the user.

Abstract Architecture

URL

For 16bit API key use below posting URL:-

1.TestURL:: https://hdfcprodsigning.in/onepayVAS/payprocessor

2.Live URL:: https://pay.1paypg.in/onepayVAS/payprocessor

For 32bit API key use below posting URL:-

3.Test:: https://hdfcprodsigning.in/onepayVAS/payprocessorV2

4.Live :: https://pay.1paypg.in/onepayVAS/payprocessorV2

Process Flow

This section briefly details the overall transaction flow -

  • User logs-in at the Merchant website for Online payment
  • User then decides to pay; clicks on ‘Checkout’ option provided at the merchant page
  • Merchant website generates a unique reference number; along with other mandatory parameters and then converts it in to Json String.
  • After generating the json object merchant encrypts the data using AES-256 algorithm. 1Pay provides a unique key for the data encryption. After encrypting the data merchant establish a connection with the 1Pay Payment Gateway Interface over a secured https channel.
  • At the 1Pay Payment Gateway; User is displayed various ‘payment options’ that he can use, for e.g. Net Banking.
  • User chooses the payment option at 1Pay Payment Gateway and is taken to the page of that specific bank. User then enters the relevant authentication details [i.e. User ID/ Card Number/ Password etc.] at the bank’s authentication page.
  • User’s account is debited, and the User is then directed back to the designated Return URL [RU] at Merchant website. 1Pay encrypts the data (using the same key) before sending it to the merchant’s page.
  • After getting the response from 1Pay, merchant needs to decrypt the data. Merchant can use this response to update its system and display to the User that the payment process was successful.
  • 1Pay also generates a unique Transaction ID against each transaction that is received – this could be displayed to the User; and used for any queries relating to the transaction.

Payment/Authorization

PostURL : https://hdfcprodsigning.in/onepayVAS/payprocessor

20 Parameters for auth request

Payment /Auth Request

merchantIdMandatory

ANAlphanumeric

Unique merchant id provided by 1Pay

Min Length: 5Max Length: 16

Sample value M00012

apiKeyMandatory

ANAlphanumeric

A unique key provided by 1Pay

Min Length: 8Max Length: 32

Sample value jpuT0821

txnIdMandatory

ANAlphanumeric

A unique tracking id created by the merchant for each transaction

Min Length: 1Max Length: 32

Sample value 77983779999

AmountMandatory

Decimal (fixed 2 decimal points)

Amount of the transaction

Min Length: 1 (excluding decimal)Max Length: 8 (excluding decimal)

Sample value 100.00

dateTimeMandatory

Date Time (yyyy-MM-dd HH:mm:ss)Datetime

Date time of the originator

Min Length: 19Max Length: 19

Sample value 2018-08-01 13:20:33

custMobileMandatory

NNumeric

Mobile number of the customer

Min Length: 10Max Length: 10

Sample value 9876588877

custMailMandatory

ANAlphanumeric

Email id of the customer

Min Length: 8Max Length: 50

Sample value abc@abc.com

channelIdMandatory

NNumeric

Channels like Internet,IVR,etc

Min Length: 1Max Length: 1

Sample value 0 (For Internet)

txnTypeMandatory

AAlphabets

DIRECT: Capture Payment details on Aggregator’s page REDIRECT: Get Payment Details in Request from Merchant and redirect to Bank Page directly

Min Length: 6Max Length: 8

Sample value DIRECT/REDIRECT

returnURLMandatory

AN(Special Characters Allowed are /?&=_:. )Alphanumeric

A Unique URL provided by merchant to post the response

Min Length: 10Max Length: 200

Sample value http://payone.tech/abc/

productIdMandatory

AN (Special Characters allowed are Tilde(~) and Pipe(|))Alphanumeric

IF Merchant wants Multipart Settlement for single Txn then he needs to pass different Product Ids along with the Amount ELSE value is ‘DEFAULT’.

Min Length:Max Length: Undefined

Sample value IF isMultiSettlement= 0 :- DEFAULT(Case-Sensitive) IF isMultiSettlement= 1 :- Product1~100|Product2~200|..|ProductN~AmountN Note :Sum of Amounts in Product Id field must be equal to Transaction Amount.

isMultiSettlementMandatory

NNumeric

IF Merchant wants Settlement of single Txn in Multiple Accounts(Registered with 1pay) then he needs to pass value of this field as ‘1’(True)ELSE ‘0’(False).

Min Length: 1Max Length: 1

Sample value 0(False)/1(True)

udf1Mandatory

ANAlphanumeric

Default value is “NA”. The user (merchant) defines these fields. The field data is passed along with a transaction request. These fields are for merchant to pass additional transaction related information like customer email id, contact number, Address etc..

Min Length: 2Max Length: 45

Sample value NA

udf2Mandatory

ANAlphanumeric

Default value is “NA”. The user (merchant) defines these fields. The field data is passed along with a transaction request. These fields are for merchant to pass additional transaction related information like customer email id, contact number.

Min Length: 2Max Length: 45

Sample value NA

udf3Mandatory

AN(Space allowed in Card Name Field)Alphanumeric

Default value is “NA”. The user (merchant) defines these fields. The field data is passed along with a transaction request. These fields are for merchant to pass additional transaction related information like customer email id, contact number.

Min Length: 2Max Length: 45

Sample value NA

udf4Mandatory

ANAlphanumeric

Default value is “NA”. The user (merchant) defines these fields. The field data is passed along with a transaction request. These fields are for merchant to pass additional transaction related information like customer email id, contact number.

Min Length: 2Max Length: 250

Sample value NA

udf5Mandatory

ANAlphanumeric

Default value is “NA”. The user (merchant) defines these fields. The field data is passed along with a transaction request. These fields are for merchant to pass additional transaction related information like customer email id, contact number.

Min Length: 2Max Length: 45

Sample value NA

instrumentIdMandatory

AAlphabets

Payment Mode of the Transaction

Min Length: 2Max Length: 12

Sample value For txnType DIRECT :-NA For txnType REDIRECT :-NB/CC/DC/UPI

cardDetailsMandatory

AN(Space allowed in Card Name Field)Alphanumeric

Default ‘NA’

Min Length: 2Max Length: 65

Sample value For txnType ‘DIRECT’ the default value -NA For txnType ‘REDIRECT’ – For CC/DC: "CARDNAME|CARDNO|CVV|EXPIRY|SAVECARDFLAG" For NB: Bank specific code provided by 1Pay For UPI: NA

cardTypeMandatory

AAlphabets

Type of Card used for Transaction

Min Length: 2Max Length: 20

Sample value For txnType DIRECT :-NA For txnType REDIRECT & instrumentId CC/DC :- Visa/Mastercard/Rupay etc For txnType REDIRECT & instrumentId NB :-NA For txnType REDIRECT & instrumentId UPI :-NA


The generated JSON data needs to be encrypted in AES-256 using a secret key provided by 1pay. After encryption the data will be posted on 1pay server over web browser.

merchantIdMandatory

ANAlphanumeric

A Unique merchant Id provided by 1Pay

Min Length: 5Max Length: 16

Sample value

reqDataMandatory

ANAlphanumeric

Encrypted request parameters

Min Length:Max Length: -

Sample value KfpBKDDON6YiH4d5pfXZq6NVVvurTmiI/+jXy3Z s3atWH7XwXQGtBodk09+WWsjILjvWWRqA/SFj32 coE6e+6WzlXmrD7eBrRKxVGNl4Ye1AgsXrRruA3 uQEX/tWMNdFmIiNMCskyCP6KF/F4sUG3frbjhld VJmsj8E/1A1X60/F91L6khBOCdN4fzAJP6zYxws 2Zg5qXJATGI51LuaIGJBp4HLEj5G0oXq/JUvHmB 3Y1MACTlIbVn46RmiW8wHbkHeopIOVGZpJSkwBo tE1d0FxGYyxsGXEP4TAAKnJ/+ykg4dbngoy9LV/ QeBU9SPJSluFwg1F2X+5JNKkUwnE1YAvx5Fi+HgQ=

Request parameters need to be converted into json format as sample given below –

{ "dateTime":"2018-08-23 19:07:02","amount":"1.00", "isMultiSettlement":"0", "custMobile":"9876543210", "apiKey":"jpuT6032", "p roductId":"DEFAULT", "instrumentId":"NA", "cardType":"NA", "txnType":"DIRECT", "udf3":"NA", "udf1":"N A", "udf2":"NA", "merchantId":"M0002", "custMail":"test@test.com", "returnURL":"http:\/\/https://hdfcpr odsigning.in\/onepayVAS\/merchantResponse.jsp","channelId":"0","txnId":"230820181535031422094"," udf4": "NA","udf5":"NA","cardDetails":"NA" }

Payment /Auth Response

respDataAES-256 bit Encrypted Response

Sample Value of respData

7BTY6h+xdqHM4dxiV6kDpjGVGHQynhQetNQ/oH0XVnnu5Ln5Tj80z+37YMgVuefMom4PCn5yfp+pffgoB6 uIIrqwcYa8OPp4fntT3y18uDPyjYCRSBQRQhUhbUj+jETewhcH33ZB4cKRcfFIv2yMnuCD+ZX1NICKq+iA0s9T au0PvM9Eh6Vdie4Le2qE+yeygw9tbbP48GcQL78pE8FM3z3JLAX3uWJBnthpkv2P/AUr4qWOhZmouSnVPE XRFZd5VZho91SUUzUrai0czkuytHFadZgrmqEXKSdtSyOLGLq8uyzZloeGezQK1Vqu5YLz7yvoJ2ZMfKnLWQP OJatAUCnN5g/BRyWrGpQ9fMCJKR2bpFXH9myMLZqI/G2v42NXs3it0hXRF+uTat2Ai2edGD+O9VJgLm2I5Q SQyNCaoN8L4jM1Rh+OfLU35NT8hvf3Up9zqX3lXhjU2XUFfp6+NHz08/224Ka9EXXfKOFNvqyKHGvLmPokd 6wSfhdprPyutD7TCkIDUdXKG84CiPEidiAF4QRFEuDahYAUK2xV1D2f7Bo4NRztBQymqNzCmBQTDMrHnpg haJc6SA6PVoAenns9oiDpb5o3ElNSfCwNLRCn0vzQsv4odeWyS0XwirM0

After receiving the encrypted response user needs to decrypt the data using the key shared by 1pay.

Json Data after decryption of the encrypted response -

{ "txn_id":"230820181535031422094", "payment_mode":"CC", "resp_date_time":"2018-08-19:07:24", "resp_message":"SUCCESS", "bank_ref_id":"823510001250", "cust_email_id":"test@test.com", "merchant_id":"M0002", "txn_amount":"1.00", "txn_date_time":"2018-08-23 19:07:02.0", "pg_ref_id":"100182351907085854", "trans_status":"Ok", "cust_mobile_no":"9876543210", "resp_code":"00000" }

Parameter details

merchant_idMandatory

ANAlphanumeric

Merchant Id Provided by 1Pay

Min Length: 5Max Length: 16

Sample value M00012

txn_idMandatory

ANAlphanumeric

Merchant’s unique TxnReference Number received in Request

Min Length: 1Max Length: 32

Sample value 2018080112045

pg_ref_idMandatory

ANAlphanumeric

1Pay Unique Transaction Reference Number generated against Merchant’s Txn Id

Min Length: 19Max Length: 19

Sample value 100182141927437447

txn_date_timeMandatory

Date TimeDatetime

TxnDate and Time received in Request

Min Length: 19Max Length: 19

Sample value yyyy-MM-dd HH:mm:ss (2018-08-01 12:10:35)

trans_statusMandatory

AAlphabets

Transaction Status

Min Length: 1Max Length: 2

Sample value F(Fail)/To(Time Out)/Ok(Success)

txn_amountMandatory

NNumeric

Transaction Amount received in Request

Min Length: 2Max Length: 6

Sample value 100.00

resp_codeMandatory

ANAlphanumeric

1pay Response Code

Min Length: 5Max Length: 5

Sample value 00000

resp_messageMandatory

ANAlphanumeric

1pay Response Message based on the Response received from Service Provider/Bank

Min Length: 10Max Length: 200

Sample value Transaction Successful/No Error etc.

bank_ref_idMandatory

ANAlphanumeric

Transaction Reference Number received from Service Provider/Bank

Min Length: UndefinedMax Length: Undefined

Sample value BNK2018121

resp_date_timeMandatory

Date TimeDatetime

Date and Time when 1Pay sent the Response to Merchant

Min Length: 19Max Length: 19

Sample value Date and Time when 1Pay sent the Response to Merchant

cust_email_idMandatory

ANAlphanumeric

Email id of the customer received in Request

Min Length: 8Max Length: 50

Sample value abc@abc.com

cust_mobile_noMandatory

NNumeric

Mobile Number of the customer received in Request

Min Length: 10Max Length: 10

Sample value 9876588877

payment_modeMandatory

AAlphabets

Payment Mode of the Transaction

Min Length: 2Max Length: 2

Sample value NB/CC/DC/UPI

Transaction Status Query

Post(Server to Server Call)URL : https://hdfcprodsigning.in/onepayVAS/getTxnDetails

Request Parameters

merchantIdMandatory

ANAlphanumeric

Unique merchant id provided by 1Pay

Min Length: 5Max Length: 16

Sample value M00012

txnIdMandatory

ANAlphanumeric

Merchant’s Unique Transaction Reference Number

Min Length: 1Max Length: 32

Sample value 77983779999



Plain Request

https://hdfcprodsigning.in/onepayVAS/getTxnDetails?merchantId =M00012&txnId=77983779999

Response Parameters

merchant_idMandatory

ANAlphanumeric

Merchant Id Provided by 1Pay

Min Length: 5Max Length: 16

Sample value M00012

txn_idMandatory

ANAlphanumeric

Merchant’s unique TxnReference Number received in Request

Min Length: 1Max Length: 32

Sample value 2018080112045

pg_ref_idMandatory

ANAlphanumeric

1Pay Unique Transaction Reference Number generated against Merchant’s Txn Id

Min Length: 19Max Length: 19

Sample value 2018111102102222

txn_date_timeMandatory

Date TimeDatetime

Transaction Date Time

Min Length: 19Max Length: 19

Sample value YYYY-MM-dd HH:mm:ss(2018-08-01 12:10:35)

trans_statusMandatory

AAlphabets

Transaction Status

Min Length: 1Max Length: 2

Sample value F(Fail)/To(Time Out)/Ok(Success)

txn_amountMandatory

NNumeric

Transaction amount

Min Length: 2Max Length: 6

Sample value 100.00

resp_codeMandatory

ANAlphanumeric

1pay Response Code

Min Length: 5Max Length: 5

Sample value 00000

resp_messageMandatory

ANAlphanumeric

1pay Response Message based on the Response received from Service Provider/Bank

Min Length: 10Max Length: 200

Sample value Transaction Successful/No Error etc.

bank_ref_idMandatory

ANAlphanumeric

Transaction Reference Number received from Service Provider/Bank

Min Length: UndefinedMax Length: Undefined

Sample value BNK2018121

Sample Response

{ "txn_id":"030820181533284534340", "payment_mode":"CC", "resp_date_time":"2018-08-03 13:58:41", "resp_code":"E0013", "resp_message":"This transaction has been declined. Kindly contact credit card issuer bank.", "bank_ref_id":"NA", "cust_email_id":"test@test.com", "merchant_id":"M0002", "txn_amount":"1.00", "txn_date_time":"2018-08-03 13:52:14", "pg_ref_id":"100182141927437447", "trans_status":"F", "cust_mobile_no":"9876543210" }

Note: For timeout transactions, if transaction status query is done after 20 minutes, transaction status response will not be fetched. In this case, you have to consider this transaction as Failed. This is to say that when you get "trans_status":"NA" & "resp_code":"NA" in dual verification response please consider these transactions as failed transactions.

Refund API

RefundRequest API

Post(Server to Server Call)URL : https://hdfcprodsigning.in/onepayVAS/refundRequest

Request Parameters

merchantIdMandatory

ANAlphanumeric

Unique merchant id provided by 1Pay

Min Length: 5Max Length: 16

Sample value M00012

txnIdMandatory

ANAlphanumeric

Merchant’s Unique Transaction Reference Number

Min Length: 1Max Length: 32

Sample value 77983779999

refundRequestIdMandatory

ANAlphanumeric

Unique number generated by merchant.

Min Length: 18Max Length: 18

Sample value 2018111102102222

refundAmountMandatory

NNumeric

Amount to be refunded

Min Length: 2Max Length: 6

Sample value 100.00

addedByMandatory

Min Length: Max Length:

Sample value Merchant

Request parameters need to be converted into json format as sample given below –

Refund request -

{ "merchantId":"M0000379", "encData":"sYlncQEgK8fdc413X1jnYeENejq78WVbzHRH5Cca2EAK5I2Pul/+TcNz2OsvyHSqqJCE6CZjRbJlI3FcQnupiI0Q+k9NwOnmzxK32kYUcYbHB43uPF0rmwyeoM738g9h5QYtZf7f6BGQexVMLsxNtQ==" } encData= { "txnId":"09139236000000200021616", "refundAmount":"1.00", "refundRequestId":" test_010101", "addedBy":"merchant" }

Response Parameters

merchant_idMandatory

ANAlphanumeric

Merchant Id Provided by 1Pay

Min Length: 5Max Length: 16

Sample value M00012

txn_idMandatory

ANAlphanumeric

Merchant’s unique Txn Reference Number received in Request

Min Length: 1Max Length: 32

Sample value 2018080112045

refundRequestIdMandatory

ANAlphanumeric

Unique number generated by merchant.

Min Length: 18Max Length: 18

Sample value 2018111102102222

refund_amountMandatory

NNumeric

Refund Amount received in Request

Min Length: 2Max Length: 6

Sample value 100.00

txn_amountMandatory

NNumeric

Transaction amount

Min Length: 2Max Length: 6

Sample value 100.00

refund_type_statusMandatory

AAlphabets

Partial Refund or Full Refund

Min Length: 2Max Length: 3

Sample value PR/FR

resp_codeMandatory

ANAlphanumeric

1pay Response Code

Min Length: 5Max Length: 5

Sample value RF000

resp_messageMandatory

ANAlphanumeric

Refund Response Message

Min Length: 10Max Length: 200

Sample value Refund Request Raised Successfully.

rrnMandatory

ANAlphanumeric

Refund Reference Number

Min Length: UndefinedMax Length: Undefined

Sample value BNK2018121

pg_ref_idMandatory

ANAlphanumeric

1Pay Unique Transaction Reference Number generated against Merchant’s Txn Id

Min Length: 19Max Length: 19

Sample value 100182141927437447

addedByMandatory

Min Length: Max Length:

Sample value Merchant

Sample Response

Below is the response code and response message for the same.

RF000 Refund Request Raised Successfully
RF001 Transaction Id not found
RF002 Transaction is not in Success Status.
RF003 This Transaction is already full refunded
RF004 Transaction is Pending for Settlement.
RF005 Refund amount is greater than transaction amount.
RF006 Required parameter is missing or blank.
RF007 Refund RequestId is Already Exist it should be unique for every Refund Reques
RF008 No Default value for RequestRefundId.
RF009 Error Occurred while fetching Data.
{ "txn_id":"09139236000000200021616", "refund_type_status":"FR", "addedBy":"merchant", "resp_message":"Refund Request Raised Successfully.", "resp_code":"RF000", "refund_amount":"1.00", "merchant_id":"M0000379", "txn_amount":"1.00", "refundRequestId":"test_010101", "pg_ref_id":"1002019814160372278", "rrn":"160720201594889257768" }

Refund Status API

Post(Server to Server Call)URL : https://hdfcprodsigning.in/onepayVAS/refundStatus

Below is the response code and response message for Refund Status API:

RS000 Refund Received successfully.
RS000 Refund Under Processed.
RS000 Refund Processed successfully.
RS001 Transaction Id does not exist.
RS002 RefundRequestId does not exist.
RS003 Required Parameters are Missing.
RS004 Error While Fetching Records.

Request parameters need to be converted into json format as sample given below -

Refund Status API Request -

{ "merchantId":"M0002", "encData":"zOlISEom3AloKFZffMM8TI4/+ArMozZTe+96BmL5oVQBaRpt3ieXef8FGWQFk7m9LNzPCwk4NUdqtsniC3s1A2eowXkcEdJvSmhLowgPxU6F/BYvcH6Ls5peE/sZFja6" } encData : { "txnId":"011020191569908197318", "merchantId":"M0002", "refundRequestId":"511510555155" }

Refund Status API response -

{ "txn_id":"011020191569908197318", "refund_type_status":"PR", "addedBy":"M0002", "resp_message":"Refund Processed successfully", "ArnNo":"111111111111", "resp_code":"RS000", "refund_amount":"4.00", "merchant_id":"M0002", "txn_amount":"10.00", "refundRequestId":"511510555155", "pg_ref_id":"1001927405360476127", "rrn":"018346000002" }