Payment Gateway API

Payment Gateway API is a protocol for connecting payment gateways. This service allows you to connect any existing payment gateway with minimal time and resources using a single connection scheme. The advantage of the method is that the development of integration works on the customer side, which means that the customer plans the timing of integration independently and independently manages the resource for it.

Contents

Connection procedure of Payment Gateway API module

The Payment Gateway API module is optional. To connect to Websky via this protocol, contact the commercial department at [email protected].

To connect the payment service using the method presented, the agency must:

1. Contact the commercial department of Websky at [email protected] with an application to connect the product, sign documents to operate the service
2. Create a ticket in the Websky project tracker for the service connection. You will get an access to "UniversalNemoPay" service in the "Access to payment methods" section (available only for Websky admins)
3. Perform integration with Websky via Payment Gateway API protocol, using technical documentation on integration (Technical documentation on integration with Payment Gateway API)
4. Set up the payment method (Set up Payment Gateway) and provide details for interaction between Websky and payment gateway in the ticket (set: URL, login, password) to complete the payment method setup by Websky technical support
5. Test the connection before starting live operation
6. Notify in the ticket that you are ready to switch to product mode. Provide service support contacts for accepting payments and test details for further service support

Special features

The service does not support fiscalization of payments according to the Federal Law 54.

Setting up Payment Gateway in Websky

1. Under Finance and payments → Payment methods → Access to payment methods open access to UniversalNemoPay payment method for users/groups/companies (see Payment methods in Websky for details on configuring)
2. In Finance and payments → Payment methods → Gateway management create a payment method "UniversalNemoPay" (see Payment methods in Websky for details on how to configure it)
3. Open the "Requisites" section of the created payment method and set up access to the payment gateway (see Payment methods in Websky for more information on setting up):
   • "Client server URL for requests - the address of requests to access the Service, for example http://test.com/test
   • API login - access requisite to the payment gateway, issued by the payment gateway
   • Password - payment gateway access requisite, issued by the payment gateway
   • Currency - currency under the agreement with the payment gateway
   • Use two-stage payment - if the parameter is on, the scheme of requests with preauthorization will be used. If it is disabled - the scheme of requests without preauthorization.
   • Allow payment by Visa Electron and MasterCard Maestro cards only.
   • Add locator to the beginning of payment identifier when transmitting to payment gateway - locator prefix will be added to orderNumber.
   • Display frame with payment page on the order info page - to pay in a frame on the order page without going to the payment gateway page
   • Frame height with payment page - set the frame height

Technical documentation on integration with Payment Gateway API

Terms used in this section:

• Websky system - Websky booking system,
• Service - payment acceptance service.

Query description

Request name	Description	Features
register.do	Order registration request (without preauthorization)	-
registerPreAuth.do	Order registration request with preauthorization	-
deposit.do	Request to complete the payment of the order	-
reverse.do	Request to cancel the payment of the order	-
refund.do	Request for a refund of the order payment	-
getOrderStatusExtended.do	Extended order status request	-

• Requests used for two-stage payment (with preauthorization): registerPreAuth.do, deposit.do.
• Requests used for one-stage payment (without preauthorization): register.do.
• Requests reverse.do, refund.do and getOrderStatusExtended.do can be used for any payment scheme.
• When a refund is required, the Websky system sends an order update request to the payment gateway. If the received order status is orderStatus=1, then a reverse.do request is sent, if orderStatus=2, then refund.do is sent.

Procedure of interaction between the Websky System and the Service

Payment with preauthorization

1. When initiating a payment, Websky System sends an Order Registration Request registerPreAuth.do.
2. Websky System redirects the user to the url that the Service specified in the response to the registration request to perform an acquiring transaction on the Service side.
3. Websky System periodically sends a getOrderStatusExtended.do request to get the order status until the Service specifies 1 or 6 as the orderStatus when the errorCode value is zero. If orderStatus = 6, the payment procedure in the Websky System is terminated as unsuccessful. If orderStatus = 1, the procedure continues.
4. Service redirects the customer back to the order page (returnUrl in the registerPreAuth.do request) in parallel with the completion of the transaction. As a result of the operation Websky System additionally sends a getOrderStatusExtended request to get the current payment status. If orderStatus = 6, the payment procedure in Websky System is terminated as unsuccessful. If orderStatus = 1, the procedure continues.
   1. Websky System performs the order processing.
   2. If the checkout is successful, Websky System initiates a deposit.do request to complete the acquiring operation on the Service side;
   3. If the checkout is unsuccessful, Websky will initiate a reverse.do request;
   4. Payment procedure completed.

Payment without preauthorization

1. When payment is initiated, Websky sends a register.do request.
2. Websky System redirects the user to the url that the Service specified in the response to the registration request to perform an acquiring operation on the Service side.
3. Websky System periodically sends a getOrderStatusExtended.do request to get the order status until the Service specifies 2 or 6 as the orderStatus when the errorCode value is zero. If orderStatus = 6, the payment procedure in the Websky System is terminated as unsuccessful. If orderStatus = 2, the procedure continues.
4. Service redirects the customer back to the order page (returnUrl in the register.do request) in parallel with the transaction completion. As a result of the transaction, Nemo System additionally sends a getOrderStatusExtended request to get the current payment status.
5. If orderStatus=2 and errorCode=0, the Websky system executes the order.

Refunds

For a refund, Websky System sends getOrderStatusExtended.do.

