Interworking with TiPay Plugin

Sometimes users want to buy content or services online. TiPay plugin facilitates incorporation of payment mechanisms into services. TiPay stand for Telephone Initiated Payment. The plugin conceals from the service developer a whole lot of routine procedures of JSON TiPay API low-level interworking as well as user registration and setting a payment PIN. From the service developer's perspective the process of payment consists of the following steps, when TiPay is in use:

1. The service composes a payment link containing the purchase details, using which the user starts the payment process. The link can be associated with a menu item, or a button, when Telegram, Viber, or Facebook messengers are used.
2. The service receives a notification of the start of payment transaction meaning that the amount declared in the order is now reserved on the user's account/card. The service developer provides a URL where such notifications should be sent to. The URL should be accessible from TiPay Platform. It is specified in the payment link (see Step 1). If transaction fails, the same URL receives an error notification.
3. The user is notified of of the start of payment transaction and the appropriate amount is reserved. Usually service developers prefer to decide how such notification should be presented to the user and what form of wording is to be used. Therefore, TiPay Platform does not notify users independently, but leaves this job to service developers. Notifications are sent by means of Mobilizer Push API.
4. The service requests payment status. It may be needed if for some reason the service has not received the notification of the start of payment transaction (see Step 2). The service then requests the transaction status using service order ID.
5. Transaction confirmation. After the purchase is completed its final amount (that can be less than that initially declared) becomes known. To finalise the transaction the service should notify the platform by sending a direct HTTP request to the plugin containing the transaction ID and the ultimate amount.
6. Transaction rollback. If for some reason the services needs to cancel the transaction, it should make the rollback call.
7. The service is notified of transaction completion. This notification is sent to the URL set in the payment link (see Step 1). If the transaction fails, the failure notification will be sent to the same URL.
8. The user is notified of payment completion. Again, the service developer takes the job of notifying users, like at the Step 3.
9. Getting user information. This option is to check if any cards are bound to the user's account and to get the user's email address.

General Interworking Scenario

The general scenario of interworking of system components and the user is different for a first-time user and a user making recurring purchases. The first-time user scenario includes necessary steps of user registration and setting of payment PIN through a web browser. After that the user receives a payment link and follows it, then interacts with the payment system to make the purchase. If the user's bank card support recurrent payments, TiPay saves the pointer to it, so that the user can make next purchases without the necessity to enter the card details again. Note that the pointer is a hash sum created and shared with TiPay by an external payment system. TiPay does not hold any user data and card details.

In the recurrent user scenario the user does not have to input card details and use a web browser. The only necessary thing here is input of the payment PIN.

Composition of Payment Link

The link has this form: http://plugins.miniapps.run/tipay?order.id=<>&order.name=<>&order.amount=<>&receipt.url=<> and comprises parameters indicated in the table below.

Name	Description	Type	Mandatory
order.id	Unique order identifier generated by the content/service provider's system.	String	Yes
order.name	Order name. It can contain brief description of the order.	String	Yes
order.amount	Amount due.	Decimal	Yes
receipt.url	Notification URL (described above).	URL	Yes

%><?xml version="1.0" encoding="UTF-8"?>
<%
  Order order = new Order();
  order.id = generateNewOrderId();
  order.name = "Pump4:Regular:20L";
  order.amount = €38.20;
  String receiptUrl = "https://azs-backend.sintez.ru/payment-receipt";
%>
<page>
  <div>
    Confirm purchase €38.20, Regular, 20L.
  </div>
  <navigation>
    <link accesskey="1" pageId="http://plugins.miniapps.run/tipay?order.id=<%=order.id%>&amp;order.name=<%=URLEncoder.encode(order.name, "UTF-8")%>&amp;order.amount=<%=order.amount%>&amp;receipt.url=<%=URLEncoder.encode(receiptUrl, "UTF-8")%>">Оплатить</link>
    <link accesskey="0" pageId="index.jsp">Отмена</link>
  </navigation>
</page>

Service Is Notified About Start of Payment Transaction

After the user initiates the payment transaction a notification of transaction start is sent to receipt.url specified by the service at the previous step. It comprises parameters indicated in the table below.

