Status page
Changelog
Back to All

2023-01-20

over 1 year ago by Iuliia Kovalchuk

Widget API Version 2 flow is released:

With the release of Version 2 of the Paybis Widget, we have added a variety of alternative payment methods (APMs) for customers to use when purchasing crypto. These options include open banking, traditional bank transfers, e-wallets, and local payment methods. The inclusion of these APMs serves to enhance the overall user experience, boost transaction success rates and provide lower fees for customers.

User flow changes

Payment method selection
The new flow for the widget begins with selecting a payment method after successful authentication. The list of available APMs is determined by the chosen fiat currency. Users can easily compare payment methods by viewing their characteristics, such as transaction limits, fees, and approval rate, displayed on the user interface. When integrated with a quote, fees are calculated and displayed in the quote currency. In cases where a quote is not being used, fees are displayed as a percentage.

Exchange form
When changing a fiat currency on the exchange form, the user is redirected back to the payment selection screen to see the updated list of available payment methods.

Completing a payment
Steps that a customer has to complete to make a payment depend on the selected payment method:

  • Credit card payment process remains unchanged.
  • Payments via alternative methods, e.g. online banking, may include redirects to external apps (e.g. banking apps). After completing the payment, the user is redirected back to Paybis Widget.

Verification
In contrast to credit card payments, where users are prompted to provide verification information after payment authorization, transactions using alternative methods require a customer to complete their Know Your Customer (KYC) verification prior to submitting a payment.

API flow changes

In Widget API V2, the following changes were introduced:

  1. V2 POST Quote endpoint: POST Quote endpoint now returns the array of quotes calculated for each supported payment method.
  2. V2 POST Request endpoint: POST Request endpoint response remains unchanged.
  3. V2 GET Payment Methods endpoint: the new endpoint that allows to retrieve the list of supported payment methods for a specific quote currency pair.

Note: We keep supporting the following V1 endpoints in version 2 of the Widget: GET Currency Pairs, POST SumSub Shared Token.

For detailed information on the API V2 flow, see the Flow with Quote or Flow without Quote guides.

Widget API V2 tips and tricks

There is a couple of new Widget API V2 features that can be utilized to enhance the user experience in your application:

  1. By using the V2 GET Payment Methods endpoint, you can retrieve a list of supported payment methods for a specific fiat/crypto pair, along with their properties, such as minimum and maximum transaction amounts, fees, and labels (e.g. "Instant," "Low Fee," "Best Approval Rate"). This enables you to display the relevant information about fees and limits in your application and validate user input before initiating the widget.
  2. If you need to display calculated quotes per payment method in your application, you can process the response of the V2 POST Quote endpoint. This method can also assist in identifying the payment method with the lowest fees.
  3. You can pass a preferred payment method in the POST Request endpoint request, which will be highlighted in the widget UI and appear at the top of the payment methods list, though the user will still have the option to select another method from the list.

Migrating to Widget API V2 flow

Migrating from Widget API V1 to V2 is a straightforward process, as all you need to do is change the API version number in the URLs for the POST Quote and POST Request endpoints.

If your integration does not request a quote from Paybis, the migration process will require minimal development efforts, as the structure of the POST Request endpoint response remains unchanged.

However, if you utilize quotes in your integration and start the widget with a quote, it's important to handle the new V2 POST Quote endpoint response. The V2 endpoint returns an array of quotes calculated for each available payment method. If a quote cannot be calculated for a specific payment method, an error will be returned in the paymentMethodErrors object, for example, if the transaction amount is less than the minimum limit for the payment method.

See the Migration Guide for detailed steps.

V1 API Deprecation

The V1 POST Quote and V1 POST Request endpoints will be discontinued three months following the release of V2. It is important to ensure that you have made all necessary changes to your integration before support for these deprecated endpoints is discontinued.

Backward compatibility

Widget API is backwards compatible: if for some reason you migrate to V2 endpoints and fail to upgrade mobile SDK clients until then, the old version will continue to work with the previous flow (credit card payments only).

Supported APMs

The list of integrated payment methods that can be enabled for our partners immediately (more coming!):
EU Instant Bank Transfer - 0-2 days
UK Instant Bank Transfer - Instant
PIX - Instant
Khipu - Instant
WebPay - Instant
PSE - Instant
Skrill - Instant
Giropay - Instant
AstroPay - Instant
Most of the APMs can be tested in sandbox mode before going live with them. Refer to this article to learn more.

Partner Portal changes

Fee settings
You can configure different fees for each payment method enabled for your business account. For this, go to the Fee Settings section in the partner portal and switch between available payment methods using the Payment method filter.

Dashboard
On the dashboard, the aggregated balance and success rates statistics are displayed. This includes transactions made through all available payment methods. Success rate calculations for both credit card payments and alternative methods only include transactions with payment attempts.

Analytics and transactions
Analytics and Transactions reports by default show transactions made via all available payment methods, but you can keep track of the statistics per payment method by applying the corresponding filter.