Installment Payments EcommerceConnect - UPC · Ecommerce gateway secure page interface OrderID L Ans… î Order number up to 20 byte . Installment Payments EcommerceConnect _____

Installment Payments EcommerceConnect _______________________________________________________________________________________

1

Acquiring

Installment Payments

EcommerceConnect

Version 1.0

Kyiv, 2018


2

Contents

Purpose ............................................................................................................................................................................. 3

Installment Payments Activation for Merchant ................................................................................................................ 4

The format and description of the elements .................................................................................................................... 5

Payment request description ............................................................................................................................................ 7

Merchant Notification about Installment Payments ...................................................................................................... 10

Status Request ................................................................................................................................................................ 13


3

Purpose

The purpose of the Document is to describe the Installment Payments service integration by the Ecommerce system developers.

In order to start the process, the Acquirer should receive per each merchant the following data from Ukrainian Processing Center:

- Merchant_id

-Terminal_id

- Ecommerce Connect payment gateway certificate

- Access to the Merchant Administrative Interface


4

Installment Payments Service Activation for Merchant

The activation of Installment Payments is enabled by Ukrainian processing center.

1. Merchant sends a request to activate the option and indicates Merchant_Id. The request should be sent to [email protected]

2. Acquiring Bank sets the threshold amount (in transaction currency) and in case it is exceeded, the installment confirmation

flag will be sent in the authorization request to the Issuer.

For instance, an Acquirer sets 100 UAH threshold amount. That would mean that all transactions below 100 UAH are

sent as ordinary purchase transactions to an Issuer. Whereas the transaction amount is above 100 UAH, like 101 UAH, the

transaction will get the parameter that can be recognized by the Issuer. In case if installment is available for the cardholder, the

Issuer will send back the Installment plan that will be shown on the merchant payment page.

3. After Installment Payments option activation by Ukrainian processing center, the Merchant via the Merchant Administrative

Interface sets the «yes» at «Installment plan sending by Notify» field. Other fields should not be changed.

If “yes” is chosen at «Installment plan sending by Notify» field, it means that the merchant will receive the notifications when

good or services are paid using the Installment option at the merchant page.

4. The Merchant initiates a standard payment request

mailto:[email protected]


5

The format and description of the elements

Parameter Structure Format Parameter name (assignment) Description

Version F N SG Interface version value Interaction protocol version. Currently Version ‘1’ is in use. This parameter is referential to process gateway’s incoming data.

MerchantID L an15 Merchant identifier Is appointed by the Acquirer

TerminalID F an8 Terminal identifier -- // --

TotalAmount F N1..12 Order amount In minimal currency units (kopeks, cents)

Currency F n3 Currency Is defined by the Bank that provides the service

AltTotalAmount (O)

F N1..12 Order amount (alternative currency) Optional parameter In minimal currency units (kopeks, cents)

AltCurrency (O) F n3 Alternative currency Is defined if the Merchant wants to display the transaction amount in another currency.

PurchaseTime F n12..17 Request time in format yyMMddHHmmss or yyMMddHHmmssZ

yy - year MM - month in year dd - day in month HH - hour in day (0-23) mm - minute in hour ss - second in minute Z - time zone (RFC 822) Zone format - [+|-] Hours Minutes Example +0300 , -0200 If there is no zone indicated in the parameter, it is considered to be same as the gateway has.

locale F a2 Interface language (en;ru;uk;hr;fr;de;sq;rs;it;hu;ro;pl;sk;cz;sl)

The language of the Ecommerce gateway secure page interface

OrderID L Ans…20 Order number up to 20 byte


6

Parameter Structure Format Parameter name (assignment) Description

SD (O) Var an...99 Session Data –data of the session Axillary parameter. Can be used by the system to manage users’ sessions

PurchaseDesc (О)

L ans...1 25 Short description of the order: service or goods

Axillary parameter of 3-D Secure specification. Can be displayed on the payment server page. Is recommended to be used for the customer’s convenience.

Signature Var Scheme dependent

MAC- code or signature value The length of the parameter depends on the chosen calculation scheme


