hola.cash eCommerce API (1.0.0)

API de hola.cash.

Soporta:
- Tokenización: Crea y obtiene tokens de pago para tarjetas de crédito y débito.
- Transacción: Cargos, capturas, reembolsos y obtiene pagos.
- Orden: Crea y obtiene órdenes.
- Checkout: Obtiene el botón de pago para invocar el Checkout Widget desde tu App o página web.

Detalles de los códigos de error regresados por la API dentro del objeto StatusDetail en detail.code

Lista de códigos de error

Código de error	Descripción
success	Operación exitosa
generic_error	Ha ocurrido un error
invalid_response	Ha ocurrido un error inesperado
unauthorized	No cuentas con autorización para acceder a este recurso
validation_error	Hemos encontrado errores de validación en la petición
action_required	Información adicional requerida
new_cvv_required	Se requiere un nuevo valor de CVV
blocked_by_hola_cash_fraud_detection	Esta acción fue bloqueada por el motor de detección de fraude de hola.cash
transaction_blocked	No hemos podido completar la transacción (blk)
invalid_security_credentials	Las credenciales no son válidas
invalid_anti_fraud_header_multiple	Encontramos múltiples headers de anti-fraud. Por favor solo manda uno
invalid_anti_fraud_header_format	Formato inválido en el encabezado de antifraude, este tiene que ser un objeto JSON convertido a una cadena de caracteres en base64
invalid_anti_fraud_header_missing_ip_address	Encabezado de antifraude inválido, falta incluir ip_address
invalid_anti_fraud_header_missing_device_id	Encabezado de antifraude inválido, falta incluir device_id
invalid_anti_fraud_header_missing_user_timezone	Encabezado de antifraude inválido, falta incluir user_timezone
invalid_anti_fraud_header_invalid_user_timezone	Formato inválido para user_timezone en el encabezado antifraude
invalid_anti_fraud_header_invalid_ip_address	Formato inválido para ip_address en el encabezado antifraude
bank_account_clabe_unrecognizable	Cuenta CLABE inválida
bank_account_clabe_already_exists	Esta cuenta CLABE se encuentra en uso
bank_account_clabe_associated_with_hola_cash	Esta cuenta CLABE no puede ser usada en hola.cash
bank_account_clabe_not_supported_spei_with_hola_cash	Esta cuenta CLABE no puede ser usada en hola.cash
transaction_not_owned_by_cashuser	No eres dueño de estra transacción
transaction_already_completed	Transacción previamente completada
transaction_needs_more_information_to_complete	Se necesita más información para completer esta transacción
transaction_data_mismatch	No se pudo encontrar esta transacción
transaction_pending_information_missing	Transacción pendiente con información faltante
transaction_version_mismatch	Versión inválida
transaction_tid_invalid	Transacción inválida
transaction_pin_required	Se necesita el PIN para la transacción
transaction_already_cancelled_or_completed	No existen más acciones para esta transacción, ya fue cancelada o completada
p2m_target_subaccount_not_open	Comercio no válido
p2m_subaccount_not_verified	Configuración de la subcuenta no verificada
p2m_subscription_not_created	Subcripción no creada
p2m_merchant_payment_disabled	Pago no válido para este comercio
p2m_merchant_is_cash_merchant	Configuración del comercio inválida
payment_method_not_allowed	Método de pago no aceptado
transaction_not_valid_capture_target	No se puede capturar este cargo
transaction_capture_amount_greater_than_transaction_amount	No se puede ingresar un monto mayor a la cantidad ingresada en la transacción original
transaction_not_valid_capture_target_already_captured	El cargo ya fue capturado
transaction_not_valid_capture_target_already_settled	El cargo ya fue procesado
transaction_not_valid_capture_target_no_funds_to_capture	No se puede procesar porque no se cuenta con fondos para capturar la transación
transaction_not_valid_capture_target_was_refunded	El cargo ya fue reembolsado.
transaction_not_valid_refund_target_no_funds_to_refund	No existen fondos para reembolsar
transaction_not_valid_refund_target_has_chargeback	La transacción no puede ser reembolsada, está asociada a un contra cargo
transaction_not_valid_refund_target_payment_method_type_not_supported_for_refunds	El método de pago no permite reembolsos
transaction_not_valid_refund_target_transaction_created_date_invalid	La transacción excedió el tiempo máximo para realizar reembolso.
transaction_not_valid_refund_target_subaccount_transacting_user_does_not_exists	El transactiong_user de este subaccount no existe
transaction_not_valid_capture_target_payment_method_type_not_supported_for_captures	El método de pago no permite capturas.
amount_limit_exceeded	Tu transacción ha fallado. Te recomendamos revisar el monto permitido por tu banco para comprar e intentar nuevamente
codi_transaction_blocked	El cobro digital por CODI ha fallado. No olvides que CODI te permite utilizar montos pequeños en tus pagos, te recomendamos revisar la información e intentar nuevamente
credit_card_expired_year	La fecha que ingresaste de tu método de pago expiró. Te recomendamos revisar la información e intentar nuevamente
credit_card_expired_month	La fecha que ingresaste de tu método de pago expiró. Te recomendamos revisar la información e intentar nuevamente
incorrect_pin	Los datos que ingresaste están incompletos o erróneos. Te recomendamos revisar la información e ingresar todos los campos correspondientes
credit_card_number_invalid	El número de tarjeta que ingresaste es inválido. Te recomendamos revisar la información e intentar nuevamente
credit_card_expired	El método de pago seleccionado a expirado. te recomendamos revisar la información e intentar nuevamente
credit_card_validation_code_required	El código de seguridad (CVV) es requirido. Por favor ingrésalo e intenta de nuevo
test_credit_card	Esta es una tarjeta de pruebas. Por favor usa una tarjeta real
credit_card_validation_code_invalid	El código de seguridad (CVV) ingresado es inválido. Por favor ingresa una válido e intenta de nuevo
three_ds_authentication_failed	La autenticación 3DS falló. Por favor intenta de nuevo con los datos correctos
credit_card_insufficient_funds	La tarjeta no tiene fondos suficientes. Por favor agrégale fondos o intenta con otra tarjeta
credit_card_stolen	La tarjeta ha sido identificada como una tarjeta robada
credit_card_fraud_detected	Esta transacción fue bloqueada por el motor de detección de fraude de hola.cash
credit_card_purchase_not_supported	Tu banco declinó esta transacción, te recomendamos contactarle para entender el motivo
credit_card_not_supported_on_line	Recuerda habilitar los pagos digitales/online en tus métodos de pago, te recomendamos conactar a tu banco para obtener más información
credit_card_lost	La tarjeta fue reportada como perdida
credit_card_restricted_by_bank	El banco ha restringido la tarjeta
credit_card_hold_card	El banco ha solicitado que la tarjeta sea retenida. Te recomendamos comunicarte con ellos para recibir más información
credit_card_call_bank_to_authorize	Se requiere solicitar al banco autorización para realizar este pago
refund_failed_retry_after_24_hour	El reembolso falló. Por favor intenta en 24 horas.
temporary_error_try_again_later	Ha ocurrido un error momentáneo, por favor intenta nuevamente
card_declined	El método de pago que utilizaste ha sido declinado por tu banco. Te recomendamos comunicarte con ellos para recibir más información
order_not_found	La orden solicitada no existe
payment_token_not_valid	El token de pago es inválido
card_amount_high	Ingresa un monto menor para esta compra e intenta nuevamente
card_amount_low	Ingresa un monto mayor para esta compra e intenga de nuevo
data_issues_contact_hola_cash	Esta transacción tiene problemas relacionados a los datos que ingresaste. Por favor ponte en contacto con nuestro departamento de suporte de hola.cash para solucionar este problema
merchant_email_address_already_exists	Ya existe un comercio asignado a este correo
merchant_phone_number_already_exists	Ya existe un comercio asignado a este número de teléfono
merchant_address_is_required	Se necesita una dirección para este comercio
invalid_merchant_category	Categoría de comercio inválida
merchant_username_already_exists	Ya existe un comercio asignado a este nombre de usuario
merchant_generic_validation_error	Se encontraron errores de validación en el registro del comercio
create_processor_account_failed_retry	La transacción falló. Por favor intenta de nuevo en unos minutos
funds_transfer_not_supported	Tu banco no soporta esta operación
card_withdrawal_limit_exceeded	Tu banco declinó la transacción debido a que se ha excedido el límite de retiro
issuer_not_supported	Tu banco no soporta el banco emisor de la tarjeta
card_already_register_with_user	Esta tarjeta no se puede usar para esta transacción. Utilice otra tarjeta por favor
invalid_card_expiry	La fecha de expiración de esta tarjeta no es válida. Por favor revise la información
3D_authentication_failed	La autenticación 3DS falló. Por favor intenta de nuevo o intenta con otra tarjeta o método de pago
user_not_allowed_to_perform_transaction	No tienes permiso para realizar esta acción
cash_token_not_found	El token solicitado no existe
service_error	Error en el servicio
order_is_required	El hola.cash order id es requerido para usar el processing_instruction use_order_payment_detail como True
payment_detail_is_required	Para crear el cargo debe pasar el campo payment_detail y customer_details
order_payment_detail_and_customer_details_are_required	La order hola.cash proporcionada debe detener el campo payment_detail y customer_details para poder ejecutar el cargo
order_already_associated_with_charge	La orden proporcionada ya fue asociada previamente a un cargo existente
continuation_not_found	The external reference id is not found.
invalid_query_param	El parámetro de consulta provisto en la llamada al API no es válido
merchant_sub_account_does_not_exist	El comerciante proporcionado no tiene una subcuenta asociada
merchant_does_not_exist	El comerciante proporcionado no existe
limit_out_of_bounds	Los límites provistos en los parámetros de consulta no son válidos
integrity_or_database_issue	Hubo un error al ejecutar la consulta, asegúrate de que los parámetros de consulta sean correctos
invalid_cursor_after_or_before	El parámetro de consulta `after_id` o `before_id` ser una cadena en base64
after_id_and_before_id_both_present	Asegurate de sólo enviar uno de los siguientes parámetros de consulta [after_id, before_id]

