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 COP_BREB, the value of this parameter should be "COP_BREB".
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 COP_BREB, the value of this parameter should be "COP".
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.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., COP_CC).
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": "COP_BREB",
  "merchant_disbursement_id": "INV123456789",
  "disbursement_amount": 150000,
  "disbursement_currency": "COP",
  "account_details": {
      "account_number": "12345678901",
      "document_number": "1020304050",
      "document_type": "COP_CC"
  },
  "ipn_url": "https://example.com/ipn-handler",
  "customer_id": "USER12345",
  "customer_name": "John Doe",
  "customer_phone_number": "+573XXXXXXXXX",
  "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 account_details fields are mandatory. A request missing one, or sending a document_type outside the Supported Document Types list, is rejected.
• COP_BREB takes no bank_code. account_number, document_number and document_type are the whole of account_details.

Supported Document Types

Document Type	Description
COP_CC	Cédula de Ciudadanía (CC)
COP_TI	Tarjeta de Identidad (TI)
COP_CE	Cédula de Extranjería (CE)
COP_PASSP	Pasaporte (Passport)
COP_NIT	Número de Identificación Tributaria (NIT)