7

Payment request description

Example:

<form action="https://ecg.test.upc.ua/rbi/enter" method="POST">

<meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<input name="Version" type="hidden" value="1" />

<input name="MerchantID" type="hidden" value="1111111" />

<input name="TerminalID" type="hidden" value="E1111111" />

<input name="TotalAmount" type="hidden" value="1000" />

<input name="Currency" type="hidden" value="980" />

<input name="locale" type="hidden" value="ru" />

<INPUT TYPE="HIDDEN" NAME="PurchaseTime" VALUE="150611110821"/>

<input name="OrderID" type="hidden" value="121sdsdss2sd" />

<input name="PurchaseDesc" type="hidden" value="tran test" />

<input name="Signature" type="hidden" value=""/>

<input type="submit"/>

</form>

After the payment confirmation request is sent, the payment page is shown to enter the payment card data:


8

After the card data entry, the client is given a possibility to complete the payment using Installments option. The “Payment

option” field shows the corresponding options.

This page shows the information about the Installment Payment, so the customer can choose the installment plan and confirm

the payment.


9

If the customer choses to Pay in Full, the customer will be given a possibility to complete the payment without Installments.


10

Merchant Notification about Installment Payments

In this case the Merchant via the Merchant Administrative Interface sets «yes» at «Installment plan sending by Notify» field,

the transaction processing result and installment plan is sent via HTTP/HTTPS POST by the Ecommerce gateway to the

Merchant page.

Notify request message:

Installment = '{"type":21,"paymentOption":"B","options":[{"number":2,"interestRate":12345,"fee":127777777777,"annualPerce

ntageRate":55555,"firstAmount":123333333333,"subsequentAmount":121212121212,"totalAmountDue":252525252525},{"nu

mber":22,"interestRate":12345,"fee":123451242222,"annualPercentageRate":78787,"firstAmount":636363663633,"subsequent

Amount":787878787777,"totalAmountDue":787878787877},{"number":77,"interestRate":78787,"fee":787878787777,"annualP

ercentageRate":45455,"firstAmount":454555555555,"subsequentAmount":496969696699,"totalAmountDue":898989898989},{

"number":88,"interestRate":44444,"fee":111111111111,"annualPercentageRate":12122,"firstAmount":777777777777,"subsequ

entAmount":888888888888,"totalAmountDue":666666666666},{"number":55,"interestRate":88888,"fee":757585858555,"annu

alPercentageRate":33333,"firstAmount":636363333333,"subsequentAmount":111111111111,"totalAmountDue":363636363636

},{"number":85,"interestRate":47474,"fee":858585888888,"annualPercentageRate":66666,"firstAmount":889898989999,"subse

quentAmount":858585858588,"totalAmountDue":969696969696},{"number":25,"interestRate":25252,"fee":858585858588,"an

nualPercentageRate":36636,"firstAmount":636363633365,"subsequentAmount":123333333333,"totalAmountDue":123333333

333},{"number":22,"interestRate":55555,"fee":123333333333,"annualPercentageRate":43434,"firstAmount":123333333333,"su

bsequentAmount":123333333333,"totalAmountDue":123333333333},{"number":22,"interestRate":12355,"fee":123333333333,

"annualPercentageRate":12333,"firstAmount":123333333333,"subsequentAmount":123333333333,"totalAmountDue":1233333

33333},{"number":11,"interestRate":12335,"fee":123333333333,"annualPercentageRate":12333,"firstAmount":123333333333,"

subsequentAmount":123333333333,"totalAmountDue":123333333333},{"number":44,"interestRate":33333,"fee":12333333333

3,"annualPercentageRate":12333,"firstAmount":123333333333,"subsequentAmount":123333333333,"totalAmountDue":12333

3333333},{"number":22,"interestRate":33333,"fee":123333333333,"annualPercentageRate":12333,"firstAmount":12333333333

3,"subsequentAmount":123333333333,"totalAmountDue":123333333333}],"receipt":"666666666666666666666666666666666


11

6666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666

6666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666

6666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666

6666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666

