Skip to main content

Migrating from V1 to V2

Breaking changes

Dibsy V2 offers very radical changes to the payment flow, compared to Dibsy V1. Here are the following.

Payment Flow

In V1, payment is created on the server-side, and a token is supplied when submitting the payment on the client-side. However, this flow had some limitations, and thus Dibsy has adopted a new flow. In V2, the payment data are converted into a token on the client-side (either directly if you’re PCI-DSS compliant or using Dibsy Components) and you can use this token to charge your customer by creating payment on the server-side. How does this affect you?

Hosted Checkout/Payment Links

If are using V1 Hosted Checkout, the hosted checkout and the redirection has the same flow, and you don’t need to change anything in this regard. However, in V1, you may be familiar with the popup that takes your customer to 3D Secure in another tab. This is no longer the case and starting V2, the customers are redirected to the 3D Secure page in the same tab.

Dibsy Components

Dibsy components present the most radical change when migrating from V1 to V2. In V2, when your customers enter their card data and hit submit, their card information is converted into a secure encrypted token. This token then must be sent to your server and used to create a payment. The API responds with a 3D Secure link where you must redirect your customer to complete the payment. They are redirected to redirectUrl once 3DS is completed.

Payment API

  • If you’re making a credit card payment, you must use the cardToken parameter instead of token.
  • All amounts in the API are passed as a map containing both a currency and a value property, for example:
{
    "amount": {
        "currency": "QAR",
        "value": "16.00"
    }
}

Apple Pay

Apple Pay in V1 is only supported for Hosted Checkout and Payment Links. However, in V2, alongside previous features, you can directly add Apple Pay to your apps and websites.

Other changes

  • Improved error messages. Error messages will contain more details to help you quickly resolve any implementation problems.
  • Support for recurring payments that allows you to save customers cards (with Dibsy) and use them when customer consents to you for faster checkout.
  • Webhook service for payments. Simply include webhookUrl as one of the parameters.
  • Support for Customer API. If you have customers that you use for recurring payments or when creating a payment, you can now query them using the Customer API.