Introduction

Important!
1. Register as a Business
2. Verify your Account
3. Generate API Key and go Live

Accept now, Better Online Payments for Your Business. We take the complexity out of the payment ecosystem, providing smart and seamless solutions that deliver value to your business.

UniPAY’s core asset is its team, which is made up of qualified industry specialists with more than 10 years of professional experience in banking, Fin Tech and e-Commerce. We’ve been developing payment solutions since 2010 and understand them inside and out. This means we can provide a high conversion rate and service up-time. 

$$\   $$\           $$\ $$$$$$$\ $$$$$$\  $$\       $$\
$$ |  $$ |          \__|$$ __$$\ $$  __$$ \\$$\    $$ |
$$ |  $$ |$$$$$$$\  $$\ $$ | $$ |$$ / $$ | \ $$\  $$/
$$ |  $$ |$$ __$$\  $$ |$$$$$$$ |$$$$$$$$|    \$$$$/
$$ |  $$ |$$ | $$ | $$ |$$ ____/ $$ __$$ |    \$$ /
$$ |  $$ |$$ | $$ | $$ |$$ |     $$ | $$ |     $$ |
\$$$$$$  |$$ | $$ |$ $ |$$ |     $$ | $$ |     $$ |
 \______/ \__| \__|\__|\__ |     \__| \__|     \__|

Version 2.0.6

Updated: 08.2022
Author: unipayninja
Mission: Modern payments for Georgia

Everything you need to know to give your customers a great online experience. Accept web and mobile payments and monitor your transactions in real time.



This document is intended to provide the partner with a comprehensive guide how to integrate UniPAY Checkout Solution for accepting payments from Visa, MasterCard and AMEX Cards.

The document will be updated every time a new release is delivered. The document itself is stored in the source control system and all of its versions are available for review.

Onboarding

Before to start development process please make sure that your business is fully verified and have an access into unipay dashboard, where you can create API cridentials for your future projects.



for business registration please Sign Up

Verification

Business account verification is most important part. After registration please follow the verification steps into your unipay dashboard. You will be asked to provide company details and information about project

Live credentials

to Get API keys you need to add a project into your dashboard. when business is fully verified you can get you production API keys for integration.

Get started

⚡️ UniPAY Simple Checkout

unipay.com provides a collection of APIs that enable you to process and manage payments. Our APIs accept and return JSON in the HTTP body, and return standard HTTP response codes. You can consume the APIs directly using your favorite HTTP/REST library or make use of one of our SDKs. We have a testing environment called sandbox, which you can sign up for to test API calls without affecting live data.

Workflow

The workflow of processing a transaction can be summarized in the steps described below.



1) The customer logs in the merchant interface (a website or an application).

2) The customer selects goods or services, or enters the amount for purchase and clicks to PAY

3) The customer chooses from the list of available payment options.

4) The UniPAY checkout API authenticates both the merchant and the received values by calculating the SHA256 checksum from the received values and the secret part, and comparing the resulting value against the received checksum.

5) The Customer confirms the transaction.

Signing mechanism

When you sign up for an account, you are given a Merchant ID and API key. You authenticate with our API by providing the appropriate key in the request Authorization header. Never share your secret keys. Keep them guarded and secure.



all endpoints require authentication using your secret key.

Example of signing generation


# request example json params

json = {
  "MerchantID ": "5007009001051",
  "MerchantUser": "REF-52265_US",
  "OrderID": "Z9s7Yt0Txsqbbx",
  "OrderPrice": "14.99",
  "OrderCurrency": "GEL",
  "OrderName": "Service Order",
  "Items": [
        {
            "price": 9,
            "quantity": 3,
            "title": "test",
            "description": "",
            "currency": "GEL",
            "attribute": ""
        },
        {
            "price": 0.1,
            "quantity": 1,
            "title": "Flat Shipping Rate",
            "description": "Shipping",
            "currency": "GEL",
            "attribute": ""
        }
    ]
}

