Use the TypeScript SDK

Applies to:Developers

Payabli offers a Software Development Kit (SDK) that can be installed in your projects to support application development. The SDK provides type safety when programming with the API. This reduces the risk of errors and improves the developer experience. Most development environments can use the SDK to generate code suggestions and inline documentation. The SDK is only available for TypeScript. See the @payabli/sdk-node package for more information.

SDK autocompletion in Zed — Code suggestions and inline documentation

Dependencies

Before you begin, make sure you have the following installed on your machine:

Use the SDK

This section shows you how to install and use the Payabli SDK in a new Node.js project. The example code in this section shows how to use the SDK to make a transaction. It uses the moneyIn.getpaid method. The moneyIn.getpaid method calls the MoneyIn/getpaid endpoint.

Method names in the SDK correspond to endpoint names in the API reference. For example: the notification.addNotification method calls the POST Notification endpoint. See the SDK reference for a full list of methods.

Create a new Node.js project

Open your terminal and run the following commands to create a new Node.js project:

$ mkdir my-payabli-app
> cd my-payabli-app
> npm init -y

Set the type to module

Open the package.json file in your code editor and set the "type" field to "module":

1 {
2   "type": "module"
3 }

Install the SDK

Run the following command to install the Payabli SDK:

$ npm install @payabli/sdk-node

Create a new file

Create a new file called index.ts in the root of your my-payabli-app directory. Open the index.ts file in your code editor.

Import the client

At the top of the index.ts file, import the Payabli client:

1 // index.ts
2 import { PayabliClient } from '@payabli/sdk-node';

Create a new client

Create a new instance of the Payabli client:

1 // index.ts
2 import { PayabliClient } from '@payabli/sdk-node';
3 
4 const client = new PayabliClient({ apiKey: "REPLACE_WITH_YOUR_API_KEY" });

Make a transaction

Use the client to make a transaction:

1 // index.ts
2 import { PayabliClient } from '@payabli/sdk-node';
3 
4 const client = new PayabliClient({ apiKey: "REPLACE_WITH_YOUR_API_KEY" });
5 
6 const result = await client.moneyIn.getpaid({
7     body: {
8         customerData: {
9             customerId: 4440,
10         },
11         entryPoint: "REPLACE_WITH_YOUR_ENTRYPOINT",
12         ipaddress: "255.255.255.255",
13         paymentDetails: {
14             serviceFee: 0,
15             totalAmount: 100,
16         },
17         paymentMethod: {
18             cardcvv: "999",
19             cardexp: "02/27",
20             cardHolder: "Kassiane Cassian",
21             cardnumber: "4111111111111111",
22             cardzip: "12345",
23             initiator: "payor",
24             method: "card",
25         },
26     },
27 });

Log the result

Log the result of the transaction to the console:

1 // index.ts
2 import { PayabliClient } from '@payabli/sdk-node';
3 
4 const client = new PayabliClient({ apiKey: "REPLACE_WITH_YOUR_API_KEY" });
5 
6 const result = await client.moneyIn.getpaid({
7     body: {
8         customerData: {
9             customerId: 4440,
10         },
11         entryPoint: "REPLACE_WITH_YOUR_ENTRYPOINT",
12         ipaddress: "255.255.255.255",
13         paymentDetails: {
14             serviceFee: 0,
15             totalAmount: 100,
16         },
17         paymentMethod: {
18             cardcvv: "999",
19             cardexp: "02/27",
20             cardHolder: "Kassiane Cassian",
21             cardnumber: "4111111111111111",
22             cardzip: "12345",
23             initiator: "payor",
24             method: "card",
25         },
26     },
27 });
28 
29 console.log(result);

Run the app

Run the app with the following command:

$ tsx index.ts

Check the result

Check the console output for the result of the transaction. A successful transaction returns a JSON response like this:

1 {
2   responseText: "Success",
3   isSuccess: true,
4   pageIdentifier: null,
5   responseData: {
6     authCode: "TAS003",
7     referenceId: "255-67bc92c141e24f474f60c1968fcba0cd",
8     resultCode: 1,
9     resultText: "Approved",
10     avsResponseText: "No Match, No address or ZIP match",
11     cvvResponseText: "CVV2/CVC2 match",
12     customerId: 4440,
13     methodReferenceId: null,
14   },
15 }

In production, we recommend that you pass a stored method ID to the paymentMethod object instead of card details. See more information in Tokenization Overview.

SDK example app

The SDK example app is a basic web application built with the @payabli/sdk-node package. It demonstrates how to create, view, and delete customers with the SDK. The code is publicly available at the example repository.

Set up the app

Follow these steps to set up the SDK example app on your local machine:

Clone the repository

Open your terminal and run the following command to clone the SDK example app repository:

$ git clone https://github.com/payabli/examples

Navigate to the app directory

In your terminal, navigate to the directory of the SDK example app:

$ cd examples/sdk-example

Install the dependencies

Install the dependencies with the following command:

$ npm install

Copy the environment template

Copy the.env.template file to a new file called .env:

$ cp .env.template .env

Fill in your environment variables

Open the .env file in your code editor. Set PAYABLI_KEY to your Payabli API token and PAYABLI_ENTRY to your Payabli entrypoint:

$ # your Payabli API token
> PAYABLI_KEY="o.Oim...Mekgjw="
> # your Payabli entrypoint
> PAYABLI_ENTRY="41xxxxxa7e"

Start the development server

Run this command to start the development server, and open the app in your browser:

$ npm run dev

Use the app

The SDK example app has two pages:

Create Customer - Create a new customer in the Payabli entrypoint.
List Customers - View a list of all customers in the Payabli entrypoint.

You can delete customers on the List Customers page.

Create customer

The Create Customer page has a form that allows you to create a new customer. Fill in the form with the customer’s information and click the “Create” button. If the customer is created successfully,a green success message appears below the button.

List customers

The List Customers page has a table of all customers in the entrypoint. You can view the customer’s information, including their name, email address, and ZIP Code.

Delete customer

In the List Customers page, you can delete a customer by clicking the red “X” button on the right side of the customer’s row. If the customer is deleted successfully, the row is removed from the table.