@first-iraqi-bank/sdk

First Iraqi Bank allows you to create online payments in your application using Rest API.

This package helps you integrate the payment API easily on your JavaScript/TypeScript backend server with simple and typed set of functions.

Table of Contents

• Installation
• Technical notices
• Methods
  • authenticate
  • createPayment
  • getPaymentStatus
  • cancelPayment
  • refundPayment
• Types & Responses
• Error Handling
• Contributing

Installation

npm

npm i @first-iraqi-bank/sdk

yarn

yarn add @first-iraqi-bank/sdk

pnpm

pnpm add @first-iraqi-bank/sdk

deno

direct import with npm: prefix:

import { PaymentSDK } from "npm:@first-iraqi-bank/sdk@pre/payment"

Or after adding the package to the import maps of your deno.json file:

{
  "imports": {
    "@first-iraqi-bank/sdk": "npm:@first-iraqi-bank/sdk@pre"
  }
}

import using the name of the package only:

import { PaymentSDK } from "@first-iraqi-bank/sdk/payment"

in deno.json:

bun

bun add @first-iraqi-bank/sdk

Technical notices

You need to register for the sandbox environment to get your client_id and client_secret. Once you are ready to move to production, contact [email protected] to obtain your production credentials.

1. This package guarantees support for Maintenance and LTS versions of Node.js, starting from v18 of Node.js. if you encountered any issues in this regard, please let us know.

2. This package guarantees support for ESM and CJS module formats, we prefer and recommend of using ESM everywhere if it works for you.

3. This package is built on top of the Fetch API and all functions return a Response giving you maximum flexibility to parse or ignore the responses you get. Check out Node.js docs - Fetch section which is available since v18.0.0

Usage

You can import the SDK classes and types from the payment entrypoint:

import { PaymentSDK } from "@first-iraqi-bank/sdk/payment"

The PaymentSDK class has a static method that gives you an instance of the SDK configured with your API credentials:

// fib.js

import { PaymentSDK } from "@first-iraqi-bank/sdk/payment"

const clientId = process.env.FIB_CLIENT_ID
const clientSecret = process.env.FIB_CLIENT_SECRET
const environment = process.env.FIB_ENV // 'dev', 'stage', or 'prod'

export const FIB = PaymentSDK.getClient(clientId, clientSecret, environment)

Now you can import FIB from anywhere in your project and call its methods to create payments, check payment status or canceling them.

[!TIP] Checkout FIB Web Payment documentations for more info and how to obtain your credentials

• authenticate(signal?: AbortSignal): Authenticates the client and returns an access token.
• createPayment(paymentInput: PaymentInput, accessToken: string, signal?: AbortSignal): Creates a payment.
• getPaymentStatus(paymentId: string, accessToken: string, signal?: AbortSignal): Gets the status of a payment.
• cancelPayment(paymentId: string, accessToken: string, signal?: AbortSignal): Cancels a payment.
• refundPayment(paymentId: string, accessToken: string, signal?: AbortSignal): Refunds a payment.

authenticate

This method sends a request to the First Iraqi Bank's identity server, giving you necessary token and other related information to authenticate your next requests like creating or canceling a payment.

import { FIB } from "./fib.js"

const res = await FIB.authenticate()
const { access_token, expires_in } = await res.json()

access_token is the most important part of the response, since you need to pass it to the next request otherwise it'll fail with Authentication error!

[!IMPORTANT] Access tokens are designed to be short-lived, expires_in will tell you how many seconds you have until the access token expires, make sure to fetch a new access token before your next API call by calling authenticate as described above.

createPayment

This method sends a request to the First Iraqi Bank's server, creating a payment based on the provided information, which are parameters to function:

1. payment: an object with below possible properties:

   • amount: a number, indicating the payment's amount in IQD. Must be bigger than 250.

   • description (optional): a string used as description and might be shown to the customer when they try to pay in the FIB app.

   • expiresIn (optional): a Duration object indicating when the transaction expires, it must be:

     1. Bigger than 5 Minutes
     2. Smaller than 48 Hours

   • refundableFor (optional): a Duration object indicating till when the transaction can be refunded after it was paid, it must be:

     1. Bigger than 12 Hours
     2. Smaller than 7 Days

   • statusCallbackUrl (optional): an instance of URL class, this must be the URL of your backend and specifically of an endpoint that can accept POST request, as FIB backend will call this endpoint when the status of the transaction changes. Omit it if you're not interested.