MerchantID = "5007009001051";
SecretKey = "08fee27d-7834-49c2-b6a3-01c7486b57f9";

# dont forget not to include in string arrays and objects
# dont include {User} because it is a object
SignatureStr = "{SecretKey}|{MerchantID}|{CustomerID}|{OrderID}|{OrderPrice}|{OrderCurrency}|{OrderName}";

Hash = SHA256( SignatureStr  );

Gateway signing mechanism

All requests and responses must be signed/verified using SHA256

A working example: You must provide HASH, Password is unique per request and generated by the SecretKey and body arguments using delimiter | and SHA256 hash


right you can see example of generation signing hash

Payments

Create Order

Endpoint URL: https://apiv2.unipay.com/custom/checkout/v1/createorder

POST /createorder

{
    "Hash": "5a35a2609b5a931ea81bc4b35fb5f4889d8863ae0c39743d809f70cbb1beb5d3",
    "MerchantID": "5005009000211",
    "MerchantUser": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
    "MerchantOrderID": "UN6141ab337e154-29",
    "OrderPrice": 40.59,
    "OrderCurrency": "GEL",
    "SuccessRedirectUrl": "aHR0cHM6Ly9zdWNjZXNzX3JlZGlyZWN0X3VybC51bmlwYXkuY29tLw==",
    "CancelRedirectUrl": "aHR0cHM6Ly9jYW5jZWxfcmVkaXJlY3RfdXJsLnVuaXBheS5jb20v",
    "CallBackUrl": "aHR0cDovL2luZm8udW5pcGF5LmNvbS8=",
    "Language": "GE",
    "OrderName": "StarWars Comics",
    "OrderDescription": "GHOSTS OF VADER’S CASTLE"

}

JSON Response Sample


{
    "errorcode": 0,
    "message": "OK",
    "data": {
        "Checkout": "{{CHECKOUT PAGE URL}}",
        "UnipayOrderHashID": "MP5005009614DF386A5472",
    }
}

HTTP Request

POST https://apiv2.unipay.com/custom/checkout/v1/createorder


To accept a payments merchant should start with createorder function to pass all necessary information for registering the transactions.



Parameters

Value Type Description
Hash String Hash is calculated with secret key and all string parameters which are passed to function. You must not include in hash string parameters which are array or object, and must not include Hash parameter itself use a delimiter between each parameter
MerchantID Integer Merchant unique ID obtained from UniPAY system.
MerchantUser String Clients Identification Account in Merchant System
MerchantOrderID String Merchant Transaction Number
OrderPrice Float >= 0 The payment amount.
OrderCurrency String GEL - Georgian Lari
SuccessRedirectUrl String - Base64 Success redirect URL
CancelRedirectUrl String - Base64 Fail redirect URL
CallBackUrl String - Base64 URL provided by merchant to get transaction status after the payment
Language String GE – Georgia, EN- English,
OrderName String A Title of the payment
OrderDescription String A description of the payment

CallBack

It is best practice for your project to receive POST a callback. We will send request on CallBackUrl parameter.

{
"MerchantOrderID": 51823,
"Status": 3,
"Hash": "808a827a928917e15e79b531227c5b1c81d6bf552b347aad9a91ed0e53a0b317",
"Amount": 20.00,
"UnipayOrderID": "MP50050176151C206A41D9",
"ErrorCode": 0,
"ErrorMessage": "OK",
"Reason": ""
}

Hash Calculation

Hash must be calculated based on SHA 256 based on following params + SecretKey provided by unipay.

Pre Authorization

In a basic payment flow, the payable amount from your payment request is authorised and then captured. But sometimes you may want to change the amount or extend the length of the authorisation before the payment is captured. You can enable this using the authorisation type pre-authorisation with your payment request. In this payment flow you can increase or decrease the authorised amount at a later stage, and then capture the payment. Such changes to a pre-authorised payment are called authorisation adjustments.

