Bot Payment API

Version 1.0
Updated: 16/11/20

IMPORTANT NOTE: this feature is only available for Viber users in Ukraine.

Overview

Use Viber’s Bot Payment API to send an order details message to your bot subscribers, allowing them to make purchases directly from the bot. You will receive the payment status of the transaction in a callback once the user completes the checkout process.

For more information on how to buy from a chatbot on Viber - click here

The use of the Viber’s Bot Payment API is also subject to the Viber Terms & Policies, including the Terms and Conditions regarding Viber Chatbot Payments Service, the Viber Public Account, Public Chat, Bot, Community, and VAP Terms & Guidelines, and the Viber API Terms of Service, as may be amended from time to time.

Definitions

Developer - the party that programs the logic of the bot’s behavior. Development can be done by the merchant or by a third party.

Merchant - entities with a legitimate business activity who sell goods or services. Users purchase goods or services from Merchants.

PSP - A third-party payment service provider that is partnered with Apple and Google to accept payments on the Merchants’ behalf.

Before starting

PSP Account

The Viber Bot Payment API is only available for merchants who have a registered account with one of the following PSPs*:

LiqPay (Ukraine)

Portmone (Ukraine)

IPay (Ukraine)

If you’re a merchant without a chatbot you can contact one of our authorized chatbot developers to help you get started, or develop the chatbot yourself according to the following process and documentation.

*Are you a Payment Service Provider looking to integrate with Viber? Contact us.

Getting Started

1. Have an active bot - see our step-by-step instructions for creating a bot here.

2. Enable the payment feature in your bot - contact the relevant PSP and request to enable the payment feature for your bot:

   1. The PSP will make all the necessary checks, sign an agreement with the merchant, approve the request, and reach out to Viber with a request to enable the payments feature for your chatbot.

   2. In the request to Viber, your PSP must include the chatbot URI, your (the chatbot developer) email, and the email of the merchant who owns the chatbot (if it is different to that of the developer).

   3. If Viber approves the request, the payment feature will be enabled on your bot. The merchant, as well as your PSP, will be notified about the approval.

3. Obtain merchant test and production credentials from your PSP, to be used with Viber’s Bot Payment API. For more information regarding the required credentials from the PSP, please see the Payment Parameters for Payment Type section.
4. Implement the payment message logic in your chatbot. For further details see the Send Message Request section of Viber’s REST API documentation.
5. Test your chatbot using the credentials from the PSP and launch once ready.

Once your bot is launched, it will receive a verification mark and will be open for users.

Handling user disputes

In order to enable payments within your chatbot, you must provide support to chatbot users in case they want to dispute a transaction with the merchant. This includes refunds, return/exchange of goods, and any other transaction disputes*.

Channels of support must include:

• Contact via email - email addresses will be listed in the user support article.

• Present your support channels as part of the chatbot itself.

*Viber is not responsible for resolving disputes between merchants, PSPs, and users.

API Reference

Important note

The Bot Payment API is currently only supported on mobile devices. When receiving payment messages on Desktop, users will see the message: “I sent you a message that is not supported on your device”.

Architecture

Send Message Request

The send_message API allows bots to send messages to Viber users who have subscribed to the bot. Additional information about send_message requirements and validations can be found here

Please note: The payment message automatically displays a “continue to checkout” button, which expires after 15 minutes.

Resource URL:

https://chatapi.viber.com/pa/send_message

Payment (order details) message structure

Post data

{
 "auth_token":  "445da6az1s345z78-dazcczb2542zv51a-e0vc5fva17480im9",
 "receiver": "01234567890A==",
 "min_api_version": 10,
 "type": "payment",
 "payment":
 {
    "type": "GooglePay",                 
    "description":"2 shirts XL",        
    "total_price": 1.85,                
    "currency_code": "EUR",              
    "payment_parameters":                
    [   
        {"key": "gateway" , "value": "gateway-name"},
        {"key": "gatewayMerchantId", "value": "ExampleMerchantId#123"},
        {"key": "url" , "value": "https://payment-service/api/gateway"},
        {"key": "otherParameterKey", "value": "otherParameterValue"},
	...
    ]
 }
}

Post parameters

Payment parameters for payment types