• If the received orderStatus=1, Websky System sends a reverse.do request,
• If orderStatus=2, Websky sends a refund.do request.

Format of requests/responses

Universal API for connecting payment gateways is implemented with HTTP requests/responses using POST method.

• register.do

Request parameters: userName, password, orderNumber, amount, returnUrl, currency, description, language, jsonParams

Parameter name	Description	Features
userName	API login	Store login received when connecting
password	Password	Store password obtained by connection
orderNumber	Order number (identifier) in the store system, unique for each store within the system	Billing number
amount	Payment amount	Payment amount in pennies (or cents)
returnUrl	Address to which you want the user to be redirected in case of successful payment. The value must be an absolute link.	Example: "http://test.com/universal_nemo_pay__after_authorisation?billing_id=111111111".
currency	Currency	Payment currency code ISO 4217.
description	Free-form description of the order	Example: "Payment for order #586578 (1X96WD) from http://test.com".
language	Language in ISO 639-1 encoding.	Example: "ru".
jsonParams	Block for transferring additional parameters of the merchant.	Example of data transferred by Websky: {"onlyMaestro": "false", "email": "[email protected]", "phone": "79270099000"}

Response parameters: orderId, formUrl, errorCode, errorMessage.

Parameter name	Description	Features
orderId	Order number in the payment system. Unique within the system.	-
formUrl	URL of the payment form to which the client's browser should be redirected.	-
errorCode	Error code.	Any value other than "0" is treated by our system as an unsuccessful response.
errorMessage	Error description in the language passed in the parameter language in the request.	-

• registerPreAuth.do

Request parameters: userName, password, orderNumber, amount, returnUrl, currency, description, language, jsonParams

Parameter name	Description	Features
userName	API login	Store login received when connecting
password	Store password obtained by connection
orderNumber	Order number (identifier) in the store system, unique for each store within the system	Billing number
amount	Payment amount	Payment amount in pennies (or cents)
returnUrl	Address to which you want the user to be redirected in case of successful payment. The value must be an absolute link.	Example: "http://test.com/universal_nemo_pay__after_authorisation?billing_id=111111111".
currency	Currency	Payment currency code ISO 4217.
description	Free-form description of the order	Example: "Payment for order #586578 (1X96WD) from http://test.com".
language	Language in ISO 639-1 encoding.	Example: "ru".
jsonParams	Block for transferring additional parameters of the merchant.	Example of data transferred by Websky: {"onlyMaestro": "false", "email": "[email protected]", "phone": "79270099000"}

Response parameters: orderId, formUrl, errorCode, errorMessage.

Parameter name	Description	Features
orderId	Order number in the payment system. Unique within the system.	-
formUrl	URL of the payment form to which the client's browser should be redirected.	-
errorCode	Error code.	Any value other than "0" is treated by our system as an unsuccessful response.
errorMessage	Error description in the language passed in the parameter in the "language" request.	-

• deposit.do

Request parameters: userName, password, orderId, amount.

Parameter name	Description	Features
userName	API login	store login received when connecting
password	store password obtained by connection
orderId	Order number in the payment system. Unique within the system.	-
amount	Payment amount in pennies (or cents)

Response parameters: errorCode, errorMessage.

Parameter name	Description	Features
errorCode	Error code.	Any value other than "0" is treated by our system as an unsuccessful response.
errorMessage	Error description in the language passed in the parameter language in the query.	-

• reverse.do

Request parameters: userName, password, orderId.

Parameter name	Description	Features
userName	API login	Store login received when connecting
password	Password	Store password obtained by connection
orderId	Order number in the payment system. Unique within the system.	-

Response parameters: errorCode, errorMessage.

Parameter name	! Description	! Features
errorMessage	Error description in the language passed in the parameter language in the query.	-

• refund.do

Request parameters: userName, password, orderId.

Parameter name	Description	Features
userName	API login	Store login received when connecting
password	Password	Store password obtained by connection
orderId	Order number in the payment system. Unique within the system.	-

Response parameters: errorCode, errorMessage.

Parameter name	Description	Features
errorCode	Error code.	Any value other than "0" is treated by our system as an unsuccessful response.
errorMessage	Error description in the language passed in the parameter language in the query.	-

• getOrderStatusExtended.do

Request parameters: userName, password, orderId, language, orderNumber.

Parameter name	Description	Features
userName	API login	Store login received when connecting
password	Password	Store password obtained by connection
orderId	Order number in the payment system. Unique within the system.	-
orderNumber	Order number (identifier) in the store system, unique for each store within the system	Billing number
language	Language in ISO 639-1 encoding.	Example: "ru".

Response parameters: errorCode, errorMessage, orderStatus and cardAuthInfo(expiration, cardholderName, approvalCode, pan).

Parameter name	Description	Features
errorCode	Error code.	Any value other than "0" is treated by our system as an unsuccessful response.
errorMessage	Error description in the language passed in the parameter language in the query.	-
orderStatus	Order status in the payment system.	0 - Order registered but not paid 1 - Preauthorized amount is locked (for two-stage payments) 2 - Full authorized amount of the order is passed 6 - Authorization denied
cardAuthInfo	Payment attribute tag.	expiration - Card expiration date in the format YYYYMM. cardholderName - Name of the cardholder. approvalCode - Payment authorization code. Fixed length field (6 characters), can contain numbers and Latin letters. pan - Masked number of the card which was used for payment.

See also

• Payment gateway
• Payment methods in Websky