Name	Description	Type
order.id	Unique order identifier inserted by the content/service provider's system in the payment link.	String
payment.id	Transaction identifier generated by TiPay. It will be required when finishing the transaction.	String
status	Initial transaction status. If the necessary amount was successfully blocked on the user's card, the status "HOLD" is returned. Otherwise "FAILED" is returned	String

User Is Notified About Start of Payment Transaction

Content/service provider's system notifies the user by calling push method in Mobilizer API.

Example:

HTTP GET

http://prod.globalussd.mobi/push?scenario=push&protocol=telegram&service=syntez.azs&user_id=6c0ed82b-f793-41cf-9114-cbaaf3e1fb16&message=<%=URLEncoder.encode("Payment €38.20, Regular", "UTF-8")%>

The parameters are described in the table below.

Name	Description	Type	Example
scenario	It should take the value push.	-	push
protocol	The name of the messenger used to communicate with the user.	String	telegram/viber/vk/facebook
service	Service ID in the Miniapps platform.	String	BP.ps
user_id_	User ID in the Miniapps platform. The content/service provider's system gets this value from the user_id parameter every time the Miniapps platform sends request to the system.	String	6c0ed82b-f793-41cf-9114-cbaaf3e1fb16
message	Message text encoded in accordance with RFC 1738. No spaces and special characters.	URL encoded string	URLEncoder.encode("Payment €38.20, Regular", "UTF-8")

Service Requests Payment Status

To request transaction related dinformation (transaction ID and status) the service can call get_payment method using HTTP address:

https://api.tipay.ru/tipay/get_payment?service=<>&order.id=<>

The parameters are described in the table below.

Name	Description	Type	Mandatory
payment.id	Transaction identifier generated by TiPay and received at Step 2.	String	No
service	Service identifier. Only mandatory in the absence of payment.id.	String	No
order.id	Order identifier generated by the service. Only mandatory in the absence of payment.id	String	No

TiPay answers with JSON object with fields specified in the following table. In the case of request failure the answer contains the field "error".

Name	Description	Type	Mandatory
paymentId	TiPay transaction ID.	String	No
status	Transaction status	String	No
error	Error text appearing in the case of request failure.	String	No

Transaction Confirmation

After the service gets the final amount it should close the transaction using the HTTP address:

https://api.tipay.ru/tipay/commit?payment.id=<>&order.amount=<>

The parameters are described in the table below.

Name	Description	Type	Mandatory
payment.id	Transaction identifier generated by TiPay and received at Step 2.	String	Yes
order.amount	The final amount of the purchase. It can be less than initially stated.	Decimal	Yes

Transaction Rollback

If for some reason the services needs to cancel the transaction, it should make the rollback call to HTTP address:

https://api.tipay.ru/tipay/rollback?payment.id=<>

The parameters are described in the table below.

Name	Description	Type	Mandatory
payment.id	Transaction identifier generated by TiPay and received at Step 2 or at Step 4.	String	Yes

TiPay answers with JSON object with fields specified in the following table. In the case of failure the answer contains the field "error".

Name	Description	Type	Mandatory
paymentId	TiPay transaction ID.	String	No
status	Transaction Status.	String	No
error	Error text appearing in the case of request failure.	String	No

The Service is Notified of Transaction Completion

When the transaction closes a notification about it is sent to the address receipt.url specified in the payment link. It comprises parameters described in the table below.

Name	Description	Type
order.id	Unique order identifier inserted by the content/service provider's system in the payment link.	String
payment.id	TiPay transaction ID.	String
status	Transaction completion status. In case of success the parameter takes the value "PAID", otherwise "FAILED"	String

The User is Notified of Payment Completion

The same way as the user is notified about the start of payment transaction.

Getting User Information

To get the user information, specifically, whether the card is bound with the user account, this call should be used:

https://api.tipay.ru/tipay/user_info?subscriber=<>

The user's MSISDN is sent a parameter.

Name	Description	Type	Mandatory
subscriber	User's MSISDN in TiPay.	String	Yes

TiPay answers with JSON object with fields specified in the following table. In the case of failure the answer contains the field "error".

Name	Description	Type	Mandatory
hasCard	Indicates whether a card is bound.	Boolean	No
email	User's email address.	String	No
error	Error text appearing in the case of request failure.	String	No