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 PEN_BANK_TRANSFER, the value of this parameter should be "PEN_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 PEN_BANK_TRANSFER, the value of this parameter should be "PEN".
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., PEN002).
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., PEN_DNI).
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": "PEN_BANK_TRANSFER",
  "merchant_disbursement_id": "INV123456789",
  "disbursement_amount": 5000,
  "disbursement_currency": "PEN",
  "account_details": {
      "account_number": "00219300123456789012",
      "bank_code": "PEN002", //Bank code
      "document_number": "45678912",
      "document_type": "PEN_DNI"
  },
  "ipn_url": "https://example.com/ipn-handler",
  "customer_id": "USER12345",
  "customer_name": "John Doe",
  "customer_phone_number": "+5198XXXXXXX",
  "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
PEN001	BBVA CONTINENTAL
PEN002	BANCO DE CREDITO
PEN003	INTERBANK
PEN004	SCOTIABANK PERU
PEN005	BANCO DE COMERCIO
PEN006	BANCO INTERAMERICANO DE FINANZAS
PEN007	CITIBANK
PEN008	MI BANCO
PEN009	BANCO GNB PERU
PEN010	BANCO FALABELLA
PEN011	BANCO RIPLEY
PEN012	SANTANDER
PEN013	BANCO DE LA NACION
PEN014	CAJA AREQUIPA
PEN015	CAJA MUNICIPAL DE AHORRO Y CREDITO CUZCO
PEN016	CAJA HUANCAYO
PEN017	CAJA METROPOLITANA DE LIMA
PEN018	CMAC ICA
PEN019	CAJA MUNICIPAL DE AHORRO Y CREDITO PIURA
PEN020	CAJA MUNICIPAL DE AHORRO Y CREDITO SULLANA
PEN021	CAJA TACNA
PEN022	CAJA TRUJILLO
PEN023	BANCO FINANCIERO
PEN024	CREDISCOTIA FINANCIERA
PEN025	ALFIN BANCO
PEN026	COMPARTAMOS FINANCIERA
PEN027	FINANCIERA OH
PEN028	FINANCIERA EFECTIVA
PEN029	FINANCIERA CONFIANZA
PEN030	DALE
PEN031	GLOBOKAS KASNET
PEN032	PAGO EFECTIVO
PEN033	WESTERN UNION
PEN034	AGENTE NIUBIZ
PEN035	RED DIGITAL
PEN036	BCP CUOTATEALO
PEN037	PAGOEFECTIVO QR
PEN038	PAGOEFECTIVO QR DIR
PEN039	BANCO PICHINCHA
PEN040	BANCO AZTECA
PEN041	BANCO CENCOSUD
PEN042	ICBC PERU BANK
PEN043	CAJA MAYNAS
PEN044	YAPE
PEN045	PLIN

Supported Document Types

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

Document Type	Description
PEN_DNI	Documento Nacional de Identidad (DNI)
PEN_CE	Carnet de Extranjería (CE)
PEN_PASSP	Pasaporte (Passport)
PEN_RUC	Registro Único de Contribuyentes (RUC)