Introduction

CHECKOUT Rest API v1

This document is intended to provide the partner with a comprehensive guide how to integrate Checkout Solution for accepting payments from UniPAY Wallet and Banking 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.

Integrating with UniPAY systems allows you to implement a solution that will fit your business characteristics and even increase your income. You can even design your very own model and use our API to accept payments in a manner that suits you best. UniPAY checkout solution provides you to accept VISA, MASTERCARD and AMEX cards from Georgian Customers along with UniPAY ewallets and also Cruptocurrency such as Bitcoins , Litecoins and Dogecoins.

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

SandBox credentials

Each partner has unique user account for development.

During the integration partner will be presented as a test user, after the integration, system account will be redirected into production mode and merchant can accept transactions from payment system.

Test Credentials
MerchatID 7507231
SecretKey 80BB6BD4-F996-4B03-8E05-C8DCA7B95DC1

Workflow



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

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

2) The client selects goods or services, or enters the amount for purchase and submits the form.

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

4) The client gets redirected to the UniPAY checkout site.

5) The UniPAY site authenticates both the merchant and the received values by calculating the MD5 checksum from the received values and the secret part, and comparing the resulting value against the received checksum.

6) Given that the merchant and their parameters are authenticated successfully, the client logs in the checkout site and get his available balance to finish the order.

7) The client chooses one of their UniPAY payment types to make a payment. (VISA, AMEX, BITCOIN )

8) The Client confirms the transaction.

9) When the transaction is initiated, client is notified by the system about the status of the payment. User also has two buttons: Go to transactions or to go back into merchant’s page.

Authentication

Example of password generation


# request example json params

json = {
  "MerchantUser": "000962",
  "MerchantOrderID": "123456789",
  "OrderPrice": "1499",
  "OrderName": "Service Order",
   "User": [
      "name" : "Bill",
      "surname" : "Jobs"
  ]
}

MerchantID = "xxxxxxxx";
SecretKey = "xxxxxxxx";

# dont forget not to include in string arrays and objects
# dont include {User} because it is a object
PasswordStr = "{SecretKey}|{MerchantUser}|{MerchantOrderID}|{OrderPrice}|{OrderName}";

Username = MerchantID;
Password = md5( PasswordStr  );

#send request with HTTP basic autorization

HTTP Request Based on Basic Authentication

You must provide Username and Password, Password is unique per request and generated by the SecretKey and body arguments using delimiter | and md5() hash


right you can see example of generationg password

Create Order

POST Request with JSON (RAW) BODY

{
  "MerchantID": "7507231",
  "MerchantUser": "000962",
  "MerchantOrderID": "123456789",
  "OrderPrice": "1499",
  "OrderCurrency":"GEL",
  "OrderName": "Buy Movie Ticket",
  "OrderDescription": "Star Wars: Episode VII The Force Awakens...",
  "BackLink": "aHR0cHM6Ly93d3cudW5pcGF5LmNvbS9lbi8=",
  "Mlogo": "aHR0cHM6Ly93d3cudW5pcGF5LmNvbS8vdGVtcGxhdGVzL3VuaXBheS9pbWFnZXMvbG9nby5wbmc=",
  "Mslogan": "company slogan",
  "Language": "GE",
  "Hash": "5c63be751937454cd320792e04d57c24"
}

JSON Response


