Nubi API Integration Guide

able of Contents

1. Introduction 4

   1. Get Started 4

   2. Intended Audience 4

2. Server API 5

   1. Important Information 5

   2. List of API 5

   3. Important Parameters 6

   4. API Endpoints 6

   5. API Response 7

   6. Hosted Payment Checkout Flow 10

   7. Server API Flow 10

   8. API – getauthcode 11

   9. API – dotransaction 13

   10. API – docapture 15

   11. API – dovoid 16

   12. API – dorefund 17

   13. API – gettransaction 18

3. Sample Code 19

4. Useful Information 20

   1. IPN – Instant Payment Notification 20

   2. Response Codes 21

   3. Testing 24

1. ‌Introduction

   1. ‌Get Started

       

      Voguepay offers multiple integration options which enables you to collect payments online in a secure environment. This document describes the protocols, parameters, and technical environment for merchants who want to integrate with our solution.

       

   2. ‌Intended Audience

       

      If you are a technology professional or developer, then this guide will give you all the technical information you need to integrate the payment platform into your application. It assumes that you are already familiar with web development techniques.

2. ‌Server API

   1. ‌Important Information

       

      • The gateway supports the following HTTP methods while consuming API.

        • GET

        • POST

      • All communications with the gateway support TLS1.2 onwards

      • Data exchange between your application and the gateway can be done using JSON/XML object post and URL-encoded query string parameters.

      • The gateway offers sandbox environment for you to integrate and test your code with our payment platform.

        • Sandbox Host – “https://sandbox.voguepay.com”

        • Live Host – “https://secure.voguepay.com”

      • All future API references in this document use sandbox host. You must replace this with live URL whenever your account is activated, and you are ready to go live.

      • Server API – the gateway offers you server level integration if you have PCI DSS level 1 certificate. This enables you to collect card details on your site and send to the gateway in a secure environment.

      • IPN – the gateway offers instant payment notification where all transaction related information is posted back to your preferred URL in JSON formatted string. This is typically used in back-office environment where you need to take some action once the payment has been confirmed, for e.g., ship some items or generate subscription details.

         

   2. ‌List of API

       

      S. No.	API Name	Description
      1	getauthcode	This API is used to generate the transaction authorization code and redirect the buyer to the gateway hosted checkout page.
      2	dotransaction	This server API is used to perform card-based transactions. PCI DSS certification needed to consume this API.
      3	docapture	This server API is used to perform a capture on a previously authorized transaction.
      4	dovoid	This server API is used to perform a void on a previously authorized transaction.
      5	dorefund	This server API is used to issue refund in full or partial from the actual transaction amount.
      6	gettransaction	This server API is used to query the gateway and get the transaction status and details in real-time.

   3. ‌Important Parameters

       

      There are some important parameters which are required based on the API being consumed.

      • MID – this is your merchant id assigned to you once your account is activated. You may find this in your back-office panel.

      • APIKEY – this API key is used to generate authorization code. It is only used with “getauthcode” API. You

        may find this in your back-office panel.

      • SERVERKEY – this API key is used in server level integration. You may find this in your back-office panel. Please contact your account manager or support in case you need to enable this.

        Please note: this key should be used securely from server side and should never be shared over browser URLs or open form submissions.

      • DOMAINNAME – this parameter is used to identify business or terminal. By passing relevant values in this parameter helps you control the transaction flow. This is defined in your back-office panel and configured by the gateway operations team.

         

   4. ‌API Endpoints

       

      S. No.	API Name	Endpoint
      1	getauthcode	{host}/api/getauthcode
      2	dotransaction	{host}/api/dotransaction
      3	docapture	{host}/api/docapture
      4	dovoid	{host}/api/dovoid
      5	dorefund	{host}/api/dorefund
      6	gettransaction	{host}/api/gettransaction

   5. ‌API Response

       

      All API listed above returns the following response object.

       

      Parameter	Description
      status	Status of current operation. Following are the possible values: success – denotes successful operation error – denotes some error occurred
      code	Status code returned by the API. List available below under response codes.
      minorcode	Minor code returned by the API. List available below under response codes.
      message	Descriptive message specifying reason. List available below under response codes.
      amount	Transaction amount with 2 decimal places.
      authcode	Transaction authorization code.
      transactionid	Unique transaction id for the operation.
      orderid	Merchant reference id passed during API calls.
      redirecturl	URL where the buyer should be redirected, if available.
      custom1	User defined variable passed during API calls.
      custom2	User defined variable passed during API calls.
      custom3	User defined variable passed during API calls.
      custom4	User defined variable passed during API calls.
      custom5	User defined variable passed during API calls.
      wtcode	Web terminal code for assisted transactions.

       

      Sample JSON response

       

      {“status”:”success”,”code”:”0″,”minorcode”:”0″,”message”:”This request processed successfully”,”amount”:”99.99″,”authcode”:”624c63fb-55f4-4e9f-b99a- 3d5c4cc19094″,”transactionid”:”10156079″,”orderid”:”200422154046″,”redirecturl”:””,”custom1″:””,”custom2″:””,”c ustom3″:””,”custom4″:””,”custom5″:””,”wtcode”:””}