Authentication

clientKey

Este es un valor secreto para la identificación del cliente. El sistema soporta llaves privadas y llaves públicas. Una llave pública comienza con pub_ y una llave privada con skt_. - La llave pública del cliente es también llamada public key . Esta es utilizada en escenarios de tokenización y cargos, cuando estos ocurren en una página web o desde una app. En estos escenarios nunca se debe de poner la llave privada. Se pueden generar más llaves públicas usando la API de authentication - La llave privada del cliente, también llamada private key debe de ser guardada de una forma segura en tu servidor donde hagas las llamadas a la HolaCash API.

Security Scheme Type	API Key
Header parameter name:	X-Api-Client-Key

clientPublicKeyInQueryString

La llave pública que se manda como un parámetro en las consultas.

Security Scheme Type	API Key
Query parameter name:	public_key

sessionToken

El token de sesión es obtenido usando la API de autentificación.

Security Scheme Type	API Key
Header parameter name:	X-Session-Token

tokenization

Crea y obtiene un token de pago para una tarjeta de crédito, este token es utilizado para crear un Cargo. Crea un token de pago desde tu aplicación Web o App para que no mandes información del pago a tus servidores. Usa estas tarjetas de pruebas para desencadenar diferentes flujos en su integración y asegúrate de manejarlos correctamente. Nota: Usa una llave pública en el header X-Api-Client-Key de la petición. Nunca expongas o hagas visible la llave privada.

Crea un token dadas unas credenciales de pago.

Genera un token de pago para tarjetas de crédito o débito, este token lo puedes almacenar en tu sistema y así completar una o varias transacciones. Debes usar solamente una public_key (llave pública) para consumir esta API. Regresaremnos un error si utilizas una secret_key.

Request

Security:

clientKey or sessionToken

header Parameters

X-Cash-Anti-Fraud-Metadata

string

Usado para mandar información al sistema para combatir fraude. Lo datos mandados en el encabezado es una estrucutra de tipo JSON name/value convertida a un String y luego codificada en Base64. La detección de fraudes da mejores resultados cuando se manda esta información. Los elementos son los siguentes:

Los siguientes son los parámetros requeridos. Un request será rechazado si estos parámetros no están presentes en el encabezado. - ip_address - device_id - user_timezone

Los siguientes son un grupo de parámetros importantes pero no requeridos. El mandar esta información ayuda a mejorar el índice de prevención de fraude.

user-agent-string
is_rooted_device
is_incognito
location_latitude
location_longitude
os_version
os_type
phone_brand
phone_carrier
battery_level
is_battery_charging
is_connected_to_wifi
screen_resolution_width
screen_resolution_height
window_position_x
window_position_y
color_depth
pixel_depth
pixel_ratio

Example: ewogICAgImlwX2FkZHJlc3MiOiIxMjMuMTIzLjEyMy4xMjMiLAogICAgImRldmljZV9pZCIgOiAiMTIzNDU2IiwKICAgICJ1c2VyX3RpbWV6b25lIiA6IiswMzozNCIsCiAgICAidXJsX2RvbWFpbl9uYW1lIiA6ImhvbGFjYXNoLm14IiwKICAgICJicm93c2VyX3ZlcnNpb24iIDoiMTIzIiwKICAgICJicm93c2VyX25hbWUiIDoiTW96aWxsYSIsCiAgICAiYnJvd3Nlcl90aW1lem9uZSIgOiJQU1QiLAogICAgInNjcmVlbl9yZXNvbHV0aW9uX3dpZHRoIiA6IjEyMyIsCiAgICAic2NyZWVuX3Jlc29sdXRpb25faGVpZ2h0IiA6IjEyMyIsCiAgICAid2luZG93X3Bvc2l0aW9uX3giIDoiMTIzIiwKICAgICJ3aW5kb3dfcG9zaXRpb25feSIgOiIxMjMiLAogICAgImNvbG9yX2RlcHRoIiA6IjEyMyIKfQ====

Request Body schema: application/json

Información acerca de la credencial de pago que necesita ser tokenizada.

required	object (ConsumerDetail) Detalles del cliente
required	object (PaymentCredential) Detalles de la credencial de pago usada para hacer el pago

Responses

200

Operación exitosa

400

Petición inválida, revisa la respuesta para detalles.

401

Las credenciales no son válidas

429

Too many requests per minute. Please retry the request with an exponential backoff.

post/tokenization/payment_token

Request samples

Payload
cURL

application/json

{"consumer_details": {"contact": {"email": "abc@abc.com"
},
"name": {"first_last_name": "Cash",
"first_name": "Test",
"second_first_name": "Hola",
"second_last_name": "User"
}
},
"credential": {"credit_or_debit_card": {"card_number": "4242424242424242",
"card_validation_code": "123",
"expiration_month": "12",
"expiration_year": "2034"
},
"payment_method": {"method": "credit_or_debit_card"
}
}
}

Response samples

200
400

application/json

{"status_details": {"date_created": "1643073307052,",
"message": "token created",
"status": "success"
},
"token_details": {"additional_details": [{"data": "visa",
"name": "card_brand"
},
{"data": "34",
"name": "expiration_year"
},
{"data": "12",
"name": "expiration_month"
},
{"data": "4242",
"name": "card_last_four_digits"
}
],
"token": "5c86fac0-08a5-4c71-92be-a6f3a770de2d"
}
}

Regresa un token de pago.

Regresa un token de pago junto con toda la información adicional necesaria. Revisa PaymentCredentialMetadata para ver mayor información.

Request

Security:

clientKey or sessionToken

path Parameters

id

required

string

El id del token de pago.

Example: 5c86fac0-08a5-4c71-92be-a6f3a770de2d

Responses

200

Operación exitosa.

400

Petición inválida, revisa la respuesta para detalles.

401

Las credenciales no son válidas

get/tokenization/payment_token/{id}

Request samples

cURL

curl --location --request GET 'https://sandbox.api.holacash.mx/v2/tokenization/payment_token/5c86fac0-08a5-4c71-92be-a6f3a770de2d' \
--header 'X-Api-Client-Key: <USE SECRET KEY>' \
--data-raw ''

Response samples

200
400

application/json

{"status_details": {"date_created": 1643086863215,
"message": "token obtained",
"status": "success"
},
"token_details": {"additional_details": [{"data": "visa",
"name": "card_brand"
},
{"data": "34",
"name": "expiration_year"
},
{"data": "12",
"name": "expiration_month"
},
{"data": "424242",
"name": "card_bin"
},
{"data": "4242",
"name": "card_last_four_digits"
},
{"data": "abc@abc.com",
"name": "holder_email"
},
{"data": "Snoop the Doggy Dog",
"name": "holder_name"
}
],
"token": "5c86fac0-08a5-4c71-92be-a6f3a770de2d"
}
}

transaction

Crea, captura, reembolsa u obtiene cargos.

Captura un cargo previo (no capturado).

Si retuviste fondos durante el cargo desactivando la configuración auto_capture o no incluyendo la configuarción (desactivado por default), puedes usar este API para capturar algunos o todos los fondos no capturados.

Request

Security:

clientKey or sessionToken

path Parameters

id

required

string

El id del cargo que va a ser capturado.

Example: f380faa8-179c-45e0-af73-25e8db75fe15

Request Body schema: application/json

El monto a capturar.

amount required	integer Entero positivo que representa la cantidad en su más pequeña unidad de moneda. $50 MXN debe de ser representado como 5000 por que la cantidad más pequeña para el peso mexicano es de 1 centavo donde 100 centavos hacen 1 peso
currency_code required	string Código de moneda a 3 caracteres Value: "MXN"

Responses

200

Operación exitosa.

400

Petición inválida, revisa la respuesta para más detalles.

401

Las credenciales no son válidas

Callbacks

postEvento de fallo de captura

postEvento de captura exitoso.

post/transaction/capture/{id}

Request samples

Payload
cURL

application/json

{"amount": 5000,
"currency_code": "MXN"
}

Response samples

200
400

application/json

{"capture_transaction_id": "f2e43795-fce4-424c-880a-f6c1fed8cdf7",
"captured_amount": {"amount": 5000,
"currency_code": "MXN"
},
"status_details": {"message": "captured",
"status": "success"
}
}

Callback payload samples

application/json

{"event_type": "capture.failed",
"payload": {"capture_detail": {"capture_transaction_id": "f2e43795-fce4-424c-880a-f6c1fed8cdf7",
"captured_amount": {"amount": 5000,
"currency_code": "MXN"
}
},
"charge_detail": {"charge": {"amount_details": {"amount": 5000,
"currency_code": "MXN"
},
"consumer_details": {"contact": {"email": "test_user@example.com"
},
"external_consumer_id": "abcd",
"name": {"first_last_name": "Cash",
"first_name": "Test",
"second_first_name": "Hola",
"second_last_name": "User"
}
},
"payment_detail": {"credentials": {"credit_or_debit_card": {"card_number": "424242XXXXXX4242",
"card_validation_code": "XXX",
"expiration_month": "12",
"expiration_year": "2024"
},
"payment_method": {"method": "credit_or_debit_card"
}
}
}
},
"id": "8fa9a35e-3ece-4085-860c-4deb4c9e28ed",
"status_details": {"date_created": 1643144893400,
"detail": {"additional_details": [ ],
"code": "transaction_not_valid_capture_target_already_settled",
"message": "Charge was already settled"
},
"message": "Could not capture charge",
"status": "failure"
}
}
}
}

Obtiene una lista de cargos.

Utiliza la llave secreta. Obtiene una lista paginada de transacciones en tiempo real ordenada por fecha de creación en orden descedente. La paginación funciona con base en cursores donde el objeto de la respuesta contiene información acerca del cursor actual y la lista de transacciones que pertenecen al tamaño de la página (limit). Estos son algunos parámetros de consulta que se pueden utilizar

limit - Número máximo de transacciones por regresar.
after_id - Transacción(es) a solicitar después de ese cursor basado en el límite.
before_id - Transacción(es) a solicitar antes de ese cursor basado en el límite.

Puedes encontrar todos los parámetros de consulta en la sección Query Parameters dentro de la sección Request. Los atributos del cursor de la respuesta se explican a continuación:

first_cursor - Indica el cursor más actual del límite de la respuesta actual.
has_next - Indica si hay transacciones más antiguas pendientes por traer.
has_previous - Indica si hay transacciones más nuevas pendientes por traer.
last_cursor - Indica el cursor más antiguo del límite de la respuesta actual.

Si se envían ambos parámetros after_id y before_id o se envía un cursor inválido causará un error (after_id_and_before_id_both_present e integrity_or_database_issue respectivamente). Revisa la sección de Códigos de error para más detalle. Para moverse hacia adelante entre las páginas de transacciones, envía el valor de first_cursor en el parámetro de consulta before_id. Para moverse hacia atrás entre las páginas de transacciones, envía el valor de last_cursor en el parámetro de consulta after_id.

Request

Security:

clientKey or sessionToken

query Parameters

search_key	string Parámetro de consulta usado para buscar por: `TID` `payment_info.reference` `payment_info.transaction_clabe` `payment_info.holacash_system_order_id` `payment_info.external_system_order_id` `creator_email`
start_time	integer La fecha de inicio para la búsqueda por rango de fechas, expresada en UTC Unix Epoch Time. Puedes visitar este sitio para convertir fechas en línea.
end_time	integer La fecha final para la búsqueda por rango de fechas, expresada en UTC Unix Epoch Time. Puedes visitar este sitio para convertir fechas en línea.
limit	integer El número de transacciones en un grupo. El valor mínimo es `1` (inclusivo) y el valor máximo es `100` (inclusivo). Si este parámetro no viene incluido en la llamada del API el valor por defecto será `10`.
before_id	string El ID del sistema usado como un punto de inicio para obetener la transacción anterior
after_id	string El ID del sistema usado como un punto de inicio para obetener la transacción siguiente
monthly_installments	string Bandera booleana que indica si la transacción fue a MSI.
transaction_status	string El estado de los cargos. Esta es una lista de campos separados por comas de `TransactionStatus`
payment_methods	string El método de pago de los cargos. Esta es una lista de campos separados por comas de `PaymentMethods`

Responses

200

Información relacionada a los cargos

400

Verifica la propiedad detail.code de la respuesta. Estos son los errores que el servicio puede regresar:

invalid_query_param
merchant_sub_account_does_not_exist
merchant_does_not_exist
limit_out_of_bounds
integrity_or_database_issue
invalid_cursor_after_or_before
after_id_and_before_id_both_present

Revisa la sección de Códigos de error para más detalle.

401

Las credenciales no son válidas

get/transaction/charge

Request samples

Default request
Request with limit
Request with filters
Request with after_id and filters

curl --location --request GET 'https://sandbox.api.holacash.mx/v2/transaction/charge' \
--header 'X-Api-Client-Key: <USE SECRET KEY>' \
--header 'Content-Type: application/json'

Response samples

200
400

application/json

{"has_next": true,
"has_previous": false,
"last_cursor": "MjAyMi0wMy0wMyAwNjo0MDozNS44MzY4MjYrMDA6MDA=",
"merchant_payment_transactions": [{"TID": "d49efac5-c834-4ff9-ae92-c8678148601a",
"amount_details": {"amount": 5000,
"currency_code": "MXN"
},
"charge_status": "completed",
"creator_email": "test_user@example.com",
"date_created": 1650904681,
"description": "Pago por cuenta bancaria",
"is_refundable": false,
"original_amount": {"amount": 5000,
"currency_code": "MXN"
},
"payment_info": {"card_brand": null,
"card_last_four_digits": null,
"external_system_order_id": "my_order_id",
"holacash_system_order_id": "3966995a-0853-4b19-83aa-d242e223a14b",
"payment_method": "pay_with_bank_account",
"reference": null,
"transaction_clabe": "646180280999990299"
}
}
]
}

Crea un cargo.

Realiza un cargo por una cantidad específica a una credencial de pago (ej. credit_or_debit_card o pay_with_bank_account). Tienes la opción de retener los fondos usando esta API y capturar los fondos después cuando la compra sea completada ó puedes completar el cargo en una sola llamada. Solo tarjeta de cédito o débito soportan esta funcionalidad de separar la retención de fondos y su captura. Revisa processing_instructions en el objeto Charge para más información. Puedes usar estas tarjetas de pruebas para hacer varios flujos y ver como manejarlos correctamente.

Request

Security:

clientKey or sessionToken

header Parameters

X-Cash-Anti-Fraud-Metadata

string

Usado para mandar información al sistema para combatir fraude. Lo datos mandados en el encabezado es una estrucutra de tipo JSON name/value convertida a un String y luego codificada en Base64. La detección de fraudes da mejores resultados cuando se manda esta información. Los elementos son los siguentes:

Los siguientes son los parámetros requeridos. Un request será rechazado si estos parámetros no están presentes en el encabezado. - ip_address - device_id - user_timezone

Los siguientes son un grupo de parámetros importantes pero no requeridos. El mandar esta información ayuda a mejorar el índice de prevención de fraude.

user-agent-string
is_rooted_device
is_incognito
location_latitude
location_longitude
os_version
os_type
phone_brand
phone_carrier
battery_level
is_battery_charging
is_connected_to_wifi
screen_resolution_width
screen_resolution_height
window_position_x
window_position_y
color_depth
pixel_depth
pixel_ratio

Example: ewogICAgImlwX2FkZHJlc3MiOiIxMjMuMTIzLjEyMy4xMjMiLAogICAgImRldmljZV9pZCIgOiAiMTIzNDU2IiwKICAgICJ1c2VyX3RpbWV6b25lIiA6IiswMzozNCIsCiAgICAidXJsX2RvbWFpbl9uYW1lIiA6ImhvbGFjYXNoLm14IiwKICAgICJicm93c2VyX3ZlcnNpb24iIDoiMTIzIiwKICAgICJicm93c2VyX25hbWUiIDoiTW96aWxsYSIsCiAgICAiYnJvd3Nlcl90aW1lem9uZSIgOiJQU1QiLAogICAgInNjcmVlbl9yZXNvbHV0aW9uX3dpZHRoIiA6IjEyMyIsCiAgICAic2NyZWVuX3Jlc29sdXRpb25faGVpZ2h0IiA6IjEyMyIsCiAgICAid2luZG93X3Bvc2l0aW9uX3giIDoiMTIzIiwKICAgICJ3aW5kb3dfcG9zaXRpb25feSIgOiIxMjMiLAogICAgImNvbG9yX2RlcHRoIiA6IjEyMyIKfQ====

Request Body schema: application/json

Detalle de lo que se necesita autorizar.

	object (AdditionalDetails) Información adicional relacionada con el domicilio
required	object (Amount) Detalle del monto
	object (ConsumerDetail) Detalles del cliente
description required	string
	object (PaymentDetail) Detalles del pago
	object (ProcessingInstruction) Detalles de como quieres que la transacción sea procesada
	object Detalles de la compra
	object (ShippingDetails) Detalles sobre donde deben de ser enviados los productos comprados

Responses

200

Detalle de lo que fue autorizado.

400

Verifica la variable status en la respuesta para determinar los siguientes pasos a seguir. El status puede ser failure (fallo) o pending (pendiente). Cuando el status se encuentra como pending, por favor verifica el valor contenido en detail.code. Si detail.code contiene el valor action_required verifica la información de los siguientes pasos a seguir en detail.additional_details.

Si payment_method es credit_or_debit_card puedes obetener 3ds_authenticate dentro del campo action en detail.additional_details. En este caso, redirige al cliente a la URL especificada en redirect_url
Si payment_method es pay_with_store o pay_with_bank_account entonces puedes obtener collect_payment dentro del campo action en detail.additional_details. En este caso, utiliza la información contenida dentro de additional_details para dirigir al cliente a completar su pago.
Si payment_method es pay_with_bnpl entonces puedes obtener complete_at_bnpl_provider dentro del campo action en detail.additional_details. En este caso, redirige al cliente a la URL especificada en redirect_url En cualquiera de los escenarios mencionados previamente puedes consultar el sistema utilizado el endpoint /transaction/{id} o registrar un webhook para recibir notificaciones del resultado del proceso.

401

Las credenciales no son válidas

Callbacks

postEvento de cargo cancelado.

postEvento de cargo fallido.

postEvento de cargo pendiente

postEvento de cargo exitoso.

post/transaction/charge

Request samples

Payload
cURL

application/json

{"amount_details": {"amount": 5000,
"currency_code": "MXN"
},
"consumer_details": {"contact": {"email": "test_user@example.com",
"id": "1234"
},
"external_consumer_id": "abcd",
"name": {"first_last_name": "Cash",
"first_name": "Test",
"second_first_name": "Hola",
"second_last_name": "User"
}
},
"description": "This is a test description",
"payment_detail": {"credentials": {"credit_or_debit_card": {"card_number": "4242424242424242",
"card_validation_code": "324",
"expiration_month": "12",
"expiration_year": "2024"
},
"payment_method": {"method": "credit_or_debit_card"
}
}
},
"processing_instructions": {"auto_capture": true
}
}

Response samples

200
400

application/json

{"charge": {"amount_details": {"amount": 5000,
"currency_code": "MXN"
},
"consumer_details": {"contact": {"email": "test_user@example.com"
},
"external_consumer_id": "abcd",
"name": {"first_last_name": "Cash",
"first_name": "Test",
"second_first_name": "Hola",
"second_last_name": "User"
}
},
"description": "This is a test description",
"payment_detail": {"credentials": {"credit_or_debit_card": {"card_number": "XXXXXXXXXXXXXXXX",
"card_validation_code": "XXX",
"expiration_month": "12",
"expiration_year": "2024"
},
"payment_method": {"method": "credit_or_debit_card"
}
}
},
"processing_instructions": {"auto_capture": true
}
},
"id": "8fa9a35e-3ece-4085-860c-4deb4c9e28ed",
"status_details": {"date_created": 1643132896227,
"detail": {"additional_details": [{"data": "visa",
"name": "card_brand"
},
{"data": "credit",
"name": "card_type"
},
{"data": "424242",
"name": "card_bin"
},
{"data": "4242",
"name": "card_last_four_digits"
},
{"data": "MXN",
"name": "currency_code"
},
{"data": "24",
"name": "expiration_year"
},
{"data": "12",
"name": "expiration_month"
},
{"data": "captured",
"name": "charge_status"
}
]
},
"message": "charge created",
"status": "success"
}
}

Callback payload samples

application/json

{"event_type": "charge.cancelled",
"payload": {"cancellation_reason": "None",
"charge": {"amount_details": {"amount": 5000,
"currency_code": "MXN"
},
"consumer_details": {"contact": {"email": "test_user@example.com"
},
"external_consumer_id": "abcd",
"name": {"first_last_name": "Cash",
"first_name": "Test",
"second_first_name": "Hola",
"second_last_name": "User"
}
},
"description": "This is a test description",
"payment_detail": {"credentials": {"credit_or_debit_card": {"card_number": "424242XXXXXX4242",
"card_validation_code": "XXX",
"expiration_month": "12",
"expiration_year": "2024"
},
"payment_method": {"method": "credit_or_debit_card"
}
}
},
"processing_instructions": {"auto_capture": true
}
},
"id": "8fa9a35e-3ece-4085-860c-4deb4c9e28ed",
"status_details": {"date_created": 1643157023494,
"detail": {"additional_details": [ ],
"code": "expired",
"message": "charge expired"
},
"message": "Could not create charge",
"status": "cancelled"
}
}
}

Obtiene el detalle de un cargo

Una vez que se realiza un cargo, y si este fue exitoso se obtiene un id. Puedes utilizar este id de cargo para obtener detalles de esta transacción después.

Request

Security:

clientKey or sessionToken

path Parameters

id

required

string

El id del cargo a regresar.

Example: 4080a2ac-2927-4212-8ff8-00DD010662DA

Responses

200

El cargo.

401

Las credenciales no son válidas

404

Cargo no encontrado.

get/transaction/charge/{id}

Request samples

cURL

curl --location --request GET 'https://sandbox.api.holacash.mx/v2/transaction/charge/f2e43795-fce4-424c-880a-f6c1fed8cdf7' \
--header 'X-Api-Client-Key: <USE SECRET KEY>' \
--data-raw ''

Response samples

200

application/json

{"charge": {"amount_details": {"amount": 5000,
"currency_code": "MXN"
},
"consumer_details": {"contact": {"email": "test_user@example.com"
},
"external_consumer_id": "abcd",
"name": {"first_last_name": "Cash",
"first_name": "Test",
"second_first_name": "Hola",
"second_last_name": "User"
}
},
"description": "This is a test description",
"payment_detail": {"credentials": {"credit_or_debit_card": {"card_number": "XXXXXXXXXXXXXXXX",
"card_validation_code": "XXX",
"expiration_month": "12",
"expiration_year": "2024"
},
"payment_method": {"method": "credit_or_debit_card"
}
}
},
"processing_instructions": {"auto_capture": true
}
},
"id": "8fa9a35e-3ece-4085-860c-4deb4c9e28ed",
"status_details": {"date_created": 1643132896227,
"detail": {"additional_details": [{"data": "visa",
"name": "card_brand"
},
{"data": "credit",
"name": "card_type"
},
{"data": "424242",
"name": "card_bin"
},
{"data": "4242",
"name": "card_last_four_digits"
},
{"data": "MXN",
"name": "currency_code"
},
{"data": "24",
"name": "expiration_year"
},
{"data": "12",
"name": "expiration_month"
},
{"data": "captured",
"name": "charge_status"
}
]
},
"message": "charge created",
"status": "success"
}
}

Reembolsa un cargo previo que haya sido capturado.

Usa una llave privada. Si realizaste el charge con la processing_instruction auto_capture cómo false y aún no haz realizado la captura (capture), solo la cantidad total del charge es reembolsada sin importar la cantidad que especifiques. Esto en efecto cancela el charge. Si realizaste el charge con la processing_instruction cómo true entonces puedes hacer el reembolso con una cantidad desde mayor a cero hasta la cantidad total del charge.

Request

Security:

clientKey or sessionToken

path Parameters

id

required

string

El id del cargo que va a ser reembolsado.

Example: f380faa8-179c-45e0-af73-25e8db75fe15

Request Body schema: application/json

El monto a reembolsar.

amount required	integer Entero positivo que representa la cantidad en su más pequeña unidad de moneda. $50 MXN debe de ser representado como 5000 por que la cantidad más pequeña para el peso mexicano es de 1 centavo donde 100 centavos hacen 1 peso
currency_code required	string Código de moneda a 3 caracteres Value: "MXN"

Responses

200

Operación exitosa.

400

Petición inválida, checa la respuesta para detalles.

401

Las credenciales no son válidas

Callbacks

postEvento de reembolso fallido.

postReembolso exitoso.

post/transaction/refund/{id}

Request samples

Payload
cURL

application/json

{"amount": 5000,
"currency_code": "MXN"
}

Response samples

200
400

application/json

{"refund_transaction_id": "db068fc2-f07d-4a5d-bd23-59aa5595d7f4",
"status_details": {"message": "refunded",
"status": "success"
}
}

Callback payload samples

application/json

{"event_type": "refund.failed",
"payload": {"charge_detail": {"charge": {"consumer_details": {"contact": {"email": "test_user@example.com"
},
"external_consumer_id": "abcd",
"name": {"first_last_name": "Cash",
"first_name": "Test",
"second_first_name": "Hola",
"second_last_name": "User"
}
},
"payment_detail": {"credentials": {"credit_or_debit_card": {"card_number": "424242XXXXXX4242",
"card_validation_code": "XXX",
"expiration_month": "12",
"expiration_year": "2024"
},
"payment_method": {"method": "credit_or_debit_card"
}
}
}
},
"id": "8fa9a35e-3ece-4085-860c-4deb4c9e28ed",
"status_details": {"date_created": 1643145296384,
"detail": {"additional_details": [ ],
"code": "transaction_not_valid_refund_target_no_funds_to_refund",
"message": "Cannot refund more than original amount"
},
"message": "Could not refund charge",
"status": "failure"
}
},
"refund_detail": {"refund_transaction_id": "db068fc2-f07d-4a5d-bd23-59aa5595d7f4",
"refunded_amount": {"amount": 5000,
"currency_code": "MXN"
}
}
}
}

order

Crear una orden

Crea una orden.

Un objeto order (orden) o su id en el sistema de HolaCash pueden ser utilizados junto con las llamadas para hacer un cargo en /transaction/charge. Esto realiza una asociación de la order (orden) con un Charge (cargo).

Request

Security:

clientKey or sessionToken

header Parameters

X-Cash-Anti-Fraud-Metadata

string

Usado para mandar información al sistema para combatir fraude. Lo datos mandados en el encabezado es una estrucutra de tipo JSON name/value convertida a un String y luego codificada en Base64. La detección de fraudes da mejores resultados cuando se manda esta información. Los elementos son los siguentes:

Los siguientes son los parámetros requeridos. Un request será rechazado si estos parámetros no están presentes en el encabezado. - ip_address - device_id - user_timezone

Los siguientes son un grupo de parámetros importantes pero no requeridos. El mandar esta información ayuda a mejorar el índice de prevención de fraude.

user-agent-string
is_rooted_device
is_incognito
location_latitude
location_longitude
os_version
os_type
phone_brand
phone_carrier
battery_level
is_battery_charging
is_connected_to_wifi
screen_resolution_width
screen_resolution_height
window_position_x
window_position_y
color_depth
pixel_depth
pixel_ratio

Example: ewogICAgImlwX2FkZHJlc3MiOiIxMjMuMTIzLjEyMy4xMjMiLAogICAgImRldmljZV9pZCIgOiAiMTIzNDU2IiwKICAgICJ1c2VyX3RpbWV6b25lIiA6IiswMzozNCIsCiAgICAidXJsX2RvbWFpbl9uYW1lIiA6ImhvbGFjYXNoLm14IiwKICAgICJicm93c2VyX3ZlcnNpb24iIDoiMTIzIiwKICAgICJicm93c2VyX25hbWUiIDoiTW96aWxsYSIsCiAgICAiYnJvd3Nlcl90aW1lem9uZSIgOiJQU1QiLAogICAgInNjcmVlbl9yZXNvbHV0aW9uX3dpZHRoIiA6IjEyMyIsCiAgICAic2NyZWVuX3Jlc29sdXRpb25faGVpZ2h0IiA6IjEyMyIsCiAgICAid2luZG93X3Bvc2l0aW9uX3giIDoiMTIzIiwKICAgICJ3aW5kb3dfcG9zaXRpb25feSIgOiIxMjMiLAogICAgImNvbG9yX2RlcHRoIiA6IjEyMyIKfQ====

Request Body schema: application/json

El objeto orden.

	object (ConsumerDetail) Detalles del cliente
description	string
required	object (Amount) Detalle del monto
	object (PaymentDetail) Detalles del pago
	Array of objects (OrderItem) non-empty Detalle de los productos que serán comprados
	object (ShippingDetails) Detalles sobre donde deben de ser enviados los productos comprados

Responses

200

Creación de orden exitosa.

400

Petición inválida, checa la respuesta para detalles.

401

Las credenciales no son válidas

429

Too many requests per minute. Please retry the request with an exponential backoff.

post/order

Request samples

Payload
cURL

application/json

{"description": "This is a test order",
"order_total_amount": {"amount": 5000,
"currency_code": "MXN"
},
"purchases": [{"description": "This is an item in the order",
"id": "1234",
"item_total_amount": {"amount": 5000,
"currency_code": "MXN"
},
"quantity": 1,
"unit_amount": {"amount": 5000,
"currency_code": "MXN"
}
}
]
}

Response samples

200
400

application/json

{"order": {"description": "This is a test order",
"order_total_amount": {"amount": 5000,
"currency_code": "MXN"
},
"purchases": [{"description": "This is an item in the order",
"id": "1234",
"item_total_amount": {"amount": 5000,
"currency_code": "MXN"
},
"quantity": 1,
"unit_amount": {"amount": 5000,
"currency_code": "MXN"
}
}
]
}
}

Obtiene una orden dado un ID específico.

Regresa una orden dado un ID específico en el sistema de HolaCash.

Request

Security:

clientKey or sessionToken

path Parameters

id

required

string

El ID de la orden a consultar

Example: f435579e-37c6-49b2-98c5-a22a49a433e9

Responses

200

Se encontró la orden de forma exitosa.

400

Petición inválida, checa la respuesta para detalles.

401

Las credenciales no son válidas

get/order/{id}

Request samples

cURL

curl --location --request GET 'https://sandbox.api.holacash.mx/v2/order/f435579e-37c6-49b2-98c5-a21a49a433e9' \
--header 'X-Api-Client-Key: <USE PUBLIC OR SECRET KEY>' \
--data-raw ''

Response samples

200
400

application/json

{"order": {"description": "This is a test order",
"order_total_amount": {"amount": 5000,
"currency_code": "MXN"
},
"purchases": [{"description": "This is an item in the order",
"id": "1234",
"item_total_amount": {"amount": 5000,
"currency_code": "MXN"
},
"quantity": 1,
"unit_amount": {"amount": 5000,
"currency_code": "MXN"
}
}
]
},
"order_information": {"order_id": "f435579e-37c6-49b2-98c5-a22a49a433e9"
}
}

Actualiza una orden dado un ID específico.

Regresa la orden actualizada dado un ID específico en el sistema de HolaCash.

Request

Security:

clientKey or sessionToken

path Parameters

id

required

string

El ID de la orden por actualizar

Example: f435579e-37c6-49b2-98c5-a22a49a433e9

header Parameters

X-Cash-Anti-Fraud-Metadata

string

Usado para mandar información al sistema para combatir fraude. Lo datos mandados en el encabezado es una estrucutra de tipo JSON name/value convertida a un String y luego codificada en Base64. La detección de fraudes da mejores resultados cuando se manda esta información. Los elementos son los siguentes:

Los siguientes son los parámetros requeridos. Un request será rechazado si estos parámetros no están presentes en el encabezado. - ip_address - device_id - user_timezone

Los siguientes son un grupo de parámetros importantes pero no requeridos. El mandar esta información ayuda a mejorar el índice de prevención de fraude.

user-agent-string
is_rooted_device
is_incognito
location_latitude
location_longitude
os_version
os_type
phone_brand
phone_carrier
battery_level
is_battery_charging
is_connected_to_wifi
screen_resolution_width
screen_resolution_height
window_position_x
window_position_y
color_depth
pixel_depth
pixel_ratio

Example: ewogICAgImlwX2FkZHJlc3MiOiIxMjMuMTIzLjEyMy4xMjMiLAogICAgImRldmljZV9pZCIgOiAiMTIzNDU2IiwKICAgICJ1c2VyX3RpbWV6b25lIiA6IiswMzozNCIsCiAgICAidXJsX2RvbWFpbl9uYW1lIiA6ImhvbGFjYXNoLm14IiwKICAgICJicm93c2VyX3ZlcnNpb24iIDoiMTIzIiwKICAgICJicm93c2VyX25hbWUiIDoiTW96aWxsYSIsCiAgICAiYnJvd3Nlcl90aW1lem9uZSIgOiJQU1QiLAogICAgInNjcmVlbl9yZXNvbHV0aW9uX3dpZHRoIiA6IjEyMyIsCiAgICAic2NyZWVuX3Jlc29sdXRpb25faGVpZ2h0IiA6IjEyMyIsCiAgICAid2luZG93X3Bvc2l0aW9uX3giIDoiMTIzIiwKICAgICJ3aW5kb3dfcG9zaXRpb25feSIgOiIxMjMiLAogICAgImNvbG9yX2RlcHRoIiA6IjEyMyIKfQ====

Request Body schema: application/json

El objeto orden.

	object (ConsumerDetail) Detalles del cliente
description	string
	object (Amount) Detalle del monto
	object (PaymentDetail) Detalles del pago
	Array of objects (OrderItem) non-empty Detalle de los productos que serán comprados
	object (ShippingDetails) Detalles sobre donde deben de ser enviados los productos comprados

Responses

200

Se actualizó la orden de forma exitosa.

400

Petición inválida, checa la respuesta para detalles.

401

Las credenciales no son válidas

patch/order/{id}

Request samples

Payload
cURL

application/json

{"description": "This is a test order",
"order_total_amount": {"amount": 5000,
"currency_code": "MXN"
},
"purchases": [{"description": "This is an item in the order",
"id": "1234",
"item_total_amount": {"amount": 5000,
"currency_code": "MXN"
},
"quantity": 1,
"unit_amount": {"amount": 5000,
"currency_code": "MXN"
}
}
]
}

Response samples

200
400

application/json

{"order": {"description": "This is the test order updated",
"order_total_amount": {"amount": 5000,
"currency_code": "MXN"
},
"purchases": [{"description": "This is an item in the updated order",
"id": "1234",
"item_total_amount": {"amount": 5000,
"currency_code": "MXN"
},
"quantity": 2,
"unit_amount": {"amount": 5000,
"currency_code": "MXN"
}
}
]
},
"order_information": {"order_id": "f435579e-37c6-49b2-98c5-a22a49a433e9"
}
}

checkout

Accede a la configuración relacionada al checkout

Obtiene el botón de checkout.

Regresa el botón de checkout para un merchant, Nota: Por el momento manejamos el mismo botón para todos los clientes, cualquier presentación personalizada estará disponible en una próxima versión.

Request

Security:

clientPublicKeyInQueryString

Responses

200

La imagen del botón del checkout.

400

Petición inválida, revisa la respuesta para detalles.

401

Las credenciales no son válidas

get/checkout/button

Request samples

cURL

curl --location --request GET 'https://sandbox.api.holacash.mx/v2/checkout/button?public_key=<USE PUBLIC KEY>'

Response samples

400

application/json

{"date_created": 1643093191130,
"detail": {"additional_details": [ ],
"code": "invalid_security_credentials",
"message": "The security credentials are not valid"
},
"message": "Could not authenticate",
"status": "failure"
}

beta

Funcionalidad sólo disponible para participantes en versión beta.

Revisa si un cargo es elegible para meses sin intereses

Usa llave secreta. Regresará una lista con las opciones disponibles de meses sin intereses o un arreglo vacío si no es elegible.

Request

Security:

clientKey or sessionToken

query Parameters

monthly_installments

required

boolean

Indica que queremos verificar si hay opciones a meses sin intereses.

Request Body schema: application/json

El cargo a verificar

	object (AdditionalDetails) Información adicional relacionada con el domicilio
required	object (Amount) Detalle del monto
	object (ConsumerDetail) Detalles del cliente
description required	string
	object (PaymentDetail) Detalles del pago
	object (ProcessingInstruction) Detalles de como quieres que la transacción sea procesada
	object Detalles de la compra
	object (ShippingDetails) Detalles sobre donde deben de ser enviados los productos comprados

Responses

200

Operación exitosa.

400

Petición inválida, revisa la respuesta para más detalles.

401

Las credenciales no son válidas

post/transaction/lookup

Request samples

Payload
cURL

application/json

{"amount_details": {"amount": 5070,
"currency_code": "MXN"
},
"consumer_details": {"contact": {"email": "test_user@example.com"
},
"external_consumer_id": "your_consumer_id",
"name": {"first_last_name": "Cash",
"first_name": "Test",
"second_first_name": "Hola",
"second_last_name": "User"
}
},
"description": "This is a test description",
"payment_detail": {"credentials": {"credit_or_debit_card": {"card_number": "4242424242424242",
"card_validation_code": "324",
"expiration_month": "12",
"expiration_year": "2024"
},
"payment_method": {"method": "credit_or_debit_card"
}
}
},
"processing_instructions": {"auto_capture": true
}
}

Response samples

200
400

application/json

{"options": [{"id": 1,
"unit": "months",
"value": 3
},
{"id": 2,
"unit": "months",
"value": 6
}
],
"options_list_id": "0a3f8ea5-78c4-4680-8952-3c7bee7f022a"
}

continuation

Obtiene la información de continuación de una transacción dado el id de continuación.

El continuation id es el valor UUID al final de la URL de continuación retornado al crear un cargo cuando el usuario tiene que completar 3DS, por ejemplo. Se puede usar el secret o public key. Retorna la información acerca del cargo asociado a esta external reference ID.

Request

Security:

clientKey or sessionToken

path Parameters

id

required

string

The external reference id.

Example: f435579e-37c6-49b2-98c5-a22a49a433e9

Responses

200

Se encontró la información de continuación de forma exitosa.

400

Petición inválida, checa la respuesta para detalles.

401

Las credenciales no son válidas

get/continuation/{id}

Request samples

cURL

curl --location --request GET 'https://sandbox.api.holacash.mx/v2/continuation/f435579e-37c6-49b2-98c5-a21a49a433e9' \
--header 'X-Api-Client-Key: <USE PUBLIC OR SECRET KEY>' \
--data-raw ''

Response samples

200
400

application/json

{"action": "3ds_authenticate",
"charge_id": "f435579e-37c6-49b2-98c5-a22a49a433e9",
"created_on": 1643144893400
}