Jibit Transferor REST API Documentation

Version 2.1
9th of February 2022

Ivan Rayan Payam, Jibit

CONFIDENTIAL - Copyright© 2021 Jibit (Ivan Rayan Payam), Iran.
This document was prepared by Jibit team and may not be used for other
purposes, or disclosed to other parties without the written permission of Jibit.
Table of Contents

Introduction Page 4

Error Handling Mechanism Page 5

Getting Access Token Page 6

Refreshing Access Token Page 7

Getting Balances List Page 8

Submit Batch Request Page 9

Inquiry Batch/Transfer Page 12

Cancel Batch/Transfer Page 15

Retry Batch/Transfer Page 16

Transfers Filtering Page 17

Enable/Disable Public Receipt Link Page 18

List of Supported Normal Transfers Banks Page 19

List of Currently Active Normal Transfers Banks Page 20

Batch Generator Helper API Page 21

Banks Identifiers Table Page 22

Jibit Transferor Project API Page 2

Versioning Information

Versioning Information

Version Date Note

2 20th of October 2021 New Version

Adding “Enable/Disable Public Receipt Link”
Adding “Batch Generator Helper API”
2.1 9th of February 2022
improving “Submit Batch Request”
Improving “Banks Identifiers Table”

Jibit Transferor Project API Page 3

Introduction

This document explains the API details of the Jibit's transferor project that provides
money transfer services based on standard mechanisms like ACH, Normal and
RTGS.

Base URL

This service's base URL is https://napi.jibit.ir/trf. Please contact with our customer
support for service activation. For using this service you should provide one or
more IP addresses, and we will restrict your access to services only by addresses
you provided.

Jibit Transferor Project API Page 4

Error Handling Mechanism

In any unsuccessful endpoint call (4xx and 5xx http status codes) the response is a
JSON content with the form of

"fingerprint": "825767e0-0522-11ec-bd3e-13d2e7dad3fe",