Response object for gettransaction API

Sample JSON response

1. 1. ‌Hosted Payment Checkout Flow

       

      • Buyer visits merchant website and selects goods/services to purchase

      • Buyer selects checkout and is ready to pay

      • Merchant calls getauthcode api with required parameters

      • After validating input data, server responds with a redirecturl parameter in api response

      • Merchant redirects buyer to redirect url

      • Buyer provides payment details and pays securely

      • If 3D secure is enabled, buyer is automatically redirected to bank site for payment confirmation

      • After payment completion server redirects buyer to payment confirmation page

      • If merchant provided response_url parameter, then buyer is redirected to this page

      • Server appends transaction authcode as querystring to this url

      • Merchant utilizes this authcode to query transaction status using gettransaction API and displays appropriate response

         

   2. ‌Server API Flow

       

      • Buyer visits merchant website and selects goods/services to purchase

      • Buyer selects checkout and is ready to pay

      • Merchant calls dotransaction api with required parameters

      • After validating input data, server responds with a payment status and details

      • If redirection is required by bank, server returns redirecturl in api response

      • Merchant should redirect buyer to this url which automatically redirects buyer to bank site for payment confirmation

      • After payment completion server redirects buyer to payment confirmation page

      • If merchant provided response_url parameter, then buyer is redirected to this page

      • Server appends transaction authcode as querystring to this url

      • Merchant utilizes this authcode to query transaction status using gettransaction API and displays appropriate response

   3. ‌API – getauthcode

       

      This API is used to generate the authcode which returns a redirect URL where the buyer is redirected to complete payment. This is the gateway hosted checkout page.

      Fields marked in red * are mandatory. All fields accept string values and follow tight validation rules and no special characters are allowed.

       

      Parameter	Description
      mid *	Merchant id.
      apikey *	API key used to initiate transaction. This is available in your back-office panel.
      domainname *	Unique domain name or LOB which is configured in your account.
      fullname *	Buyer’s full name.
      email *	Buyer’s email.
      phone *	Buyer’s phone.
      orderid *	Your reference id. You should always pass a unique value in this field.
      countrycode *	Buyer’s country. 3-character ISO code.
      currencycode *	Transaction currency. 3-character ISO code.
      amount *	Transaction amount with up to 2 decimal places.
      paymentmodes	Payment modes to display on hosted page. If multiple, then you should concatenate with pipe character “|” Valid values: creditcard, debitcard, netbanking, upi Sample: creditcard |upi
      paymenttype *	Transaction payment type. Possible value: sale sale – funds are directly captured from buyer card authorize – funds are blocked for later capture
      response_url	URL where the buyer will be redirected after transaction operation. The gateway server passes transaction authcode in query string for you to query the status and display relevant messaging to the buyer. If this parameter is not supplied, then the gateway hosted response page is displayed.
      cancel_url	URL where the buyer will be redirected in case the transaction is cancelled by the buyer. If this parameter is supplied, then a cancel button is displayed on the gateway hosted payment page else this is hidden.
      ipn_url	URL where the server will send instant payment notification. Please refer IPN section for more details.
      custom1	User defined variable, can be used to pass additional value.
      custom2	User defined variable, can be used to pass additional value.
      custom3	User defined variable, can be used to pass additional value.
      custom4	User defined variable, can be used to pass additional value.
      custom5	User defined variable, can be used to pass additional value.
      bill_address *	Buyer’s billing address.
      bill_city *	Buyer’s billing city.
      bill_state *	Buyer’s billing state.
      bill_country *	Buyer’s billing country. 3-character ISO code.
      bill_postalcode *	Buyer’s billing postal code.
      ship_address	Buyer’s shipping address.
      ship_city	Buyer’s shipping city.
      ship_state	Buyer’s shipping state.
      ship_country	Buyer’s shipping country. 3-character ISO code.

       

      ship_postalcode

      Buyer’s shipping postal code.

   4. ‌API – dotransaction

       

      This API is used to initiate direct server level transaction. You should have PCI compliance certificate as this enables you to collect card details on your website.

      Fields marked in red * are mandatory. All fields accept string values and follow tight validation rules and no special characters are allowed.

       

      Parameter	Description
      mid *	Merchant id.
      serverkey *	Server API key used to initiate transaction. This is available in your back-office panel. Please ask your account manager or support to activate this. You need PCI certification.
      client_ip *	Buyer’s IP address
      domainname *	Unique domain name or LOB which is configured in your account.
      fullname *	Buyer’s full name.
      email *	Buyer’s email.
      phone *	Buyer’s phone.
      orderid *	Your reference id. You should always pass a unique value in this field.
      countrycode *	Buyer’s country. 3-character ISO code.
      currencycode *	Transaction currency. 3-character ISO code.
      amount *	Transaction amount with up to 2 decimal places.
      paymentmode *	Payment mode. Valid value: creditcard or debitcard
      paymenttype *	Transaction payment type. Valid value: sale sale – funds are directly captured from buyer card authorize – funds are blocked for later capture
      response_url	URL where the buyer will be redirected after transaction operation. The gateway server passes transaction authcode in query string for you to query the status and display relevant messaging to the buyer. If this parameter is not supplied, then the gateway hosted response page is displayed.
      ipn_url	URL where the server will send instant payment notification. Please IPN section for more details.
      custom1	User defined variable, can be used to pass additional value.
      custom2	User defined variable, can be used to pass additional value.
      custom3	User defined variable, can be used to pass additional value.
      custom4	User defined variable, can be used to pass additional value.
      custom5	User defined variable, can be used to pass additional value.
      bill_address *	Buyer’s billing address.
      bill_city *	Buyer’s billing city.
      bill_state *	Buyer’s billing state.
      bill_country *	Buyer’s billing country. 3-character ISO code.
      bill_postalcode *	Buyer’s billing postal code.
      ship_address	Buyer’s shipping address.
      ship_city	Buyer’s shipping city.
      ship_state	Buyer’s shipping state.
      ship_country	Buyer’s shipping country. 3-character ISO code.
      ship_postalcode	Buyer’s shipping postal code.
      cardnum *	Card number.

       

      expiryyear *	4-digit card expiry year.
      expirymonth *	2-digit card expiry month.
      cardcvv *	3-digit or 4-digit card CVV code.
      cardholder *	Cardholder name.
      cardpin *	Debit card PIN. Required or optional as per geographic requirements.
      token	Card token.

   5. ‌API – docapture

       

      This API is used to collect the funds due from completed authorizations. It supports both full and partial capture operation. The capture activity can be initiated only once.

      Fields marked in red * are mandatory. All fields accept string values and follow tight validation rules and no special characters are allowed.

      Please consult your account manager to check if this feature is available to you.

       

      Parameter	Description
      mid *	Merchant id.
      serverkey *	Server API key used to initiate transaction. This is available in your back-office panel. Please ask your account manager or support to activate this. You need PCI certification.
      transactionid *	Transaction authcode you received after completing the initial transaction operation.
      amount *	Transaction amount with up to 2 decimal places to capture from initial authorized amount. This should always be less than or equal to original amount. Partial amount capture activity can only be done once. The remaining balance is automatically voided.

   6. ‌API – dovoid

       

      This API is used to void the funds from previously completed authorizations. This releases the amount that was blocked from the credit card without collecting it.

      Fields marked in red * are mandatory. All fields accept string values and follow tight validation rules and no special characters are allowed.

      Please consult your account manager to check if this feature is available to you.

       

      Parameter	Description
      mid *	Merchant id.
      serverkey *	Server API key used to initiate transaction. This is available in your back-office panel. Please ask your account manager or support to activate this. You need PCI certification.
      transactionid *	Transaction authcode you received after completing the initial transaction operation.

   7. ‌API – dorefund

       

      This API returns money into the buyer’s payment mode used during initial transaction which can be a partial amount or full amount. The refund amount cannot exceed the original transaction amount. The refund activity can be initiated only once.

      Fields marked in red * are mandatory. All fields follow tight validation rules and no special characters are allowed.

       

      Parameter	Description
      mid *	Merchant id.
      serverkey *	Server API key used to initiate transaction. This is available in your back-office panel. Please ask your account manager or support to activate this.
      transactionid *	Transaction authcode you received after completing the initial transaction operation.
      amount *	Transaction amount with up to 2 decimal places to refund from initial transaction amount. This should always be less than or equal to original amount. Partial amount refund activity can only be done once.
      reason *	A small descriptive message specifying reason for refund.

   8. ‌API – gettransaction

       

      This API can be used to query payment gateway server and get the transaction details in real-time.

      Fields marked in red * are mandatory. All fields accept string values and follow tight validation rules and no special characters are allowed.

       

      Parameter	Description
      mid *	Merchant id.
      serverkey *	Server API key used to initiate transaction. This is available in your back-office panel. Please ask your account manager or support to activate this.
      transactionid *	Transaction authcode you received after completing the initial transaction operation.