The following is a list of parameters that need to be provided to the Google Pay system and to the PSP, in order to process a payment.

Mandatory parameters for PSP Portmone

*The use of a generated password token is preferable but not mandatory. The token will hide your actual password from the request body. You will find the password in the “Personal Area” of the Portmone website or in the Portmone developer’s documentation.

Payment request example for Portmone:

{
	"auth_token": "1234567",
	"min_api_version": 10,
	"receiver": "qwerty",
	"sender":
	{
		"name": "mybot",
		"avatar": ""
	},
	"type": "payment",
	"payment":
	{
		"type":"GooglePay",
		"description":"test payment",
		"total_price":1.23,
		"currency_code":"UAH",
		"payment_parameters":
		[
			{"key":"gateway","value":"portmonecom"},
			{"key":"gatewayMerchantId","value":"12345"},
			{"key":"url","value":"https://www.portmone.com.ua/r3/api/gateway"},
			{"key":"login","value":"login"},
			{"key":"password","value":"PasswordHashCode"},
			{"key":"payeeId","value":"12345"}
		]
	}
}

Mandatory parameters for PSP LiqPay.

LiqPay support If you require support in connecting to LiqPay, please contact LiqPay on the LiqPay developers portal for support.

Payment request example for “LiqPay” service

{
	"auth_token": "1234567890&",
	"url": "https://api.webhookinbox.com/i/u9MMDI2ns/in/",
	"min_api_version": 10,
	"receiver": "qwerty",
	"sender":
	{
		"name": "mybot",
		"avatar": ""
	},
	"type": "payment",
	"payment":
	{
		"type":"GooglePay",
		"description":"Test purchase",
		"total_price":9.99,
		"currency_code":"UAH",
		"payment_parameters":
		[
			{"key": "gateway", "value": "liqpay"},
			{"key": "gatewayMerchantId", "value": "abc123"},
			{"key": "url", "value": "https://www.liqpay.ua/api/viber"},
			{"key": "data",	"value": "qwerty12345"},
			{"key": "signature", "value": "123abc"	},
			{"key":"payeeId","value":"abc123"}
		]
	}
}

Mandatory parameters for PSP IPay.ua

Signing algorithm and rest of documentation on iPay.ua website

Payment request example for IPay.ua

{
  "auth_token": "1234567890&"
  "receiver": "qwerty",
  "min_api_version": 10,
  "type": "payment",
  "payment": {
	"type": "GooglePay",
	"description": "2 shirts XL",
	"total_price": 0.3,
	"currency_code": "UAH",
	"payment_parameters": 
	[
	  {"key": "gateway","value": "ipayua"},
	  {"key": "gatewayMerchantId","value": 1111},
	  {"key": "url","value": "https://api-viber.ipay.ua"},
	  {"key": "subMerchantId","value": 2222},
	  {"key": "authSalt","value": "4ad908f5a74096cdcbcf5a36e03089410ce6811a"},
	  {"key": "authSign","value": "9b4b0cd8c06c9d3f23704b53caadaf41e474cd4ee618ccc2dc796fe1be0d2ff882317ecffafe943cbd03f68fa7c3de333843eb1b3d69b5be7a38f96f949aefb3"},
	  {"key": "transactions","value": "[{\"desc\":\"single transaction\",\"amount\":30}]"}
	]
  }
}

Client_status callback

This callback is sent to the bot’s webhook URL after the user taps on the payment provider (i.e. Google Pay) “Pay” button, in the checkout page.

{
 "event": "client_status",               
 "timestamp": 1457764197627,                    
 "message_token": 4912661846655238145,     
 "chat_hostname": "sn-chat-04",
 "user":
 {
    "id": "01234567890A=",                     
    "name": "John McClane",                       
    "avatar": "https://avatar_url",          	
    "country": "UA",                           
    "language": "ua",                     
    "api_version": 1,                           
  },
 "status": {
     "type": "payment", 
     "code": 0,  
     "supported_psps" : ["bank1", "bank2", "bank3"], 
     "tracking_data": "tracking data"   
   }
}

Callback parameters

Error codes

General error codes for the Viber Bot API can be found here. The following error codes are those relevant for the Bot Payment API: