Checkout Workfow EN

Introduction

This instruction was developed by JSC Global Solutions and describes the procedure for interaction with the payment service GLOBAL PAY CHECKOUT for the purpose of implementing electronic monetary transactions between the service provider and the payment gateway via a unified form of payment within the Backend connection.

Terms and definitions

Operator - JSC Global Solutions

Supplier - A legal entity providing its services via online payments (shops, cinemas, telecoms, utility/tax services, etc.).

GLOBAL PAY CHECKOUT payment service - Automated payment service owned by Global Solutions JSC, automating the acceptance of payments in favor of suppliers

User - Person on whose behalf the payment is made

Payment system - Processing centers Uzcard, Humo, Visa, Mastercard, etc.

{{base_checkout_url}} - Base part of the Checkout system URL for making HTTP requests, for example, to create a payment token.

For the test environment, it takes the value https://checkout-api-dev.globalpay.uz/checkout

For staging - https://checkout-api-staging.globalpay.uz/checkout

For the production environment - https://checkout-api.globalpay.uz/checkout

Steps and conditions before starting the integration

  1. Global Solutions JSC receives a request";

  2. After the supplier's request for consideration for connection to the GLOBAL PAY CHECKOUT payment gateway is approved, an agreement is drawn up

  3. Technical specialists of Global Solutions JSC register the supplier in the GLOBAL PAY GATE system and issue it with a "service_id" and "client_id", as well as authentication data required for subsequent interaction with the payment service.

  4. After providing all the necessary credentials to the supplier, the supplier begins development and testing in a test environment.

Brief interaction diagram:

Checkout Diagram

Sequence of actions:

Step zero is the authentication of the merchant in the Operator's system. It can be carried out at any stage of interaction.

  1. createServiceToken - Request to create a payment token from the Merchant system
  2. serviceTokenResponse - response to a request to create a token from the Operator system
  3. redirectUrl - redirect the user's browser to the payment page
  4. cardDetails - user input of payment card data
  5. requestOtp - request for an OTP code from the Operator in the Processing Center
  6. SMS - sending an SMS with an OTP code to the SMS notification number of the payment card
  7. OTP code - input of the received OTP code by the user
  8. verifyOtp - sending the OTP code by the Operator to the Processing Center
  9. response - response to a request to verify the OTP code and make a payment
  10. callback - request from the Supplier system to the Merchant system with data on the transaction result to the address agreed with the Merchant (callback)
  11. paymentResponse - notifying the user of the transaction result and redirecting the user to the Merchant page (if any) specified when creating the payment token)
  12. getPayment - Request for transaction information. The Merchant sends a payment token
  13. paymentResponse - the Operator's system returns transaction data, if any, in the system.

Detailed description of authorization and payment steps

Receiving an Authorization Token

POST Request to {{base_checkout_url}}/v1/merchant/auth
with the request body

where oauth_username and oauth_password are the login and password issued to the merchant. The response will be a structure of the following type:

access_token- must be used for subsequent requests as Authorization: Bearer token as a request header. Its expiration date is specified in the expires_in field in seconds.

refresh_token - can be used to refresh the token by POSTing to {base_checkout_url}/v1/merchant/auth/refresh. The refresh token expiration time is specified in the refresh_expires_in field in seconds.

Creating a Payment Token

The merchant system makes a POST request to the address of the following structure:

name- token name. Must be globally unique. Required to avoid confusion with the User.

description- Payment description

externalId- Transaction ID in the Merchant system

accountRecipient ID in the provider (Merchant) system

tokenLifespan- Optional field. Payment token lifetime in seconds. By default 900, minimum 300, maximum 86400. If a value less than 300 (5 minutes) is specified, 300 will be set. If a value greater than 86400 (24 hours) is specified, 86400 will be set.

externalServiceId- The serviceId provided to the Merchant, representing the cash register identifier for making payments

itemsProduct data for the State Tax Committee. May be empty within a single payment (product), otherwise the supplier (Merchant) is obliged to fill in in accordance with the law.

requestFields- Fields for providing further information on the payment. Mandatory fields are those with the names amount and currency, meaning the amount of the payment in the minimum currency value (tiyins for Uzbek soms) and the currency, respectively.

successRedirectUrl - link to which the User's browser will be redirected in case of a successful payment

failRedirectUrl - link to which the User's browser will be redirected in case of an unsuccessful payment.

The following structure will be returned in response:

The new thing here is the id field - it is payment token, which will be used further to redirect the user to the page for entering payment card details and making the payment.

Upon receiving a response from this structure, it is necessary to redirect the user to the web page, the address of which is specified in the userRedirectUrl field.

User actions and OTP code

To make a payment, the User will have to enter the payment card details and click the Pay button. If the card belongs to the UZCARD or Humo Payment Systems, they will request an OTP code and a form will open for entering the code received from the SMS. If the card belongs to the Visa/Mastercard Payment Systems, the OTP code will not be requested at this stage.

If the card belongs to the Visa/Mastercard Payment Systems, the user will be shown a form for entering the OTP code to pass the 3DSecure check. The form belongs to the bank and its contents are controlled by the bank.

After entering all the data, the user will receive a notification about the payment made and a page for a successful or unsuccessful payment will open in the browser. If the successRedirectUrl and failRedirectUrl fields were specified when creating a payment token, then upon successful or unsuccessful payment, the browser will be redirected to the pages specified in these fields.

If a payment for a token has already been made or more than 15 minutes have passed since the token was created, it will be impossible to make a payment for this token.

Getting payment status

When making a payment, the Operator's system can execute a callback request to the Merchant's system with data on the completed payment in the format

Where status can take the values ​​APPROVED - for a successful transaction, or FAILED - for an unsuccessful one. In case of an unsuccessful transaction, the error field will be filled (for example, with the value “INSUFFICIENT_FUNDS“ for unsuccessful transactions due to insufficient funds).

gnkDetail - will be filled for successful transactions with the receipt fiscalization data in the State Tax Committee, where qrCodeUrl will be a link to receive an electronic receipt.

Also, at any stage of work, it is possible to request up-to-date information about the payment by executing a GET request to the address {{base_checkout_url}}/v1/payment/servicetoken/{{user_service_token}}

Where user_service_token - should take the value of the payment token identifier (the “id“ field from the response to the POST user-service-tokens request above).

The response will contain the same structure as in the body of the callback request with the same data.

If more seconds have passed since the token was created than was specified in the tokenLifespan field (by default 900, or 15 minutes) and the system has not received card data and a payment request from the user, the payment will receive the status = FAILED with the error field = “PAYMENT_EXPIRED“.

Received errors.

The following HTTP error codes are possible:

400 - Invalid data in the request

401 - Request not authorized

404 - Entity not found in the system, or the called URL does not exist

500 - Unexpected server error.

The error body comes in the following format:

detail - Error description.

code - Error code.

path - The address of the request that caused the error.

timestamp - The time the error occurred.

trace - The request identifier for diagnostics.

Supported by