{
  “Errorcode: 0,
  “Message: "ok",
  “Data: {
  “Checkout: "https:// checkout.serviceurl.com/checkout?id=598366",
  “UnipayOrderHashID: "MP75072311216D48D1"
}

HTTP Request

POST https://api.unipay.com/checkout/createorder


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

Hash Calculation Hash = md5 ( Secret_key | param1 | param2 | papram3 | param4 | ……. | …. |) 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 “|”

Service Based Orders

{   
  "OrderPrice": "1499",
  "OrderCurrency":"GEL",
  "OrderName": "Buy Movie Ticket",
  "OrderDescription": "Star Wars: Episode VII The Force Awakens...",
  "Mslogan": "company slogan"
}

example for service based orders on checkout page.

Item Based Orders

{   
  "OrderPrice": "300",
  "OrderCurrency": "GEL",
    "Items": [
    "100|2|title1|description1",
    "200|3|title2|description2",
    "300|9|title3|description3"
  ]
}

example for Item based orders on checkout page.

Parameters

Price are in Tetris 1 GEL=100 Tetri

Type Value Description
Int MerchantID Merchant unique ID obtained from UniPAY system.
String MerchantUser Clients Identification Account in Merchant System
String MerchantOrderID Merchant Transaction Number
Int OrderPrice Order Total Price in Tetri’s
Int Discount Order Discount Amount Price in Tetri’s
Int Shipping Order Shipping Amount Price in Tetri’s
String OrderCurrency GEL, USD, EUR Defoult currency is Georgian Lari
String OrderName Test Order Name
String OrderDescription Test Order Description
Info []Items List of Products, Items are passed as string with delimiters
String BackLink Merchant Back Link URL encoded in based64
String Mlogo Merchant’s Logo URL URL encoded in based64
String Mslogan Merchant’s Slogan TEXT Some Simple Site Slogan
String Language GE – Georgia, EN- English,
String Hash Checksum

Transactions

POST Request with JSON (RAW) BODY

{
  "MerchantID": "7507231",
  "Hash": "62a2dd240c14a091ae8afd23a1426345",
  "TransactionID" : "MP750723112168038B"
}

JSON Response


{
  "Errorcode": 0,
  "Message": "ok",
  "Data": {
    "Status": "PENDING",
    "MerchantOrderID": ""
  }
}

HTTP Request

POST https://api.unipay.com/checkout/transaction


With this method You can retrive transaction and check status

Callback

Simple PHP code


$Hash = $_GET['Hash'];

$UnipayOrderID = $_GET['UnipayOrderID'];

$MerchantOrderID= $_GET['MerchantOrderID'];

$Status= $_GET['Status'];

$Reason= $_GET['Reason'];

$CalculateHash = $UnipayOrderID.'|'.$MerchantOrderID.'|'.$Status.'|'.$SecretKey;

$CalculateHash = md5( $CalculateHash );

if( $Hash != $CalculateHash ){
     throw new Exception( 'this_is_not_unipay_response' 500 );
}

# do some work ...

HTTP Callback Request

POST https://merchantsCallbackService


Merchant must provide some service url based on we will send payment information and Hash

Merchant must check Hash to be sure that this is a UniPAY callback request,

Right you can see simple code to check hash and return HTTP 200 OK

Status List

Name Description
PENDING
PROCESS
ON_HOLD
COMPLETED
CANCELED
NOT_FINISHED
SAVED
PREPARED
CLEARED
DENIED
EXPIRED
FAILED
REFUNDED
DECLINED
RETURNED

Errors

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

Regular payment flow

With this method you can initialize transaction on merchants system. for regular payment you need pass inapp additional parameter, the minimal request parameters are:

POST Request

{
  "MerchantID": "7507231",
  "MerchantUser": "000962",
  "MerchantOrderID": "123456789",
  "OrderPrice": "100",
  "OrderName": "Buy Movie Ticket",
  "OrderDescription": "Star Wars: Episode VII The Force Awakens...",
  "BackLink": "aHR0cHM6Ly93d3cudW5pcGF5LmNvbS9lbi8=",
  "inapp": 1
}

Success Response example:

{
  "Errorcode": 0,
  "Message": "ok",
  "Data": {
    "Checkout": "https:// checkout.serviceurl.com/checkout?id=598366",
    "UnipayOrderHashID": "MP75072311216D48D1"
}

Error response will be

{
  "Errorcode": 500,
  "Message": "SOME_ERROR_MESSAGE",
}

You need to take Checkout field and make redirect to it. After payment UniPAY server will notify you about payment details, with POST method:

Callback request parameters:

{
  "UnipayOrderID": 0,
  "MerchantOrderID": '',
  "Status": '',
  "Hash": '',
  "Amount": '',
  "CardNumber": '4545******4545',
  "RegularpaymentID": '45654356',
  "Payment": 0,
  "UnipayOrderHashID": 'MP334534534534',
  "Reason": '',
}

You need to save RegularpaymentID for regular payments. After this flow you can make payment without redirecting, request is as simple as:

{
  "MerchantID": "7507231",
  "MerchantUser": "000962",
  "MerchantOrderID": "123456789",
  "OrderPrice": "100",
  "OrderName": "Buy Movie Ticket",
  "OrderDescription": "Star Wars: Episode VII The Force Awakens...",
  "BackLink": "aHR0cHM6Ly93d3cudW5pcGF5LmNvbS9lbi8=",
  "inapp": 1,
  "RegularpaymentID": '645654645343636'
}

And success response will be

{
  "Errorcode": 0,
  "Message": "ok",
  "Data": {
    "UnipayOrderHashID": "MP75072311216D48D1"
  }
}

Error response will be

{
  "Errorcode": 500,
  "Message": "SOME_ERROR_MESSAGE",
}