2. ‌Sample Code

    

   The simplest form of integration is by forming a URL and redirecting the buyer to this URL. Please see an example below. Replace values with your account details:

   {host}/api/getauthcode?mid=1111&apikey=ABCD1234&fullname=Rahul%20Singh&[email protected]& phone=1231231234&countrycode=IND&orderid=200409103717&bill_address=Street%201&bill_city=New% 20Delhi&bill_state=Delhi&bill_country=IND&bill_postalcode=110017&currencycode=INR&amount=1.99&re sponse_url=&cancel_url=&domainname=value&paymenttype=sale

    

   Ensure that you URL encode values before redirecting the buyer to the gateway server.

    

   The gateway system uses REST API which you can integrate with any language or platform of our choice. You just need to form proper post data as per API requirement and post it to API endpoint. The post can be in the form of:

   1. JSON

   2. XML

   3. Form key-value pair

3. ‌Useful Information

   1. ‌IPN – Instant Payment Notification

       

      The gateway server sends out notification to your URL which can be configured in your back-office panel or sent as request parameter in getauthcode or dotransaction API. The details of these notifications are mentioned below.

      IPN object parameters sent to your notification URL

       

      Parameter	Description
      ipnevent	IPN event type. Following events are triggered by the gateway server.   IPNTEST – test event AUTHCODE – when getauthcode api completed successfully TXNAPI – when payment transaction completes successfully CAPTURE – when payment transaction captured successfully VOID – when payment transaction voided successfully REFUND – when refund processed successfully
      postdata	Contains the complete response object as returned by gettxnstatus API

       

      Sample IPN response object

       

      “ipnevent”:”AUTHCODE”,”postdata”:”{“status”:”success”,”code”:”0″,”minorcode”:”0″,”message”:”This request processed successfully”,”id_merchant”:”10010001″,”authcode”:”624c63fb-55f4-4e9f-b99a- 3d5c4cc19094″,”transactionid”:”10156079″,”orderid”:”200422154046″,”paymentmode”:”creditcard”,”paymenttype”: “sale”,”txnamount”:”99.99″,”txn_status”:”TXN_COMPLETE”,”txn_code”:”0″,”txn_minorcode”:”0″,”txn_message”:”This request processed successfully”,”currencycode”:”USD”,”originalamount”:”99.99″,”fullname”:”Jack Smith”,”email”:”[email protected]”,”phone”:”1231231234″,”city”:”New York”,”countrycode”:”USA”,”postalcode”:”12345″,”billing_info”:”Street 1|New York|NY|USA|12345″,”shipping_info”:”||||”,”nameoncard”:”Jack Smith”,”cardtype”:”Mastercard”,”cardtrunc”:”554637******1457″,”custom1″:””,”custom2″:””,”custom3″:””,”custom

      4″:””,”custom5″:””,”domainname”:”3dsn”,”token”:””}”}