2. accessToken: a previously fetched access token from authenticate method.

3. signal (optional): an AbortSignal that can use to abort the fetch request. Checkout Canceling a request on MDN for detailed explanation.

Example:

import { FIB } from "./fib.js"

const paymentInput = {
  amount: 1000, // amount in IQD
  description: "Payment for Order #12345",
  statusCallbackUrl: new URL("https://your.callback.url/status"),
  refundableFor: { days: 1 },
  expiresIn: { hours: 1 },
}

const authRes = await FIB.authenticate()
const { access_token } = await authRes.json()

const res = await FIB.createPayment(paymentInput, access_token)

This method returns a JSON response, that is the details of transaction that you just created, represented by Payment type:

• paymentId: a string indicating the id of the payment
• readableCode: a 12-character alpha-numeric string used to generate the qrCode property.
• qrCode: a URL-encoded PNG image that can be shown to the user to scan and pay the amount.
• validUntil: a string indicating until when this payment is valid.
• personalAppLink: a string representing the personal deep link that users can visit which automatically opens the payment details in the FIB app.
• businessAppLink: a string representing the personal deep link that users can visit which automatically opens the payment details in the FIB app.
• corporateAppLink: a string representing the personal deep link that users can visit which automatically opens the payment details in the FIB app.

[!TIP] Users can pay the amount either by scanning the QRCode, manually typing the readableCode or visiting the deep-links like personalAppLink, we recommend showing all 3 options to the user to make it more convenient for your users to fulfill the payment

Users might refresh your page, or close your application and come back, make sure you save the transaction details in your database as it contains information that can helpful to you or your customers later.

getPaymentStatus

When you generated a payment, you can use this method to retrieve information about the status of the payment, this provides details on when the payment is paid, or if its canceled then why and some other useful information:

import { FIB } from "./fib.js"

const authRes = await FIB.authenticate()
const { access_token } = await authRes.json()

const res = await FIB.getPaymentStatus(paymentId, accessToken)

cancelPayment

When a payment is created, you might want to cancel the payment for any reason, this can be done before he payment is fulfilled:

import { FIB } from "./fib.js"

const authRes = await FIB.authenticate()
const { access_token } = await authRes.json()

const res = await FIB.cancelPayment(paymentId, accessToken)

refundPayment

After a payment is fulfilled, it can be refunded depending on the refundableFor option you created the payment with:

import { FIB } from "./fib.js"

const authRes = await FIB.authenticate()
const { access_token } = await authRes.json()

const res = await FIB.refundPayment(paymentId, accessToken)

Types

PaymentInput

type PaymentInput = {
  amount: number
  description?: string
  statusCallbackUrl?: URL
  expiresIn?: Duration
  refundableFor?: Duration
}

PaymentResponse

type PaymentResponse = {
  paymentId: string
  readableCode: string
  qrCode: string
  validUntil: string
  personalAppLink: string
  businessAppLink: string
  corporateAppLink: string
}

PaymentStatusResponse

type PaymentStatusResponse = {
  paymentId: string
  amount: MonetaryValue
  status: "UNPAID" | "DECLINED" | "PAID" | "REFUNDED" | "REFUND_REQUESTED"
  paidAt?: string
  decliningReason?: "PAYMENT_CANCELLATION" | "PAYMENT_EXPIRATION"
  declinedAt?: string
  paidBy?: { name: string; iban: string }
}

Error Handling

There are two types of errors you might want to watch out for:

1. When the requests return a Response, but its not in 2xx range, in this case FIB backend returns an error message and some traceId, that we can inspect the request for you if the error is not expected.

   const res = await FIB.getPaymentStatus(paymentInput, accessToken)
   if(res.status !== 200){
     const { errors } = await res.json()
   }

2. When the request fails with an Error, which might happen for several reasons, for example a NetworkError or other runtime exceptions.

   try{
     const res = await FIB.getPaymentStatus(paymentInput, accessToken)
     const { status } = await res.json()
   
     return status
   }catch(error){
     console.log("Something went wrong", error)
     return null
   }

Contributing

If you encounter any bugs or issues while using the SDK, we encourage you to report them by filing an issue on our GitHub repository. Your feedback helps us improve the SDK.

Additionally, if during the discussion of an issue you feel that you can contribute a code change to resolve the problem, we warmly welcome your contributions. To do so, please submit a pull request with your proposed changes.