Version 1.0
Updated: 16/11/20
IMPORTANT NOTE: this feature is only available for Viber users in Ukraine.
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.
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.
The Viber Bot Payment API is only available for merchants who have a registered account with one of the following PSPs*:
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.
Enable the payment feature in your bot - contact the relevant PSP and request to enable the payment feature for your bot:
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.
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).
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.
Once your bot is launched, it will receive a verification mark and will be open for users.
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.
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”.
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.
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 |
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.
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.
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.
Signing algorithm and rest of documentation on iPay.ua website
Key | Value | Source | Description |
---|---|---|---|
gateway | “ipayua” | PSP | PSP ID in Google Pay and Apple Pay systems’ |
gatewayMerchantId | any string (example below) | Merchant | Merchant ID in iPay PSP system |
url | ”https://api-viber.ipay.ua” | PSP | URL for payment requests to PSP |
subMerchantId | any string (example below) | Merchant | Merchant id in PSP system. Can be found on the PSP website |
authSalt | any string | Merchant | Merchant password or token in iPay PSP system. Can be found on the PSP website |
authSign | any string | Merchant | Merchant password or token in iPay PSP system. Can be found on the PSP website |
transactions | any string (example below) | Merchant | Optional. An array of transactions, as a string, not a JSON array. |
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.
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 |
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. |