1. 1. ‌Response Codes

       

      Below is a comprehensive list of all codes and their corresponding messages returned by the gateway system. This list is updated as and when new banks or acquirers are added to the system. You should always rely on success code “0” and “txn_status” as returned by gettransaction API and design your solution accordingly.

       

      Code	Minorcode	Message
      0	0	This request processed successfully. The txn_status value in this case should be TXN_COMPLETE
      0	0	This request is pending and will be reversed or charged automatically after bank confirmation. The txn_status value in this case will be TXN_PENDING
      2001	2001001	Invalid data in source
      	2001002	Domain name value is missing or contains invalid data
      	2001003	Fullname value is missing or contains invalid data
      	2001004	Email value is missing or contains invalid data
      	2001005	Phone value is missing or contains invalid data
      	2001006	City value is missing or contains invalid data
      	2001007	Country code value is missing or contains invalid data
      	2001008	Postal code value is missing or contains invalid data
      	2001009	Order ID value is missing or contains invalid data
      	2001010	Currency code value is missing or contains invalid data
      	2001011	Payment type value is missing or contains invalid data
      	2001012	Response URL format is invalid or contains invalid data
      	2001013	Cancel URL format is invalid or contains invalid data
      	2001014	IPN URL format is invalid or contains invalid data
      	2001015	Custom fields contain invalid data
      	2001016	Billing address fields contains invalid data
      	2001017	Shipping address fields contains invalid data
      	2001018	Billing address data is required
      	2001019	Shipping address data is required
      	2001020	Tokenize field contains invalid data
      	2001021	Token field contains invalid data
      	2001022	Merchant ID value is missing or contains invalid data
      	2001023	API key value is missing or contains invalid data
      	2001024	Server key value is missing or contains invalid data
      	2001025	Transaction ID value is missing or contains invalid data
      	2001026	Amount value is missing or contains invalid data
      	2001027	Client IP value is missing or contains invalid data
      	2001028	Payment mode value is missing or contains invalid data
      	2001029	Card holder value is missing or contains invalid data
      	2001030	Card holder fullname is required
      	2001031	Card CVV value is missing or contains invalid data
      	2001032	Card expiry value is missing or contains invalid data
      	2001033	Card number value is missing or contains invalid data
      	2001034	Netbanking bank code value is missing or contains invalid data
      	2001035	VPA or UPI id value is missing or format is invalid

       

      	2001036	Payout key value is missing or contains invalid data
      	2001037	Account holder value is missing or contains invalid data
      	2001038	Account number value is missing or contains invalid data
      	2001039	IFSC value is missing or contains invalid data
      	2001040	Account type is missing or contains invalid data
      	2001041	Remark data is missing or contains invalid data
      	2001041	Beneficiary name value is missing or contains invalid data
      	2001042	Beneficiary bank value is missing or contains invalid data
      	2001043	Beneficiary code value is missing or contains invalid data
      	2001044	Payout type should be either NEFT, IMPS, RTGS or FT
      	2001045	Beneficiary vpa value is missing or contains invalid data
      	2001100	This transaction authorization is used
      	2001101	This transaction session has expired
      	2001102	Buyer cancelled the transaction
      	2001103	This transaction authorization is in 3DS process
      	2001104	Failed to process transaction, please try again
      2002	2002000	This HTTP method is not supported
      	2002001	This api key is not authorized to perform this request
      	2002002	This API key not authorized to use tokenization
      	2002003	This server key is not authorized to perform this request
      	2002004	This server key not authorized to use tokenization
      	2002005	Invalid merchant id
      	2002006	Invalid api key
      	2002007	Invalid server key
      	2002008	Invalid transaction id
      	2002009	Invalid domain name or lob
      	2002010	This transaction is not in authorize state
      	2002011	This transaction is not in sale or capture state
      	2002012	Capture amount should be greater than 0 and less than or equal to transaction amount
      	2002013	Reason text is missing or invalid data in reason field
      	2002014	Refund amount should be greater than 0 and less than or equal to transaction amount
      	2002015	Exception occurred, please try again
      	2002016	Invalid token
      	2002017	Domain name does not match with token domain name
      	2002018	Card CVV is required for this transaction
      	2002019	Configuration error, please contact support
      	2002020	Invalid country code
      	2002021	Invalid currency code
      	2002022	Transaction count for the day exceeds the limit
      	2002023	Transaction amount is 0 or exceeds the maximum amount limit
      	2002024	Duplicate order id
      	2002025	Invalid card number
      	2002026	Invalid card expiry
      	2002027	Invalid session code
      	2002028	Invalid netbanking bank code
      	2002029	Daily refund limit reached, please try again after some time
      	2002030	Invalid passcode

       

      	2002030	Payouts is not allowed for this MID
      	2002031	Invalid payout key
      	2002032	Payouts api is currently locked
      	2002033	This IP address is not allowed
      	2002034	Amount value greater than allowed value
      	2002035	Not enough funds
      	2002036	Configuration error in payout fees
      	2002037	You have exceeded total transaction count for the day
      	2002038	Beneficiary code is required for payout
      	2002039	Bank details (account holder, number, ifsc, account type) are required for payout
      	2002040	The given payout type is not supported
      	2002041	Amount value should be greater than 0
      	2002042	Beneficiary vpa is required for payout
      	2002043	Duplicate order id is not allowed
      2003	2003001	Failed to process your request, please try again
      	2003002	Configuration error, no gateways defined
      	2003003	System exception, please try again
      	2003004	Processing transaction post auth
      	2003005	System exception while capturing funds, please try again
      	2003006	System exception while voiding funds, please try again
      	2003007	System exception while refunding funds, please try again
      	2003008	Failed to generate authcode, please try again
      	2003009	Failed to generate transaction id, please try again
      	2003010	Failed to generate transaction id, please try again
      	2003011	Failed to update transaction id, please try again
      2004	2004001	Failed to process this request
      	2004002	Redirect buyer
      	2004003	Non 3D secure cards are not allowed
      	2004004	Partial 3DS attempt
      	2004005	This transaction is in 3D secure check
      	2004006	3DS data error
      	2004007	Pending
      2005	2005001	Failed to process this request
      	2005010	Failed to process your request, gateway error
      	2005011	System exception
      	2005012	Data not found or is still pending
      	2005013	Data not found

   2. ‌Testing

Please ask your account manager to setup sandbox MID and provide you testing details.