6666666666666666666666666666666666666666666666666666666666666666666"}'

Email = '[email protected]'

TranCode = '602'

MerchantID = '1754971'

TotalAmount = '15000'

OrderID = '844477'

ApprovalCode = '423488'

ProxyPan = '555949******0023'

Delay = '0'

Rrn = '825415352694'

PurchaseTime = '180907113626'

SD = ''

XID = '18091115-278639'

Currency = '980'

Signature = 'null'

TerminalID = 'E7882971'

The Merchant sends response in the page code. Each parameter and its value like Parameter=Value are available in the new line.

The lines are divided by the line separator symbol.

The response in addition to the original parameters values (MerchantID, TerminalID, OrderID, Currency, TotalAmount, XID,

PurchaseTime) has 3 new parameters Response.action, Response.reason, Response.forwardUrl

Parameter Value Description

Response.action approve | reverse In case of ‘approve’ value, the Merchant approves operation success. In case of ‘reverse’ value, the gateway cancels the successful transaction and sets the completion value 503 – «Transaction canceled by the Merchant»

Response.reason An.. 255 Explanations of the Merchant response (optional), like the reason for value Response.action

Response.forwardUrl An.. 255 URL value to redirect user’s browser, instead of SUCCESS_URL or FAILURE_URL (there is a possibility to use dynamic links)


12

Example:

echo "MerchantID="1752493"\n";

echo "TerminalID="E7880293"\n";

echo "OrderID="ID0009992"\n";

echo "Currency="980"\n";

echo "TotalAmount="980"\n";

echo "XID="333333-4444444"\n";

echo "PurchaseTime="090929152500"\n";

echo "Response.action="\n";

echo "Response.reason="\n";

echo "Response.forwardUrl="\n";

In case the Merchant doesn’t receive the callback or doesn't know about the transaction result, transaction status

(Status Request), request should be sent. After that the decision should be taken about transaction reverse or service decline.

In this case the Merchant has set «yes» at «Installment plan sending by Notify» field at the Merchant Administrative Interface,

the Merchant gets a possibility to extend the reversal sending period up to 60 days.


13

Status Request

All data is transferred to в Base64URL Encode, https://simplycalc.com/ can be used for encryption.

The creation of json object is in accordance to the rfc7515 standard.