"errors": [

"code": "handler.not_found",

"message": "handler not found"

The fingerprint helps us to track the exact problem internally. The errors array
contains a list of errors occurred;
including a `code` that indicates machine and human-readable error code, and
`message` that is a human-readable reason for tracking purposes.

Jibit Transferor Project API Page 5

Getting Access Token

In order to authenticate with service and get access token you should use this
endpoint.

POST /v2/tokens/generate (With base URL: https://napi.jibit.ir/trf/v2/tokens/generate)

Request Headers
Parameter Type Description
Content-Type application/json

Request Body
Field Type Description
the API key received from dashboard, or was sent using
apiKey string
email

the secret key received from dashboard, or was sent using

secretKey string
email

Response Body
Field Type Description

accessToken string bearer type access token, valid for 24 hours

refreshToken string refresh token, valid for 48 hours

Possible Error Codes

• invalid.request_body
• apiKey.is_required
• apiKey.invalid_length
• secretKey.is_required
• secretKey.invalid_length
• invalid.credentials
• server.error

Jibit Transferor Project API Page 6

Refreshing Access Token

The returned access token on previous step is only valid for 24 hours, you should
provide an internal mechanism to refresh access token periodically using some
scheduler for example.

POST /v2/tokens/refresh

Request Headers
Parameter Type Description
Content-Type application/json

Request Body
Field Type Description

accessToken string access token, even if expired

refreshToken string valid refresh token, refresh tokens are valid for 48 hours

Response Body
Field Type Description

accessToken string bearer type access token, valid for 24 hours

refreshToken string refresh token, valid for 48 hours

Possible Error Codes

• invalid.request_body
• accessToken.is_required
• refreshToken.is_required
• refreshToken.not_valid
• invalid.tokens_pair
• client.not_found
• server.error

Jibit Transferor Project API Page 7

Getting Balances List

Using this API you can see your wallets, including the wallet that is used for
transferring money from.

GET /v2/balances

Request Headers
Parameter Type Description
Bearer
Authorization
accessToken

Response Body
Field Type Description
balance long main wallet balance

settleableBalance long settleable wallet balance

balances Balance[] an array of different balance types

Balance
Field Type Description

balanceType string balance type, exp. WLT or TRF

currency string currency of a specific balance type

amount long the amount in current balance type

Possible Error Codes

• invalid.request_body
• forbidden
• server.error

Jibit Transferor Project API Page 8

Submit Batch Request (1/3)

In order to transfer money from your settleable wallet to any valid IBAN, you can
use this endpoint.
Submit batch request can be used to transfer a batch (Including at least one item)
and in two different modes:

• BATCH mode: The requested batch should be accepted in whole, we mean all
or nothing.
• TRANSFER mode: The requested batch should be processed in one by one
manner; we try to select from start of batch and submit transfer items while
you have enough settleable balance. All rejected transfers will return back to
you in API response.

POST /v2/transfers

Request Headers
Parameter Type Description
Content-Type application/json
Bearer
Authorization
accessToken

Request Body
Field Type Description
batch identifier, it is recommended to use unique batch ids
batchID string
for each batch

submissionMode string BATCH or TRANSFER

transfers Transfer[] an array of transfers (we say this a batch)

Jibit Transferor Project API Page 9

Submit Batch Request (2/3)

Transfer
Field Type Description
transferID string unique transfer identifier

optional transfer mode of ACH, NORMAL or RTGS. default is

transferMode string
ACH

destination string destination IBAN

optional destination first name, if not provided it will be

destinationFirstName string
filled by provided IBAN's information

optional destination last name, if not provided it will be

destinationLastName string
filled by provided IBAN's information

amount long amount of money to transfer

currency string IRR, RIALS or TOMAN

description string description of transfer that will be sent to bank

optional metadata (For example in JSON format) for your

metadata string
internal use

optional URL for notification use; see Batch Inquiry API to

notifyURL string
see what is POST into this URL

optional; if provided we will hold this transfer for 1 hour

cancellable boolean
before sending to banks, default is true

optional; required if you want to assign a payment identifier

paymentID string
for this transfer when sending to bank

Response Body
Field Type Description
number of items of batch submitted, in submission mode of
submittedCount int
TRANSFER it may be less than batch size

totalAmountTransferred long total amount of items of batch submitted in IRR or RIALS

rejections Transfer[] an array of rejected transfer item

Jibit Transferor Project API Page 10

Submit Batch Request (3/3)

Possible Error Codes

• forbidden
• invalid.request_body
• batchID.invalid_length
• submissionMode.not_valid
• transfers.invalid_length
• transfers.i.transferID.invalid_length (ith item in batch has issue)
• transfers.i.destination.not_valid
• transfers.i.source_bank.not_supported
• transfers.i.destinationFirstName.invalid_length
• transfers.i.destinationLastName.invalid_length
• transfers.i.amount.not_enough_for_ach
• transfers.i.amount.exceeded_maximum_for_ach
• transfers.i.amount.not_enough_for_normal
• transfers.i.amount.exceeded_maximum_for_normal
• transfers.i.currency.not_valid
• transfers.i.description.invalid_length
• transfers.i.metadata.invalid_length
• transfers.i.notifyURL.invalid_length
• transfers.i.notifyURL.not_valid
• transfers.i.paymentID.invalid_length
• transfers.i.paymentID.not_valid
• balances.not_enough
• transfer.already_exists
• server.error

Jibit Transferor Project API Page 11

Inquiry Batch/Transfer (1/3)

Using this API you are able to inquiry a batch or any item in batch to check transfer
status.

GET /v2/transfers?batchID=exampleBatchID

GET /v2/transfers?transferID=exampleTransferID

GET /v2/transfers?batchID=exampleBatchID&transferID=exampleTransferID

Request Headers
Parameter Type Description
Bearer
Authorization
accessToken

Response Body
Field Type Description
batchID string

transfers Transfer[] array of transfers (we say this a batch)

Jibit Transferor Project API Page 12

Inquiry Batch/Transfer (2/3)
Transfer
Field Type Description
transferID string

transferMode string

destination string

destinationFirstName string

destinationLastName string

amount long

currency string

description string

metadata string

notifyURL string

cancellable boolean

paymentID string

bankTransferID string the identifier of transfer in bank

one of INITIALIZED, CANCELLING, CANCELLED, IN_PROGRESS,

state string
TRANSFERRED, FAILED

reason of FAILED state, it is a machine readable code like

failReason string
destination.not.found

feeCurrency string IRR

feeAmount long amount of fee for this transfer

standard UTC format based on RFC1123. exp 2021-10-

createdAt string
10T20:10:30.904062Z

standard UTC format based on RFC1123. exp 2021-10-

modifiedAt string
10T20:10:30.904062Z

Jibit Transferor Project API Page 13

Inquiry Batch/Transfer (3/3)

Possible Error Codes

• invalid.request_body
• forbidden
• batchID_or_transferID.is_required
• transfer.not_found
• server.error

Jibit Transferor Project API Page 14

Cancel Batch/Transfer

Using this API you are able to cancel a batch or any item in batch. This API only
works for cancellable transfer items.

DELETE /v2/transfers?batchID=exampleBatchID

DELETE /v2/transfers?transferID=exampleTransferID

DELETE /v2/transfers?batchID=exampleBatchID&transferID=exampleTransferID

Request Headers
Parameter Type Description
Bearer
Authorization
accessToken

Possible Error Codes

• invalid.request_body
• forbidden
• batchID_or_transferID.is_required
• transfer.not_found
• cancellation.failed
• cancellation.not_applicable
• server.error

Jibit Transferor Project API Page 15

Retry Batch/Transfer

Using this API you are able to retry a failed batch or any failed item in batch. This
API only works for previously failed transfer items.

PATCH /v2/transfers?batchID=exampleBatchID

PATCH /v2/transfers?transferID=exampleTransferID

PATCH /v2/transfers?batchID=exampleBatchID&transferID=exampleTransferID

Request Headers
Parameter Type Description
Content-Type application/json
Bearer
Authorization
accessToken

Request Body
Field Type Description
state string set this to RETRY

Possible Error Codes

• invalid.request_body
• forbidden
• batchID_or_transferID.is_required
• transfer.not_found
• retry.failed
• retry.not_applicable
• server.error

Jibit Transferor Project API Page 16

Transfers Filtering

Using this API you are able to filter all submitted transfers by providing some
information.

GET /v2/transfers/filter

Request Headers
Parameter Type Description
Bearer
Authorization
accessToken

Query Parameters
Field Type Description
state string optional; if not specified we will return all transfers

optional; standard UTC format based on RFC1123. exp

from string
2021-10-10T20:10:30.000000Z

optional; standard UTC format based on RFC1123. exp

to string
2021-10-10T21:10:30.000000Z

page string page number, must be greater than 0

size string must be greater than 0 and less than or equal to 250

Possible Error Codes

• invalid.request_body
• forbidden
• page.not_valid
• size.not_valid
• server.error

Jibit Transferor Project API Page 17

Enable/Disable Public Receipt Link

Using this API you are able to enable or disable a publicly available receipt link for a
batch/transfer.
This public link will be available for one hour by default, and automatically will be
disabled after this period.
This one hour can be increased or decreased based on your request (Contact with
Jibit customer support).

POST /v2/receipts

Request Headers
Parameter Type Description
Bearer
Authorization
accessToken

Request Body
Field Type Description
batchID string optional batch identifier

optional transfer identifier, however one of batchID or

transferID string
transferID is required

newEnablementStatus string true to enable public link and false to disable

Response Body
Field Type Description
publicLink string publicly generated link

Possible Error Codes

• invalid.request_body
• Forbidden
• batchID_or_transferID.is_required
• transfer.not_found
• server.error

Jibit Transferor Project API Page 18

List of Supported Normal Transfers Banks

Using this API you are able to fetch the list of supported normal transfers banks.

GET /v2/banks/normal

Request Headers
Parameter Type Description
Bearer
Authorization
accessToken

Response Body
Field Type Description
string[] an array of swift codes of supported banks

Possible Error Codes

• invalid.request_body
• forbidden
• server.error

Jibit Transferor Project API Page 19

List of Currently Active Normal Transfers Banks

Using this API you are able to fetch the list of currently active normal transfers
banks.

GET /v2/banks/status

Request Headers
Parameter Type Description
Bearer
Authorization
accessToken

Response Body
Field Type Description
string[] an array of swift codes of currently active banks

Possible Error Codes

• invalid.request_body
• forbidden
• server.error

Jibit Transferor Project API Page 20

Batch Generator Helper API
This API helps you automatically generate batches to be sent for Submit Batch
Request API.

POST /v2/batch/generate

Request Headers
Parameter Type Description
Bearer
Authorization
accessToken

Request Body
Field Type Description
submissionMode string optional; BATCH or TRANSFER; BATCH is default value

transferMode string one of ACH, NORMAL or RTGS

destination string destination IBAN

amount of money to transfer, for amounts greater than 50

amount long
million toman, it will be split automatically

currency string IRR, RIALS or TOMAN

description string optional

metadata string optional

notifyURL string optional

cancellable boolean optional

paymentID string optional

Response Body
Response body of this API will be an automatically generated request body for
Submit Batch Request API.
Possible Error Codes
• invalid.request_body
• Forbidden
• batchID_or_transferID.is_required
• transfer.not_found
• server.error

Jibit Transferor Project API Page 21

Banks Identifiers Table (1/2)

Identifier Swift Code Official Name Official Website

Central Bank of the Islamic Republic

MARKAZI BMJIIR www.cbi.ir
of Iran

SANAT_VA_MADAN BOIMIR Bank of Industry & Mine www.bim.ir

MELLAT BKMTIR Bank Mellat www.bankmellat.ir

REFAH REFAIR Refah K. Bank www.refah-bank.ir

MASKAN BKMNIR Bank Maskan www.bank-maskan.ir

SEPAH SEPBIR Bank Sepah www.banksepah.ir

KESHAVARZI KESHIR Bank Keshavarzi Iran www.bki.ir

MELLI MELIIR Bank Melli Iran www.bmi.ir

TEJARAT BTEJIR Tejarat Bank www.tejaratbank.ir

SADERAT BSIRIR Bank Saderat Iran www.bsi.ir

TOSEAH_SADERAT EDBIIR Export Development Bank of Iran www.edbi.ir

POST PBIRIR Post Bank Iran www.postbank.ir

TOSEAH_TAAVON TTBIIR Tose'e Ta'avon Bank www.ttbank.ir

TOSEAH BTOSIR Tosse Credit Institution www.cid.ir

KARAFARIN KBIDIR Karafarin Bank www.karafarinbank.ir

PARSIAN BKPAIR Parsian Bank www.parsian-bank.ir

EGHTESAD_NOVIN BEGNIR Bank Eghtesad Novin www.enbank.ir

SAMAN SABCIR Saman Bank www.sb24.ir

PASARGAD BKBPIR Bank Pasargad www.bpi.ir

SARMAYEH SRMBIR Sarmayeh Bank www.sbank.ir

SINA SINAIR Sina Bank www.sinabank.ir

MEHR_IRANIAN MEHRIR Gharzolhasane Mehr Iran Bank www.qmb.ir

SHAHR CIYBIR Shahr Bank www.shahr-bank.ir

Jibit Transferor Project API Page 22

Banks Identifiers Table (2/2)

Identifier Swift Code Official Name Official Website

AYANDEH AYBKIR Ayandeh Bank www.ba24.ir

GARDESHGARI TOSMIR Tourism Bank www.tourismbank.ir

DAY DAYBIR Day Bank www.bank-day.ir

IRANZAMIN IRZAIR Iran Zamin Bank www.izbank.ir

RESALAT RESBIR Resalat Gharzolhasane Bank www.rqbank.ir

MELAL MELLIR Melal Credit Institution www.melalbank.ir

www.middleeastban
KHAVARMIANEH KHMIIR Middle East Bank
k.ir

NOOR NOORIR Noor Credit Institution www.noorbank.ir

IRAN_VENEZUELA IVBBIR Iran-Venezuela BiNational Bank www.ivbb.ir

UNKNOWN - -

Jibit Transferor Project API Page 23

 Ivan Rayan Payam, Jibit
Address: 1st Floor, Number 3, Pirooz Dead-End, Jordan (Nelson Mandela) Street, Tehran, Iran
Website: www.jibit.ir | Email: [email protected] | Telephone: +98 21 42296