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 MXN_BANK_TRANSFER, the value of this parameter should be "MXN_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 MXN_BANK_TRANSFER, the value of this parameter should be "MXN".
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 identifier code as required by the payment rail.
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": "MXN_BANK_TRANSFER",
  "merchant_disbursement_id": "INV123456789",
  "disbursement_amount": 5000,
  "disbursement_currency": "MXN",
  "account_details": {
      "account_number": "63818001014xxxxxxx",
      "bank_code": "MXN007" //Bank code
  },
  "ipn_url": "https://example.com/ipn-handler",
  "customer_id": "USER12345",
  "customer_name": "John Doe",
  "customer_phone_number": "+88017XXXXXXXX",
  "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.

Supported Banks​

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

Bank CodeBank Name
MXN001Banco de México
MXN002Banco Nacional de Comercio Exterior
MXN003Banco Nacional de Obras y Servicios Públicos
MXN004Banco del Ejército
MXN005Nacional Financiera
MXN006BaBien
MXN007Sociedad Hipotecaria Federal
MXN008Banco Nacional de México
MXN009BBVA México
MXN010Banco Santander México
MXN011HSBC México
MXN012Banco del Bajío
MXN013Banco Inbursa
MXN014Banco Mifel
MXN015Scotiabank México
MXN016Banco Regional de Monterrey
MXN017Banco Invex
MXN018Banco Bansi
MXN019Banco Afirme
MXN020Banco Mercantil del Norte
MXN021Bank of America México
MXN022MUFG Bank México
MXN023J.P. Morgan México
MXN024Banco Monex
MXN025Ve por Más
MXN026Credit Suisse México
MXN027Banco Azteca
MXN028Banco Autofin
MXN029Barclays México
MXN030Banco Compartamos
MXN031Banco Multiva
MXN032Actinver
MXN033Banco Intercam
MXN034Banco Coppel
MXN035ABC Capital
MXN036Consubanco
MXN037Volkswagen Bank México
MXN038Cibanco
MXN039BBASE
MXN040Bankaool
MXN041Pagatodo
MXN042Banco Inmobiliario Mexicano
MXN043Banco Donde
MXN044Banco Bancrea
MXN045Banco Covalto
MXN046ICBC México
MXN047Banco Sabadell México
MXN048Shinhan Bank México
MXN049Mizuho Bank México
MXN050Bank of China México
MXN051Banco S3
MXN052Monex Casa de Bolsa
MXN053GBM
MXN054Masari
MXN055Value
MXN056Vector
MXN057Finamex
MXN058Valmex
MXN059Profuturo
MXN060Intercam Casa de Bolsa
MXN061CI Casa de Bolsa
MXN062Fincomún
MXN063Nu México
MXN064STP
MXN065Credicapital
MXN066Kuspit
MXN067Unagra
MXN068ASP Integra OPC
MXN069Alternativos
MXN070Libertad
MXN071Caja Popular Mexicana
MXN072Cristóbal Colón
MXN073Caja de Ahorro de los Telefonistas
MXN074Transfer
MXN075Fondo (FIRA)
MXN076Invercap
MXN077Crediclub
MXN078Fompred
MXN079Tesored
MXN080Arcus
MXN081Nvio
MXN082Mercado Pago W
MXN083Cuenca
MXN084CLS
MXN085Indeval
MXN086CoDi Valida
MXN087Akala
MXN088Reforma
MXN089Tactiv Casa de Bolsa
MXN090Finterra
MXN091MexPago
MXN092albo
MXN093Fondeadora
MXN094Transfer
MXN095Spin by OXXO
MXN096Cartera Digital
MXN097Peibo
MXN098FINCO PAY
MXN099Evercore
MXN100Mexican-only Entity
MXN101CITI MEXICO
MXN102Banco del Ahorro Nacional y Servicios Financieros
MXN103Multiva Casa de Bolsa