Endpoint URL: https://apiv2.unipay.com/custom/checkout/v1/createorder

POST /createorder

{
    "Hash": "5a35a2609b5a931ea81bc4b35fb5f4889d8863ae0c39743d809f70cbb1beb5d3",
    "MerchantID": "5005009000211",
    "MerchantUser": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
    "MerchantOrderID": "UN6141ab337e154-29",
    "OrderPrice": 40.59,
    "OrderCurrency": "GEL",
    "SuccessRedirectUrl": "aHR0cHM6Ly9zdWNjZXNzX3JlZGlyZWN0X3VybC51bmlwYXkuY29tLw==",
    "CancelRedirectUrl": "aHR0cHM6Ly9jYW5jZWxfcmVkaXJlY3RfdXJsLnVuaXBheS5jb20v",
    "CallBackUrl": "aHR0cDovL2luZm8udW5pcGF5LmNvbS8=",
    "Language": "GE",
    "OrderName": "StarWars Comics",
    "OrderDescription": "GHOSTS OF VADER’S CASTLE",
    "OrderType": "preauth"
}

JSON Response Sample


{
    "errorcode": 0,
    "message": "OK",
    "data": {
        "UnipayOrderHashID": "MP5005009614DF386A5472"
    }
}

HTTP Request

POST https://apiv2.unipay.com/custom/checkout/v1/createorder




Parameters

Value Type Description
Hash String Hash is calculated with secret key and all string parameters which are passed to function. You must not include in hash string parameters which are array or object, and must not include Hash parameter itself use a delimiter between each parameter
MerchantID Integer Merchant unique ID obtained from UniPAY system.
MerchantUser String Clients Identification Account in Merchant System
MerchantOrderID String Merchant Transaction Number
OrderPrice Float >= 0 The payment amount.
OrderCurrency String GEL - Georgian Lari
SuccessRedirectUrl String - Base64 Success redirect URL
CancelRedirectUrl String - Base64 Fail redirect URL
CallBackUrl String - Base64 URL provided by merchant to get transaction status after the payment
Languege String GE – Georgia, EN- English,
OrderName String A Title of the payment
OrderDescription String A description of the payment
OrderType string Pass "preauth" to activate pre authorisation function

CallBack

It is best practice for your project to receive POST a callback. We will send request on CallBackUrl parameter.

{
"MerchantOrderID": 51823,
"Status": 3,
"Hash": "808a827a928917e15e79b531227c5b1c81d6bf552b347aad9a91ed0e53a0b317",
"Amount": 20.00,
"UnipayOrderID": "MP50050176151C206A41D9",
"ErrorCode": 0,
"ErrorMessage": "OK",
"Reason": ""
}

Hash Calculation

Hash must be calculated based on SHA 256 based on following params + SecretKey provided by unipay.

Pre Authorization Confirm

Function gives an option to confirm the pre automation order with defined amount. you can cancel the order with amount 0 and full amount will be returned.

Endpoint URL: https://apiv2.unipay.com/custom/checkout/v1/confirm

POST /confirm

{
   "Hash": "e8364a4dd914a9fda43050d8321d7b8026a148d3ca581708c1441aa4fee06081",
   "MerchantID": "5005009000211",
   "OrderHashID": "MP5005009614DF386A5472",
   "Amount": 0.10
}

JSON Response Sample


{
    "errorcode": 0,
    "message": "OK",
    "data": {
        "UnipayOrderHashID": "MP5005009614DF386A5472"
    }
}

HTTP Request

POST https://apiv2.unipay.com/custom/checkout/v1/confirm



Parameters

Value Type Description
Hash String Hash is calculated with secret key and all string parameters which are passed to function. You must not include in hash string parameters which are array or object, and must not include Hash parameter itself use a delimiter between each parameter
MerchantID Integer Merchant unique ID obtained from UniPAY system.
OrderHashID String returned unipay order hash ID
Amount Float >= 0 Confirm amount.

