Create Disbursement

The Create Disbursement API allows merchants to initiate a disbursement request. This process involves generating a disbursement ID that can be used to query the disbursement. Upon validation of request body information, the create disbursement request will be confirmed.

Endpoint

Request URL: https://apihit.net/api/disbursement/create

Request Headers

Header Name	Value
Content-Type	application/json
Accept	application/json
X-Signature	The HMAC signature used for verification.

Request Parameters

Property	Presence	Type	Description
mid	Mandatory	String	Provided by creedo during onboarding.
disbursement_method	Mandatory	String	This parameter indicates the method of disbursement. For BOB_BANK_TRANSFER, the value of this parameter should be "BOB_BANK_TRANSFER".
merchant_disbursement_id	Mandatory	String	Unique invoice number used on the merchant side for this specific disbursement. Max length is 25 characters. Special characters "<", ">" and "&" are not allowed.
disbursement_amount	Mandatory	Integer	Amount of the disbursement to be made.
disbursement_currency	Mandatory	String	Currency of the mentioned amount. For BOB_BANK_TRANSFER, the value of this parameter should be "BOB".
account_details	Mandatory.	Object	Contains beneficiary bank account details required for disbursement.
account_details.account_number	Mandatory	String	Beneficiary bank account number where Creedo will send the disbursement amount.
account_details.bank_code	Mandatory	String	Bank code from the Supported Banks list (e.g., BOB002).
account_details.document_number	Mandatory	String	Identity document number of the account holder.
account_details.document_type	Mandatory	String	Document type from the Supported Document Types list (e.g., BOB_CI).
ipn_url	Mandatory	String	URL where creedo sends Instant Disbursement Notification. It must accept POST request from creedo.
customer_id	Mandatory	String	Unique user ID on the merchant's side.
customer_name	Mandatory	String	Full name of the user on the merchant's side.
customer_phone_number	Mandatory	String	Registered phone number of the user on the merchant's side.
customer_email	Mandatory	String	Registered email address of the user on the merchant's side.
customer_ip	Mandatory	String	Current IP address of the user.
customer_type	Optional	String	Type of the user. Possible values: Trusted, FTD, MTD, YTD, Others.
btag	Optional	String	Btag identifier of the customer.
additional_info_1	Optional	String	Additional information.
additional_info_2	Optional	String	Additional information.

Success Response Parameters

Property	Type	Description
gateway_status	String	"accepted"
creedo_disbursement_id	String	Creedo-generated disbursement ID for this disbursement creation request. This disbursement ID can be used later to track the disbursement and in other disbursement-related APIs.

Error Response Parameters

Property	Type	Description
gateway_status	String	"rejected"
message	String	Error message here.

Signature Generation

The signature (X-Signature) is generated using HMAC with SHA-256. It uses the secret_key and a secret_string as inputs. All inputs should be in string format:

secret_string = mid:merchant_disbursement_id:disbursement_method:disbursement_currency:disbursement_amount

Request Body

POST /api/disbursement/create HTTP/1.1
Host: https://apihit.net
Content-Type: application/json
Accept: application/json
X-Signature: <hash_str>

{
  "mid": "CREEDO12345",
  "disbursement_method": "BOB_BANK_TRANSFER",
  "merchant_disbursement_id": "INV123456789",
  "disbursement_amount": 5000,
  "disbursement_currency": "BOB",
  "account_details": {
      "account_number": "1000123456",
      "bank_code": "BOB002", //Bank code
      "document_number": "1234567",
      "document_type": "BOB_CI"
  },
  "ipn_url": "https://example.com/ipn-handler",
  "customer_id": "USER12345",
  "customer_name": "John Doe",
  "customer_phone_number": "+5917XXXXXXX",
  "customer_email": "johndoe@example.com",
  "customer_ip": "192.168.1.1",
  "customer_type": "Trusted",  // Optional
  "btag": "BTAG001",  // Optional
  "additional_info_1": "Loyal customer",  // Optional
  "additional_info_2": ""  // Optional
}

Success Response

A successful response will return a JSON object containing:

{
  "gateway_status": "accepted",
  "creedo_disbursement_id": "3C8HL0MHX9"
}

Error Response

In case of an error, the API will return a JSON object with error details:

{
    "gateway_status": "rejected",
    "message": "Unknown error occurred."
}

Notes

• The merchant_disbursement_id must be unique for each transaction to prevent duplication.
• All four account_details fields are mandatory. A request missing one, or sending a document_type outside the Supported Document Types list, is rejected.
• There is no "other bank" fallback code. A bank that is not in the Supported Banks list cannot receive a disbursement.

Supported Banks

The value sent in account_details.bank_code must be one of the Bank Code values listed below.

Bank Code	Bank Name
BOB001	BANCO NACIONAL BOLIVIA
BOB002	BANCO MERCANTIL
BOB003	BANCO DE CREDITO
BOB004	BANCO DE NACION ARGENTINA
BOB005	BANCO BISA
BOB006	BANCO UNION
BOB007	BANCO ECONOMICO
BOB008	BANCO SOL
BOB009	BANCO GANADERO
BOB010	BANCO FIE S.A.
BOB011	BANCO FORTALEZA
BOB012	PANAMERICAN SAFI
BOB013	CIDRE IFD
BOB014	CRACER IFD
BOB015	DIACONIA IFD
BOB016	FUNDACION BOLIVIANA PARA EL DESARROLLO IFD
BOB017	IDEPRO IFD
BOB018	PRO MUJER IFD
BOB019	COOPERATIVA JESUS NAZARENO
BOB020	COOPERATIVA SAN MARTIN DE PORRES
BOB021	COOPERATIVA FATIMA
BOB022	COOPERATIVA LA MERCED
BOB023	COOPERATIVA DE AHORRO Y CREDITO ABIERTA PIO X R.I
BOB024	COOPERATIVA QUILLACOLLO
BOB025	COOPERATIVA SAN JOSE DE PUNATA
BOB026	COOPERATIVA SAN MATEO
BOB027	COOPERATIVA CACEF
BOB028	COOPERATIVA MAGISTERIO RURAL DE CHUQUISACA
BOB029	LINKSER S.A
BOB030	ADMINISTRADORA DE TARJETAS DE CREDITO S.A
BOB031	EFECTIVO S.A
BOB032	BANCO PYME ECOFUTURO
BOB033	BANCO PYME DE LA COMUNIDAD
BOB034	LA PROMOTORA EFV
BOB035	BANCO CENTRAL DE BOLIVIA - MLD
BOB036	BANCO CENTRAL DE BOLIVIA - COMPRA DE BONUS
BOB037	COOP AHO Y CRED ABIERTA SAN PEDRO LTDA.
BOB038	COOPERATIVA DE AHORRO Y CREDITO ABIERTA EL CHOROLOQUE R.I
BOB039	COOP AHO Y CRED ABIERTA INCA HUASI LTDA
BOB040	COOP AHO Y CRED COMARAPA R.I
BOB041	LA PRIMERA ENTIDAD FINANCIERA DE VIVIENDA
BOB042	EL PROGRESO ENTIDAD FINANCIERA DE VIVIENDA
BOB043	YAPE

Supported Document Types

The value sent in account_details.document_type must be one of the Document Type values listed below.

Document Type	Description
BOB_CI	Cédula de Identidad (CI)
BOB_PASSP	Pasaporte (Passport)
BOB_NIT	Número de Identificación Tributaria (NIT)