MIGRATION.md

Migration guide

This guide outlines the changes and steps needed to migrate your codebase to the latest version of the payOS Typescript and Javascript SDK.

Breaking changes

Initialize client

The library now relies on the builtin Web fetch API instead of axios. So we change the initialize function to have better options for the client.

// before
import PayOS from '@payos/node';

const payos = new PayOS(clientId, apiKey, checksumKey, partnerCode);

// after
import { PayOS } from '@payos/node';

const payos = new PayOS({ clientId, apiKey, checksumKey, partnerCode });

Methods name

All methods related to payment request now under PayOS.paymentRequests.

// before
await payos.createPaymentLink(paymentData);
await payos.getPaymentLinkInformation(paymentLinkId);
await payos.cancelPaymentLink(paymentLinkId);

// after
await payos.paymentRequests.create(paymentData);
await payos.paymentRequests.get(paymentLinkId);
await payos.paymentRequests.cancel(paymentLinkId);

For webhook related methods, they now under PayOS.webhooks.

// before
await payos.confirmWebhook(webhookUrl);
payos.verifyPaymentWebhookData(webhookBody);

// after
await payos.webhooks.confirm(webhookUrl);
await payos.webhooks.verify(webhookBody);

Types

Some types has been renamed, more detail below.

// before
const paymentData: CheckoutRequestType;
const result: CheckoutResponseDataType = await payos.createPaymentLink(paymentData);

// after
const paymentData: CreatePaymentLinkRequest;
const result: CreatePaymentLinkResponse = await payos.paymentRequests.create(paymentData);

// before
const paymentLinkInfo: PaymentLinkDataType = await payos.getPaymentLinkInformation(paymentLinkId);
const paymentLinkCancelled: PaymentLinkDataType = await payos.cancelPaymentLink(paymentLinkId);

// after
const paymentLinkInfo: PaymentLink = await payos.paymentRequests.get(paymentLinkId);
const paymentLinkCancelled: PaymentLink = await payos.paymentRequests.cancel(paymentLinkId);

// before
const confirmResult: string = await payos.confirmWebhook(webhookUrl);
const webhookBody: WebhookType;
const webhookDataVerified: WebhookDataType = payos.verifyPaymentWebhookData(webhookBody);

// after
const confirmResult: ConfirmWebhookResponse = await payos.webhooks.confirm(webhookUrl);
const webhookBody: Webhook;
const webhookDataVerified: WebhookData = await payos.webhooks.verify(webhookBody);

Handling errors

The library now throw client error as PayOS.PayOSError, API related errors as PayOS.APIError, webhook related errors as PayOS.WebhookError and signature related errors as PayOS.InvalidSignatureError instead of throw PayOSError for related API errors and Error for other errors.

// before
payos
  .createPaymentLink(paymentData)
  .then((res) => res)
  .catch((err) => {
    if (err instanceof PayOSError) {
      console.log(err.message);
      console.log(err.code);
    }
  });

// after
payos.paymentRequests
  .create(paymentData)
  .then((res) => res)
  .catch((err) => {
    if (err instanceof APIError) {
      console.log(err.status);
      console.log(err.code);
      console.log(err.desc);
    }
  });