gatepay v1.0.3

Typescript Payment Gateway

This package works with multiple drivers, and you can create custom drivers if you can't find them in the current drivers list (below list).

• داکیومنت فارسی
• English documents

List of contents

• Typescript Payment Gateway
• List of contents
• List of available drivers
  • Install
  • How to use
    • Working with invoices
    • Purchase invoice
    • Pay invoice
    • Verify payment
    • Useful methods
    • Create custom drivers:
  • Local driver (for development)

List of available drivers

• atipay :heavy_check_mark:
• idpay :heavy_check_mark:
• payir :heavy_check_mark:
• payping :heavy_check_mark:
• sep (saman electronic payment) Keshavarzi & Saderat :heavy_check_mark:
• zarinpal :heavy_check_mark:
• zibal :heavy_check_mark:
• local :heavy_check_mark:
• Others are under way.

you can create your own custom drivers if it doesn't exist in the list, read the Create custom drivers section.

Install

$ npm install gatepay

How to use

In your code, use it like the below:

  // Create new Instance.
  const payment = new Payment(Driver);

  // Set merchantId.
  payment.setMerchantId("merchantId");
  // Set invoice amount.
  payment.setAmount(10000);
  //Add invoice details.
  payment.getDriver().setDetail("detail", "value");

  //or 

  // Create new invoice.
  const invoice = new Invoice()
  // Set invoice amount.
  invoice.setAmount(10000)
  // Set invoice details.
  invoice.setDetail("detail", "value")
  // Set invoice.
  payment.getDriver().setInvoice(invoice);

Purchase invoice

In order to pay the invoice, we need the payment transactionId. We purchase the invoice to retrieve transaction id:

  // Purchase method accepts a callback function.
  payment
    .purchase((amont: number, transactionId: string, uuid: string) => {
      // We can store transactionId in database
    })

Pay invoice

  // Retrieve json format of Redirection (in this case you can handle redirection to bank gateway)
  payment
  .purchase((amont: number, transactionId: string, uuid: string) => {
    // Store transactionId in database.
    // We need the transactionId to verify payment in the future.
  })
  .then((res) => {
    return res.pay().toJson();
  });

Verify payment

  // You need to verify the payment to ensure the invoice has been paid successfully.
  // We use transaction id to verify payments
  // It is a good practice to add invoice amount as well.
  try {
    const receipt = await payment.setTransactionId(transactionId).verify();

    // You can show payment referenceId to the user.
    receipt.getReferenceId()
    // You can get payment date tame.
    receipt.getDate()
    
  } catch (error) {
    // when payment is not verified, it will throw an exception.

    console.log(error);
  }

You can get payment data.

  
  try {
    const receipt: DriverReceipt = await payment.setTransactionId(transactionId).verify();
    
    receipt.getData()
    
  } catch (error) {
    // when payment is not verified, it will throw an exception.

    console.log(error);
  }

Create custom drivers:

import { Driver, Receipt, DetailInterface, Setting, Gateway, Invoice, Payment } from "gatepay";

interface CustomSetting extends Setting {}

export interface CustomDetail extends DetailInterface {
  custom?: string;
}

type VerifyResponseType = {id: string, order_id: string}

class CustomReceipt extends Receipt<VerifyResponseType> {}

class Custom extends Driver<Invoice<CustomDetail>> {
  public settings: CustomSetting = {
      apiPaymentUrl: "http://api.custom.com/payment",
      apiPurchaseUrl: "http://api.custom.com/purchase",
      apiVerificationUrl: "http://api.custom.com/verify",
      callbackUrl: "http://callback.custom.com",
      merchantId: "",
  };
  constructor() {
    super(new Invoice());
  }

  // Purchase the invoice, save its transactionId and finaly return it.
  async purchase(): Promise<string> {
    // Request for a payment transaction id.
    ...


    this.invoice.setTransactionId("custom");

    return this.invoice.getTransactionId();
  }

  // Redirect into bank using transactionId, to complete the payment.
  pay(): Gateway {
    // Prepare payment url.
    const payUrl = `${this.settings.apiPaymentUrl}${this.invoice.getTransactionId()}`;

    // Redirect to the bank.
    return new Gateway(payUrl, "GET");
  }

  // Verify the payment (we must verify to ensure that user has paid the invoice).
  async verify(): Promise<CustomReceipt> {
    //

    return new CustomReceipt("payment_receipt_number", data);
  }
}

Local driver

Local driver can simulate payment flow of a real gateway for development purpose.

Payment can be initiated like any other driver

You can get payment data.

  // Create new Instance.
  const payment = new Payment(Local);

  // Set merchantId.
  payment.setMerchantId("merchantId");
  // Set invoice amount.
  payment.setAmount(10000);
  //Add invoice details.
  payment.getDriver().setDetail("detail", "value");

Payment can be verified after receiving the callback request.

  const receipt: LocalReceipt = await payment.setTransactionId(transactionId).verify();

In case of succesful payment, receipt will contains the following parameters

  {
    orderId: // fake order number 
    traceNo: // fake trace number (this should be stored in databse)
    referenceNo: // generated transaction ID in `purchase` method callback
    cardNo:// fake last four digits of card 
  }