Gopay Miniapp Client

MiniAppSDK is a JavaScript library that provides a simple interface for initializing your app and retrieving location information.

Installation

You can install MiniAppSDK using npm:

npm install @gopay/miniapp-client

Usage

Miniapp sdk behavior is different on development or production. During the development, you'll be using a dummy SDK that will mimic the behavior of the sdk during production stage.

Initialization

If you're using vite, you can determine the environment your webapp is currently running using import.meta.env.PROD

import MiniAppSDK from '@gopay/miniapp-client';

const inProductionEnvironment = import.meta.env.PROD;

const miniAppSdk = new MiniAppSDK({
  useDummyService: !inProductionEnvironment
});

SDK Methods

For details on new handlers and their implementation, please refer to the documentation.

Every method calls will returns this object:

type MethodCallResult<Data = {}> = {
  success: boolean;
  data?: Data;
  error?: {
    code: number;
    message: string;
  };
};

Where the Data object will differ with each method call

Location

1. Get user location

miniAppSdk.getLocation().then((result) => {
  console.log('Latitude:', result.data.latitude);
  console.log('Longitude:', result.data.latitude);
  console.log('Time:', result.data.time); // time of the user's location
});

Location data :

{
  "latitude": number,
  "longitude": number,
  "time": number // milliseconds since epoch
}

Possible Error Codes:

• 300 : No permission error
• 400 : Resource not found error

Authentication

1. Get authentication code

miniAppSdk.getAuthCode().then((result) => {
  console.log('Authcode:', result.data.auth_code);
});

Authcode Data:

{
  "auth_code": string
}

Possible Error Codes:

• 400 : Resource not found error
• 401 : Network error

Deeplink

1. Open a gopay deeplink

const deeplink = 'gopay://...';

miniAppSdk
  .openGopayDeeplink(deeplink)
  .then((result) => {
    console.log('Success:', result.success);
  })
  .catch((err) => {
    console.log(err);
  });

Possible Error Codes:

• 200 : Incomplete parameter error
• 201 : Invalid parameter type error
• 202 : Parameter data error

2. Trigger payment

[!NOTE] Available from : 0.3.19

// fetch the deeplink from your miniapp backend
const paymentDeeplink = 'gopay://...';

miniAppSdk.triggerPayment({ deeplink: paymentDeeplink }).then((result) => {
  console.log('Payment status:', result.data.status);
});

The payment result will be returned when user returns to miniapp after completing or cancelling payment.

Payment status data:

type PaymentData = {
  status: 'success' | 'failed' | 'pending' | 'cancelled';
};

| Status | Description | | --------- | -------------------------------------------------------------------------- | | success | User have successfully paid the transaction | | cancelled | User cancelled the transaction | | failed | There's an error processing the transaction | | pending | User goes back to the miniapp without completing or cancelling the payment |

Possible Error Codes:

• 200 : Incomplete parameter error
• 201 : Invalid parameter type error
• 202 : Parameter data error
• 401 : Network error

Error Codes:

Categories

Here are the error code categories and its descriptions

| Code | Category | Description | | ---- | -------------------- | ------------------------------------------------------------------------------------------------- | | 1xx | Platform Error | Platform-related errors, such as opening gopay deeplink while you're testing on the web | | 2xx | Miniapp Error | Such as method invocation error calling openDeeplink with a wrong deeplink format | | 3xx | Permission Error | Permission-related error, such as getting user location but the user does not give the permission | | 4xx | Device related Error | Returned on device-related error such as network error | | 5xx | Superapp Error | Error from the superapp side (imagine this as server error) |

Error Codes List

| Codes | Description | Happens When | | ----- | -------------------------- | --------------------------------------------------------------------------------------------------------- | | 100 | Method not supported error | The miniapp is calling a method that's not supported on the platform. | | 200 | Incomplete parameter error | The method call have incomplete parameters | | 201 | Invalid type error | The method call have invalid parameters. E.g. providing int while the required type is string | | 202 | Parameter data error | The parameters being called is not supported by gopay. E.g. calling open deeplink with non-gopay deeplink | | 203 | Miniapp not registered | The miniapp you're developing is not registered inside gopay system | | 300 | No permission error | Miniapp does not have access to the method being called | | 400 | Device not supported | The resource being requested is not supported by the device | | 401 | Network Error | Internet related problem such as slow or disconnected internet | | 500 | Superapp error | Superapp related error. Happens if there's an internal error in gopay while a resource is requested |