JWS Algorithm (https://tools.ietf.org/html/rfc7515#page-10)

Creation of json object

header => {"alg":"RS256"}

payload creation data are taken from the original transaction

payload =>

{"merchantId":"1752739","terminalId":"E7880539","totalAmount":50000,"currency":"980","orderId":"poip1","purchaseTime":"

20151123153333"}

transferred to Base64URL Encode

and signature made based on the received data.

Transferred to Base64URL header

eyJhbGciOiJSUzI1NiJ9

Transferred to Base64URL payload

eyJtZXJjaGFudElkIjoiMTc1MjczOSIsInRlcm1pbmFsSWQiOiJFNzg4MDUzOSIsInRvdGFsQW1vdW50Ijo1MDAwMCwiY3VycmVuY3ki

OiI5ODAiLCJvcmRlcklkIjoicG9pcDEiLCJwdXJjaGFzZVRpbWUiOiIyMDE1MTEyMzE1MzMzMyJ9

Preparation of signature=”header”.”payload”

eyJhbGciOiJSUzI1NiJ9.eyJtZXJjaGFudElkIjoiMTc1MjczOSIsInRlcm1pbmFsSWQiOiJFNzg4MDUzOSIsInRvdGFsQW1vdW50Ijo1MDA

wMCwiY3VycmVuY3kiOiI5ODAiLCJvcmRlcklkIjoicG9pcDEiLCJwdXJjaGFzZVRpbWUiOiIyMDE1MTEyMzE1MzMzMyJ9

Based on openssl

openssl dgst -sha256 -sign %1 datafile1 > signature.bin

and transformed to

openssl base64 -e -in signature. -out signature

signature= HFGe2v7Zv+RJF+Vv2rPV5A3PAVRQkjI8HUxWdIRX4aKLH0y67sITqMFPFfEBaotF

DVWTYsHQywrHLygiiBZ48K7cQJ9NbNrkzV6QnB5Q7tWna/tQTK2kpSmPQDrlKg+H

6vysPTeOsTFbvMR779nDQ/R7o1GLcNn+LieRaK0qIf9MQKO747r5xLck6pIAF4mS

edyakI92fgFuBL/DIyq2ATMogCFijLIWwIEmf11D+UblDpfgTKgH4sCYYLwUKMCl

uJhQt06qL5QhyiZpVdLMK+z42SOHWKq5zEz50I1ABuaULiY+KOPJIhaRVuiNWbYB

daJf9LXP3Uj3DDHg5+gXIA==

json request creation to https://ecg.test.upc.ua/go/service/01

{“header”:” eyJhbGciOiJSUzI1NiJ9”,

https://simplycalc.com/

https://ecg.test.upc.ua/go/service/01


14

“payload”:”eyJtZXJjaGFudElkIjoiMTc1MjczOSIsInRlcm1pbmFsSWQiOiJFNzg4MDUzOSIsInRvdGFsQW1vdW50Ijo1MDAwMCwiY3V

ycmVuY3kiOiI5ODAiLCJvcmRlcklkIjoicG9pcDEiLCJwdXJjaGFzZVRpbWUiOiIyMDE1MTEyMzE1MzMzMyJ9”,

Signature:”HFGe2v7Zv+RJF+Vv2rPV5A3PAVRQkjI8HUxWdIRX4aKLH0y67sITqMFPFfEBaotF

DVWTYsHQywrHLygiiBZ48K7cQJ9NbNrkzV6QnB5Q7tWna/tQTK2kpSmPQDrlKg+H

6vysPTeOsTFbvMR779nDQ/R7o1GLcNn+LieRaK0qIf9MQKO747r5xLck6pIAF4mS

edyakI92fgFuBL/DIyq2ATMogCFijLIWwIEmf11D+UblDpfgTKgH4sCYYLwUKMCl

uJhQt06qL5QhyiZpVdLMK+z42SOHWKq5zEz50I1ABuaULiY+KOPJIhaRVuiNWbYB

daJf9LXP3Uj3DDHg5+gXIA==”}

Received json response to decode

eyJyZXN1bHRzIjpbeyJ0cmFuQ29kZSI6IjYwMiIsImFwcHJvdmFsQ29kZSI6Ijc5ODU0NCIsInJybiI6ODI1NzA5MzUxOTE3LCJjb21tZW50I

joiV2FpdGluZyBjb25maXJtYXRpb24gb2YgaW5zdGFsbWVudCIsImNhcmROdW1NYXNrZWQiOiI1NDA5NTMqKioqKiowMDAyIiwidH

JhblRpbWUiOiIyMDE4LTA5LTE0IDA5OjIwOjE0LjQxOCIsImFtb3VudCI6MTUwMDAwMCwiY3VycmVuY3kiOjk4MCwib3BlclR5cGUiO

iJQVVJDSEFTRSIsImFjdGlvbkNvZGUiOiIwMDAiLCJpbnN0YWxsbWVudERhdGEiOnsidHlwZSI6MjAsInBheW1lbnRPcHRpb24iOiJCIiwi

b3B0aW9uIjp7Im1pbk51bWJlciI6NSwibWF4TnVtYmVyIjoxMCwiaW50ZXJlc3RSYXRlIjoxNTIsImZlZSI6MzQ2LCJhbm51YWxQZXJjZW

50YWdlUmF0ZSI6MTgyNCwidG90YWxBbW91bnREdWUiOjIyMzkyfSwicmVjZWlwdCI6IlNvbWUgdGV4dCJ9fSx7InRyYW5Db2RlIjoi

MDAwIiwiYXBwcm92YWxDb2RlIjoiNTM1NzYwIiwicnJuIjo4MjU3MDkzNTE5MTcsImNvbW1lbnQiOiJBcHByb3ZlZCIsImNhcmROdW

1NYXNrZWQiOiI1NDA5NTMqKioqKiowMDAyIiwidHJhblRpbWUiOiIyMDE4LTA5LTE0IDA5OjI3OjQwLjE5MSIsImFtb3VudCI6MTUw

MDAwMCwiY3VycmVuY3kiOjk4MCwib3BlclR5cGUiOiJSRVZFUlNBTCIsImFjdGlvbkNvZGUiOiIwMDAiLCJpbnN0YWxsbWVudERhdG

EiOnsidHlwZSI6MjAsInBheW1lbnRPcHRpb24iOiJCIiwib3B0aW9uIjp7Im1pbk51bWJlciI6NSwibWF4TnVtYmVyIjoxMCwiaW50ZXJlc3

RSYXRlIjoxNTIsImZlZSI6MzQ2LCJhbm51YWxQZXJjZW50YWdlUmF0ZSI6MTgyNCwidG90YWxBbW91bnREdWUiOjIyMzkyfSwicmVjZ

WlwdCI6IlNvbWUgdGV4dCJ9fV19

Example: canceled transaction result

{"results":[{"tranCode":"602","approvalCode":"798544","rrn":825709351917,"comment":"Waiting confirmation of

instalment","cardNumMasked":"540953******0002","tranTime":"2018-09-14

09:20:14.418","amount":1500000,"currency":980,"operType":"PURCHASE","actionCode":"000","installmentData":{"type":20,"p

aymentOption":"B","option":{"minNumber":5,"maxNumber":10,"interestRate":152,"fee":346,"annualPercentageRate":1824,"to

talAmountDue":22392},"receipt":"Some

text"}},{"tranCode":"000","approvalCode":"535760","rrn":825709351917,"comment":"Approved","cardNumMasked":"540953*

*****0002","tranTime":"2018-09-14

09:27:40.191","amount":1500000,"currency":980,"operType":"REVERSAL","actionCode":"000","installmentData":{"type":20,"pa

ymentOption":"B","option":{"minNumber":5,"maxNumber":10,"interestRate":152,"fee":346,"annualPercentageRate":1824,"tot

alAmountDue":22392},"receipt":"Some text"}}]}

Example: successful payment with the installment plan

{"results":[{"tranCode":"000","approvalCode":"417768","rrn":825617351845,"comment":"Approved","cardNumMasked":"5409

53******0002","tranTime":"2018-09-13


aymentOption":"B","option":{"minNumber":5,"maxNumber":10,"interestRate":152,"fee":346,"annualPercentageRate":1824,"to

talAmountDue":22392},"receipt":"Some text","selectedNumber":5}}

Example: successful payment canceled by the Merchant


15

{"results":[{"tranCode":"503","approvalCode":"218258","rrn":825709353551,"comment":"Transaction was canceled by

merchant","cardNumMasked":"516053******5703","tranTime":"2018-09-14


aymentOption":"B","options":[{"number":2,"interestRate":12345,"fee":127777777777,"annualPercentageRate":55555,"firstAm

ount":123333333333,"subsequentAmount":121212121212,"totalAmountDue":252525252525},{"number":22,"interestRate":12

345,"fee":123451242222,"annualPercentageRate":78787,"firstAmount":636363663633,"subsequentAmount":787878787777,"t

otalAmountDue":787878787877},{"number":77,"interestRate":78787,"fee":787878787777,"annualPercentageRate":45455,"first

Amount":454555555555,"subsequentAmount":496969696699,"totalAmountDue":898989898989},{"number":88,"interestRate":

44444,"fee":111111111111,"annualPercentageRate":12122,"firstAmount":777777777777,"subsequentAmount":888888888888,

"totalAmountDue":666666666666},{"number":55,"interestRate":88888,"fee":757585858555,"annualPercentageRate":33333,"fi

rstAmount":636363333333,"subsequentAmount":111111111111,"totalAmountDue":363636363636},{"number":85,"interestRat

e":47474,"fee":858585888888,"annualPercentageRate":66666,"firstAmount":889898989999,"subsequentAmount":8585858585

88,"totalAmountDue":969696969696},{"number":25,"interestRate":25252,"fee":858585858588,"annualPercentageRate":36636,

"firstAmount":636363633365,"subsequentAmount":123333333333,"totalAmountDue":123333333333},{"number":22,"interestR

ate":55555,"fee":123333333333,"annualPercentageRate":43434,"firstAmount":123333333333,"subsequentAmount":12333333

3333,"totalAmountDue":123333333333},{"number":22,"interestRate":12355,"fee":123333333333,"annualPercentageRate":123

33,"firstAmount":123333333333,"subsequentAmount":123333333333,"totalAmountDue":123333333333},{"number":11,"intere

stRate":12335,"fee":123333333333,"annualPercentageRate":12333,"firstAmount":123333333333,"subsequentAmount":123333


2333,"firstAmount":123333333333,"subsequentAmount":123333333333,"totalAmountDue":123333333333},{"number":22,"int

erestRate":33333,"fee":123333333333,"annualPercentageRate":12333,"firstAmount":123333333333,"subsequentAmount":123

333333333,"totalAmountDue":123333333333}],"receipt":"6666666666666666666666666666666666666666666666666666666

6666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666

6666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666

6666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666

6666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666

666666666666666666666666666666666666666666666"}},{"tranCode":"000","approvalCode":"539321","rrn":825709353551,"c

omment":"Approved","cardNumMasked":"516053******5703","tranTime":"2018-09-14

09:50:44.631","amount":1500000,"currency":980,"operType":"REVERSAL","actionCode":"000","installmentData":{"type":21,"pa

ymentOption":"B","options":[{"number":2,"interestRate":12345,"fee":127777777777,"annualPercentageRate":55555,"firstAmo

unt":123333333333,"subsequentAmount":121212121212,"totalAmountDue":252525252525},{"number":22,"interestRate":123

45,"fee":123451242222,"annualPercentageRate":78787,"firstAmount":636363663633,"subsequentAmount":787878787777,"to

talAmountDue":787878787877},{"number":77,"interestRate":78787,"fee":787878787777,"annualPercentageRate":45455,"first

Amount":454555555555,"subsequentAmount":496969696699,"totalAmountDue":898989898989},{"number":88,"interestRate":

44444,"fee":111111111111,"annualPercentageRate":12122,"firstAmount":777777777777,"subsequentAmount":888888888888,

"totalAmountDue":666666666666},{"number":55,"interestRate":88888,"fee":757585858555,"annualPercentageRate":33333,"fi

rstAmount":636363333333,"subsequentAmount":111111111111,"totalAmountDue":363636363636},{"number":85,"interestRat

e":47474,"fee":858585888888,"annualPercentageRate":66666,"firstAmount":889898989999,"subsequentAmount":8585858585

88,"totalAmountDue":969696969696},{"number":25,"interestRate":25252,"fee":858585858588,"annualPercentageRate":36636,

"firstAmount":636363633365,"subsequentAmount":123333333333,"totalAmountDue":123333333333},{"number":22,"interestR

ate":55555,"fee":123333333333,"annualPercentageRate":43434,"firstAmount":123333333333,"subsequentAmount":12333333


33,"firstAmount":123333333333,"subsequentAmount":123333333333,"totalAmountDue":123333333333},{"number":11,"intere

stRate":12335,"fee":123333333333,"annualPercentageRate":12333,"firstAmount":123333333333,"subsequentAmount":123333


2333,"firstAmount":123333333333,"subsequentAmount":123333333333,"totalAmountDue":123333333333},{"number":22,"int

erestRate":33333,"fee":123333333333,"annualPercentageRate":12333,"firstAmount":123333333333,"subsequentAmount":123

333333333,"totalAmountDue":123333333333}],"receipt":"6666666666666666666666666666666666666666666666666666666

6666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666

6666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666

6666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666

6666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666

666666666666666666666666666666666666666666666"}}]

Documents

Installment Payments EcommerceConnect - UPC · Ecommerce gateway secure page interface OrderID L Ans… î Order number up to 20 byte . Installment Payments EcommerceConnect _____