Skip to main content
Version: v3.0

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 NameValue
Content-Typeapplication/json
Acceptapplication/json
X-SignatureThe HMAC signature used for verification.

Request Parameters​

PropertyPresenceTypeDescription
midMandatoryStringProvided by creedo during onboarding.
disbursement_methodMandatoryStringThis parameter indicates the method of disbursement. For COP_BANK_TRANSFER, the value of this parameter should be "COP_BANK_TRANSFER".
merchant_disbursement_idMandatoryStringUnique invoice number used on the merchant side for this specific disbursement. Max length is 25 characters. Special characters "<", ">" and "&" are not allowed.
disbursement_amountMandatoryIntegerAmount of the disbursement to be made.
disbursement_currencyMandatoryStringCurrency of the mentioned amount. For COP_BANK_TRANSFER, the value of this parameter should be "COP".
account_detailsMandatory.ObjectContains beneficiary bank account details required for disbursement.
account_details.account_numberMandatoryStringBeneficiary bank account number where Creedo will send the disbursement amount.
account_details.bank_codeMandatoryStringBank code from the Supported Banks list (e.g., COP004).
account_details.document_numberMandatoryStringIdentity document number of the account holder.
account_details.document_typeMandatoryStringDocument type from the Supported Document Types list (e.g., COP_CC).
ipn_urlMandatoryStringURL where creedo sends Instant Disbursement Notification. It must accept POST request from creedo.
customer_idMandatoryStringUnique user ID on the merchant's side.
customer_nameMandatoryStringFull name of the user on the merchant's side.
customer_phone_numberMandatoryStringRegistered phone number of the user on the merchant's side.
customer_emailMandatoryStringRegistered email address of the user on the merchant's side.
customer_ipMandatoryStringCurrent IP address of the user.
customer_typeOptionalStringType of the user. Possible values: Trusted, FTD, MTD, YTD, Others.
btagOptionalStringBtag identifier of the customer.
additional_info_1OptionalStringAdditional information.
additional_info_2OptionalStringAdditional information.

Success Response Parameters​

PropertyTypeDescription
gateway_statusString"accepted"
creedo_disbursement_idStringCreedo-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​

PropertyTypeDescription
gateway_statusString"rejected"
messageStringError 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_BANK_TRANSFER",
  "merchant_disbursement_id": "INV123456789",
  "disbursement_amount": 150000,
  "disbursement_currency": "COP",
  "account_details": {
      "account_number": "12345678901",
      "bank_code": "COP004", //Bank code
      "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.
  • There is no "other bank" fallback code. A bank that is not in the Supported Banks list cannot receive a disbursement.
  • COP_BREB, the other COP disbursement method, takes no bank_code at all.

Supported Banks​

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

Bank CodeBank Name
COP001Banco de Bogotá
COP002Banco Popular
COP003Itaú
COP004Bancolombia
COP005Citibank
COP006Banco GNB Sudameris
COP007BBVA Colombia
COP008Scotiabank Colpatria
COP009Banco de Occidente
COP010Bancóldex
COP011Banco Caja Social (BCSC)
COP012Banco Agrario
COP013Banco Mundo Mujer
COP014Banco Davivienda
COP015Banco AV Villas
COP016Banco W
COP017Banco de las Microfinanzas Bancamía
COP018Banco Pichincha
COP019Bancoomeva
COP020Banco Falabella
COP021Banco Finandina
COP022Banco Santander de Negocios
COP023Banco Cooperativo Coopcentral
COP024Banco Serfinanza
COP025Financiera Juriscoop
COP026Cootrafa Cooperativa Financiera
COP027Confiar Cooperativa Financiera
COP028Coltefinanciera
COP029Nequi
COP030Daviplata
COP031Mibanco
COP032Lulo Bank
COP033Banco JP Morgan Colombia
COP034Dale
COP035Asopagos
COP036Cooperativa Financiera de Antioquia
COP037JFK Cooperativa Financiera
COP038Coofinep Cooperativa Financiera
COP039Banco Unión
COP040Ban100
COP041PiBank
COP042Iris
COP043Movii
COP044Ding Tecnipagos
COP045Powwi
COP046Ualá
COP047Banco BTG Pactual
COP048Bold CF
COP049Nu Colombia
COP050RappiPay
COP051Coink
COP052Santander Consumer
COP053Global66
COP054Alianza Fiduciaria
COP055Crezcamos
COP056Banca de Inversión Bancolombia
COP057Banco Credifinanciera
COP058Compañía de Financiamiento Tuya
COP059Corporación Financiera Colombiana
COP060Credifamilia
COP061Financiera de Desarrollo Nacional
COP062Findeter
COP063Fogafin
COP064Fondo Nacional de Garantías
COP065Fondo Nacional del Ahorro
COP066Finagro
COP067GM Financial Colombia
COP068Instituto Crédito Exterior
COP069Banco Multibank

Supported Document Types​

Document TypeDescription
COP_CCCédula de Ciudadanía (CC)
COP_TITarjeta de Identidad (TI)
COP_CECédula de Extranjería (CE)
COP_PASSPPasaporte (Passport)
COP_NITNúmero de Identificación Tributaria (NIT)