Viber API Documentation7.3.0

Docs / Tools / Bot Payment API

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)

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:

*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

Name Description Validation
auth_token A unique bot identifier used to validate your account in all API requests. Once your account is created your authentication token will appear in the account’s “edit info” screen (for admins only). Each request posted to Viber by the account will need to contain the token. Required. Each API request must either include an HTTP header X-Viber-Auth-Token containing the account’s authentication token, or include this parameter in the request body. Each API request must include the account’s authentication token in the HTTP header (X-Viber-Auth-Token), or in the request body.
receiver The unique Viber user ID. Required. the user ID of a subscribed user.
min_api_version The minimum API version required by clients for this message is 10. For more info about min API version click here Optional but highly recommended to ensure that the recipient’s client version supports the payment API.
type Message type. Required. Value: payment.
payment.type Payment type. Required. Currently only “GooglePay” for Android devices and “ApplePay” for iOS devices are valid.
payment.description Free text description. Optional
payment.total_price The price units, up to two decimal places (for example: 1.85). Required
payment.currentcy_code Currency string according to ISO 4217 currency code. Required
payment.payment_parameters List of parameters needed for: Getting the encrypted token for payment system provider (PSP) from the digital wallet platform (currently Google Pay and Apple Pay only). Should be provided by PSP or merchant. Parameters needed for the request to the PSP. Contains a generic array of Json objects, each with “key”-“value” structure. Required

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

Key Value Source Description
gateway “portmonecom” PSP PSP ID in Google Pay and Apple Pay systems’
gatewayMerchantId any string Merchant Merchant ID in PSP system
url ”https://www.portmone.com.ua/r3/en/api/gateway/” PSP URL for payment requests to PSP
login any string Merchant Merchant login in PSP system
password any string Merchant Merchant password or token in PSP system*
payeeId any string Merchant Merchant payee ID in PSP system

*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.

Key Value Source Description
gateway “liqpay” PSP PSP ID in Google Pay and Apple Pay systems’
gatewayMerchantId any string Merchant Merchant Public Key in LiqPay PSP system For more info click here
url ”https://www.liqpay.ua/api/viber” PSP URL for payment requests to PSP
data any string Merchant Encrypted data about a purchase. For more info click here
signature any string Merchant Merchant authentication signature in PSP system. For more info click here
payeeId any string Merchant Merchant Public Key in LiqPay PSP system. For more info click here

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"}
		]
	}
}

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": "http://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

Name Description Possible values
event Callback type - which event triggered the callback “Client_status”
timestamp Time of the event that triggered the callback Epoch time
user.id Unique Viber user ID  
user.name User’s Viber name  
user.avatar URL of user’s avatar  
user.country User’s two letter country code ISO ALPHA-2 Code
user.language User’s present phone language ISO 639-1
user.api_version The maximal Viber version that is supported by all of the user’s devices  
message_token Unique ID of the message  
chat_hostname For Viber internal use  
status.type Status type “payment”
status.code Numeric code signifying the result of the payment process  
status.supported_psps A list of supported PSPs  
status.tracking_data Tracking data of the message. See more on tracking_data here  

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:

Value Name Description
13 apiVersionNotSupported Will be returned when the recipient’s Viber version does not support the payment API. The message was not delivered to the recipient in this case.
21 unsupportedCountry Will be returned when the recipient’s country is not in a supported country. The message was not delivered to the recipient in this case.
3 badData Will be returned when: The currency code is not ISO 4217. The total_price has an invalid value. The payment ‘type’ is not supported. Currently we support payment types “GooglePay” and “ApplePay”. The message was not delivered to the recipient in this case.
22 paymentUnsuported Will be returned when the payment API has not been enabled for the bot.