CallBack

It is best practice for your project to receive POST a callback. We will send request on CallBackUrl parameter.

{
 "MerchantOrderID": 51823,
 "Status": 3,
 "Hash": "808a827a928917e15e79b531227c5b1c81d6bf552b347aad9a91ed0e53a0b317",
 "Amount": 20.00,
 "UnipayOrderID": "MP50050176151C206A41D9",
 "ErrorCode": 0,
 "ErrorMessage": "OK",
 "Reason": ""
}

Hash Calculation

Hash must be calculated based on SHA 256 based on following params + SecretKey provided by unipay.

Save Card

Endpoint URL: https://apiv2.unipay.com/custom/checkout/v1/createorder

POST /createorder

{
    "Hash": "5a35a2609b5a931ea81bc4b35fb5f4889d8863ae0c39743d809f70cbb1beb5d3",
    "MerchantID": "5005009000211",
    "MerchantUser": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
    "MerchantOrderID": "UN6141ab337e154-29",
    "OrderPrice": 40.59,
    "OrderCurrency": "GEL",
    "SuccessRedirectUrl": "aHR0cHM6Ly9zdWNjZXNzX3JlZGlyZWN0X3VybC51bmlwYXkuY29tLw==",
    "CancelRedirectUrl": "aHR0cHM6Ly9jYW5jZWxfcmVkaXJlY3RfdXJsLnVuaXBheS5jb20v",
    "CallBackUrl": "aHR0cDovL2luZm8udW5pcGF5LmNvbS8=",
    "Language": "GE",
    "OrderName": "StarWars Comics",
    "OrderDescription": "GHOSTS OF VADER’S CASTLE"
    "InApp": "1"

}

JSON Response Sample


{
    "errorcode": 0,
    "message": "OK",
    "data": {
        "Checkout": "{{CHECKOUT PAGE URL}}",
        "UnipayOrderHashID": "MP5005009614DF386A5472",
    }
}

HTTP Request

POST https://apiv2.unipay.com/custom/checkout/v1/createorder


You can Save card securly for future use to charge customer or build a subscription flows. we are providing two options. Save Card ( InApp) or Pay from already Saved Card (RegularPaymentID)



Parameters

Value Type Description
Hash String Hash is calculated with secret key and all string parameters which are passed to function. You must not include in hash string parameters which are array or object, and must not include Hash parameter itself use a delimiter between each parameter
MerchantID Integer Merchant unique ID obtained from UniPAY system.
MerchantUser String Clients Identification Account in Merchant System
MerchantOrderID String Merchant Transaction Number
OrderPrice Float >= 0 The payment amount.
OrderCurrency String GEL - Georgian Lari
SuccessRedirectUrl String - Base64 Success redirect URL
CancelRedirectUrl String - Base64 Fail redirect URL
CallBackUrl String - Base64 URL provided by merchant to get transaction status after the payment
Language String GE – Georgia, EN- English,
OrderName String A Title of the payment
OrderDescription String A description of the payment
InApp Integer Pass 1 to actviate Save card feature

CallBack

It is best practice for your project to receive POST a callback. We will send request on CallBackUrl parameter.

{
"MerchantOrderID": 51823,
"Status": 3,
"Hash": "808a827a928917e15e79b531227c5b1c81d6bf552b347aad9a91ed0e53a0b317",
"Amount": 20.00,
"CardNumber": "4 *** 6661",
"RegularPaymentID": "card_i7HQMtjp6SNFfJNo7MO3jMIbjcQNbXWk",
"UnipayOrderID": "MP50050176151C206A41D9",
"ErrorCode": 0,
"ErrorMessage": "OK",
"Reason": ""

}

Hash Calculation

Hash must be calculated based on SHA 256 based on following params + SecretKey provided by unipay.

Pay with SaveCard

Endpoint URL: https://apiv2.unipay.com/custom/checkout/v1/createorder

POST /createorder

{
    "Hash": "5a35a2609b5a931ea81bc4b35fb5f4889d8863ae0c39743d809f70cbb1beb5d3",
    "MerchantID": "5005009000211",
    "MerchantUser": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
    "MerchantOrderID": "UN6141ab337e154-29",
    "OrderPrice": 40.59,
    "OrderCurrency": "GEL",
    "SuccessRedirectUrl": "aHR0cHM6Ly9zdWNjZXNzX3JlZGlyZWN0X3VybC51bmlwYXkuY29tLw==",
    "CancelRedirectUrl": "aHR0cHM6Ly9jYW5jZWxfcmVkaXJlY3RfdXJsLnVuaXBheS5jb20v",
    "CallBackUrl": "aHR0cDovL2luZm8udW5pcGF5LmNvbS8=",
    "Language": "GE",
    "OrderName": "StarWars Comics",
    "OrderDescription": "GHOSTS OF VADER’S CASTLE"
    "RegularPaymentID": "card_i7HQMtjp6SNFfJNo7MO3jMIbjcQNbXWk"

}

JSON Response Sample


{
    "errorcode": 0,
    "message": "OK",
    "data": {
        "Checkout": "{{CHECKOUT PAGE URL}}",
        "UnipayOrderHashID": "MP5005009614DF386A5472",
    }
}

HTTP Request

POST https://apiv2.unipay.com/custom/checkout/v1/createorder


You can iniciate Payment from SavedCard securly. Use (RegularPaymentID) where you have to use a Saved Card Token.



Parameters

Value Type Description
Hash String Hash is calculated with secret key and all string parameters which are passed to function. You must not include in hash string parameters which are array or object, and must not include Hash parameter itself use a delimiter between each parameter
MerchantID Integer Merchant unique ID obtained from UniPAY system.
MerchantUser String Clients Identification Account in Merchant System
MerchantOrderID String Merchant Transaction Number
OrderPrice Float >= 0 The payment amount.
OrderCurrency String GEL - Georgian Lari
SuccessRedirectUrl String - Base64 Success redirect URL
CancelRedirectUrl String - Base64 Fail redirect URL
CallBackUrl String - Base64 URL provided by merchant to get transaction status after the payment
Language String GE – Georgia, EN- English,
OrderName String A Title of the payment
OrderDescription String A description of the payment
RegularPaymentID String After saving the Card with function InApp you are getting a Card Token from UniPAY.

CallBack

It is best practice for your project to receive POST a callback. We will send request on CallBackUrl parameter.

{
"MerchantOrderID": 51823,
"Status": 3,
"Hash": "808a827a928917e15e79b531227c5b1c81d6bf552b347aad9a91ed0e53a0b317",
"Amount": 20.00,
"CardNumber": "4 *** 6661",
"RegularPaymentID": "card_i7HQMtjp6SNFfJNo7MO3jMIbjcQNbXWk",
"UnipayOrderID": "MP50050176151C206A41D9",
"ErrorCode": 0,
"ErrorMessage": "OK",
"Reason": ""

}

Hash Calculation

Hash must be calculated based on SHA 256 based on following params + SecretKey provided by unipay.

Get Saved Card

Endpoint URL: https://apiv2.unipay.com/custom/checkout/v1/get-card

POST /get-card

{
"Hash": "2fa5a80a3693fcee49569adc75e8a6f82a332287b9d9bf669bf037b7f3918aa4",
"MerchantID": "5005009001821",
"RegularpaymentID": "card_CsnWLhpUNEIk8LABukuqFvly7PY3ldoS"
}

JSON Response Sample


{
"errorcode": 0,
"message": "OK",
"data": {
"recurrent_card": {
"card_hash": "card_CsnWLhpUNEIk8LABurtqFvly7PY3ldoS",
"card_number": "4 *** 6631",
"card_expire_year": "2025",
"card_expire_month": "10",
"card_brand": "VISA"
}

HTTP Request

`POST /get-card


You can get list of Saved Cards.



CallBack

It is best practice for your project to receive POST a callback. We will send request on CallBackUrl parameter.

Hash Calculation

Hash must be calculated based on SHA 256 based on following params + SecretKey provided by unipay.

Status List

Code Name Description
1 PROCESS Payment is under process
2 HOLD Payment was hold
3 SUCCESS Payment is successful
5 REFUNDED Payment was refunded
13 FAILED Payment failed due to some errors
19 PARTIAL_REFUNDED was initiated a partial refund
22 INCOMPLETE_BANK Payment timeout
23 INCOMPLETE Payment is incomplete
1000 CREATED Payment was created
1001 PROCESSING Payment is processing and waiting to get update status

Error List

Code Description
0 OK
403 HTTP_AUTORIZATION_MERCHANT_ID_WRONG
402 HTTP_AUTORIZATION_MERCHANT_NOT_DEFINED
401 HTTP_AUTORIZATION_HASH_WRONG
101 ERROR_MERCHANT_IS_DISABLED
102 ERROR_MERCHANT_ID_NOT_DEFINED
103 ERROR_MERCHANT_ORDER_ID_NOT_DEFINED
104 ERROR_ORDER_PRICE_NOT_DEFINED
105 ERROR_ORDER_CURRENCY_NOT_DEFINED
106 ERROR_ORDER_CURRENCY_BAT_FORMAT
107 ERROR_LANGUAGE_BAD_FORMAT
108 ERROR_MIN_AMOUNT
109 ERROR_MAX_AMOUNT
110 ERROR_HASH
111 ERROR_BAD_FORMAT_OF_BACKLINKS
112 ERROR_BAD_FORMAT_OF_LOGO
113 ERROR_BAD_OF_ITEM_IN_LIST
116 ERROR_CARD_NOT_FOUND
117 ERROR_CHECKOUT_DEACTIVATED
118 ERROR_CHECKOUT_DOMAIN_NOT_RESOLVED
119 ERROR_PLATFORM_NOT_EXISTS
120 ERROR_CALLBACK_IS_EMPTY
121 ERROR_REQUEST_DATA_IS_EMPTY
122 ERROR_REASON_IS_EMPTY
123 ERROR_ORDER_NOT_FOUND
124 ERROR_CARD_TOKEN_IS_EMPTY
125 ERROR_MERCHANT_IS_REJECTED
126 ERROR_CURRENCY_IS_OUT_OF_DATE
127 ERROR_CURRENCY_IS_NOT_CONFIGURED
128 ERROR_PAYMENT_TYPE_IS_NOT_CORRECT
129 ERROR_PAYMENT_CHANNEL_NOT_FOUND
130 ERROR_RECURRING_OPTION_TURNED_OFF
140 INSUFFICIENT_FUNDS
141 AMOUNT_LIMIT_EXCEEDED
142 FREQUENCY_LIMIT_EXCEEDED
143 CARD_NOR_EFFECTIVE
144 CARD_EXPIRED
145 CARD_LOST
146 CARD_STOLEN
147 CARD_RESTRICTED
148 DECLINED_BY_ISSUER
149 BANK_SYSTEM_ERROR
150 UNKNOWN
151 AUTHENTICATION_FAILED
152 OFFER_TIMEOUT

Not-Code Options

E-Commerce Platforms
1. WIX
2. Shopify
3. Ecwid
4. Woocommerce
5. Wordpress
6. Unishop
7. Desk
8. OpenCart
9. CS Cart
10. NopCommerce
11. Magento
12. Tilda
13. PrestaShop
14. Virtuemart
15. WHCSM

Not using APIs?

We've partnered with many popular e-commerce platforms so you can get up and running quickly, processing online payments with one of our e-commerce plugins.

it si very easy to integrate using ready integrations, You just need to download unipay checkout plugin for specific e commerce platform, enter your merchant id and API KEY and you are ready to start accepting the payments.







<unipay />