Support

Hola Cash eCommerce API (1.0.0)

API a la plataforma 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.

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. Leer el Tutorial 3DS 2.0 para más detalle sobre cómo enviar la información para que tus clientes puedan tener una experiencia sin fricción.

Securityoauth2 or clientKey or sessionToken

Request

header Parameters

X-Cash-Anti-Fraud-Metadata

string

Se usa para mandar información al sistema para combatir fraude. Lo datos se mandan en el encabezado con una estructura de tipo JSON name/value convertida a un String y luego codificada en Base64. Enviar esta información mejora la detección de fraude

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 (PaymentCredential) Detalles de la credencial de pago usada para hacer el pago
required	object (ConsumerDetail) Detalles del cliente

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

{"credential": {"payment_method": {"method": "credit_or_debit_card"
},
"credit_or_debit_card": {"card_number": "4242424242424242",
"expiration_month": "12",
"expiration_year": "2034",
"card_validation_code": "123"
}
},
"consumer_details": {"contact": {"email": "abc@abc.com"
},
"name": {"first_name": "Test",
"second_first_name": "Hola",
"first_last_name": "Cash",
"second_last_name": "User"
},
"address": {"address_line_1": "First line of address",
"address_line_2": "Unit number",
"locality": "CDMX",
"region_name_or_code": "CX",
"postal_code": "11503",
"country_code": "MEX"
}
}
}

Response samples

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"
}
}

Consulta un token de pago previamente creado

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

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

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

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"
}
}

Actualiza un token de pago creado previamente

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

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

required

string

El id del token de pago.

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

Request Body schema: application/json

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

required

object (ConsumerDetail)

Detalles del cliente

Responses

200

Operación exitosa.

400

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

401

Las credenciales no son válidas

patch/tokenization/payment_token/{id}

Request samples

Payload
cURL

application/json

{"consumer_details": {"contact": {"email": "abc@abc.com"
},
"name": {"first_name": "Test",
"second_first_name": "Hola",
"first_last_name": "Cash",
"second_last_name": "User"
},
"address": {"address_line_1": "street name",
"country_code": "MEX",
"locality": "Leon",
"postal_code": 37000,
"region_name_or_code": "GTO"
}
}
}

Response samples

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"
},
{"data": {"address": {"address_line_1": "foo1",
"address_line_2": "foo2",
"address_line_3": "foo3",
"address_line_4": "foo4",
"country_code": "MEX",
"locality": "Leon",
"postal_code": "37000",
"region_name_or_code": "GTO"
},
"contact": {"email": "test_user@example.com"
},
"name": {"first_name": "Test"
}
},
"name": "consumer_details"
}
],
"token": "5c86fac0-08a5-4c71-92be-a6f3a770de2d"
}
}

Transaction

Crea, captura, reembolsa u obtiene cargos.

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 cuando la compra sea completada, o puedes completar el cargo en una sola llamada. La funcionalidad de separar la retención de fondos y su captura solo se soporta con una tarjeta de crédito o débito. Revisa processing_instructions en el objeto Charge para más información. Puedes usar estas tarjetas de pruebas para probar varios flujos y ver cómo manejarlos correctamente. Lee el Tutorial 3DS 2.0 para más detalles sobre cómo enviar la información requerida para brindarle a tus clientes una experiencia sin fricción.

Securityoauth2 or clientKey or sessionToken

Request

header Parameters

X-Cash-Anti-Fraud-Metadata

string

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

Request Body schema: application/json

Detalle de lo que se necesita autorizar.

description required	string
required	object (Amount) Detalle del monto
	object (PaymentDetail) Detalles del pago. Atención se ha descartado el uso de la información de este objeto sobre dirección, contacto y nombre ('address', 'contact', and 'name') . Por favor use 'charge.billing_details' para proveer dicha información.
	object (ProcessingInstruction) Detalles de como quieres que la transacción sea procesada
	object Detalles de la compra
	object (ConsumerDetail) Detalles del cliente
	object (BillingDetails) Información de facturación asociada a las credenciales del pago del cliente. *Nota Para asegurar altas tasas de aprobación es importante enviar los siguientes campos - first_name, last_name, email, phone_1, address_line_1, country_code, locality, postal_code, region_name_or_code
	object (ShippingDetails) Detalles sobre donde deben de ser enviados los productos comprados
	object (AdditionalDetails) Información adicional relacionada con el domicilio

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).
Si el status se encuentra pending, verifica el valor del contenido en detail.code.
Si el detail.code contiene el valor action_required revisa los pasos a seguir en
los detail.additional_details

Si el status se encuentra pending, verifica el valor del contenido en
detail.code. Si el detail.code contiene el valor action_required revisa
los pasos a seguir en los detail.additional_details.
Si el payment_method es credit_or_debit_card, puedes obtener un
3ds_authenticate dentro del campo action en detail.additional_details.
En este caso, redirige al cliente a la URL especificada en redirect_url
Si elpayment_method (método de pago) es pay_with_store o
pay_with_bank_account entonces puedes obtener collect_payment
dentro del campo action en detail.additional_details. Para este caso,
utiliza la información contenida dentro de additional_details para dirigir
al cliente a completar su pago
Si el 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 que mencionamos previamente puedes consultar el sistema
utilizado el endpoint /transaction/{id} o registrar un webhook para
recibir notificaciones del resultado del proceso. Verifica la variable status en la respuesta
para determinar los siguientes pasos a seguir. El status puede ser failure (fallo)
o pending (pendiente)

401

Las credenciales no son válidas

Callbacks

postEvento de cargo exitoso.

postEvento de cargo pendiente

postEvento de cargo fallido.

postEvento de cargo cancelado.

postEvento de dispersión exitoso.

postEvento de dispersión fallido.

post/transaction/charge

Request samples

Payload
cURL

application/json

{"description": "This is a test description",
"amount_details": {"amount": 5000,
"currency_code": "MXN"
},
"payment_detail": {"credentials": {"payment_method": {"method": "credit_or_debit_card"
},
"credit_or_debit_card": {"card_number": "4242424242424242",
"expiration_month": "12",
"expiration_year": "2024",
"card_validation_code": "324"
}
}
},
"consumer_details": {"external_consumer_id": "abcd",
"contact": {"id": "1234",
"email": "test_user@example.com"
},
"name": {"first_name": "Test",
"second_first_name": "Hola",
"first_last_name": "Cash",
"second_last_name": "User"
}
},
"billing_details": {"contact": {"email": "test_user@example.com"
},
"name": {"first_name": "Test",
"second_first_name": "Hola",
"first_last_name": "Cash",
"second_last_name": "User"
},
"address": {"address_line_1": "First line of address",
"address_line_2": "Unit number",
"locality": "CDMX",
"region_name_or_code": "CX",
"postal_code": "11503",
"country_code": "MEX"
}
},
"shipping_details": {"contact": {"email": "test_user@example.com"
},
"name": {"first_name": "Test",
"second_first_name": "Hola",
"first_last_name": "Cash",
"second_last_name": "User"
},
"address": {"address_line_1": "First line of address",
"address_line_2": "Unit number",
"locality": "CDMX",
"region_name_or_code": "CX",
"postal_code": "11503",
"country_code": "MEX"
}
},
"processing_instructions": {"auto_capture": true
}
}

Response samples

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.succeeded",
"payload": {"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": 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"
}
}

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.

Securityoauth2 or clientKey or sessionToken

Request

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` `payment_link_id` `subscription_id`
start_time	integer <int64> 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 <int64> 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`
payment_networks	string Cadena separada por comas con Payment Networks de BNPL
subscription	string Bandera booleana que indica si la transacción fue pagada por una suscripción
channel	string Canal por el cual el usuario realizó el pago. Este es una cadena separada por comas de los siguientes posibles valores que representan los canales plugin.woocommerce plugin.magento commerce_api checkout_widget payment_link

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

application/json

{"has_next": true,
"has_previous": false,
"last_cursor": "MjAyMi0wNC0yNyAyMzozMzowOS45MTI5NTUrMDA6MDA=",
"merchant_payment_transactions": [{"TID": "ba770b24-8cf2-4a7a-83f0-54ac1b3b7328",
"amount_details": {"amount": 10000,
"currency_code": "MXN"
},
"charge_status": "failed",
"creator_email": "test_user@example.com",
"date_created": 1651102389,
"description": "Pago en efectivo por medio de tienda",
"is_refundable": false,
"original_amount": {"amount": 10000,
"currency_code": "MXN"
},
"payment_info": {"payment_method": "pay_with_store",
"reference": "1010100846381335",
"transaction_clabe": "None"
}
}
]
}

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.

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

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

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"
}
}

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.

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

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 mayor or igual a cero que representa la cantidad en su más pequeña unidad de moneda. $50 MXN debe de ser representado como 5000 (lo que significa 50 pesos 0 centavos, o $50.00 MXN).
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 captura exitoso.

postEvento de fallo de captura

post/transaction/capture/{id}

Request samples

Payload
cURL

application/json

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

Response samples

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.succeeded",
"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": "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": "424242XXXXXX4242",
"card_validation_code": "XXX",
"expiration_month": "12",
"expiration_year": "2024"
},
"payment_method": {"method": "credit_or_debit_card"
}
}
},
"processing_instructions": {"auto_capture": false
}
},
"id": "686dc8c1-8660-4642-85fc-a993aea51c20",
"related_transactions": [{"data": {"amount": 5000,
"currency": "MXN",
"date": 1644525036,
"id": "4fed7c82-8bb2-4d32-a683-2cb408abce26"
},
"name": "capture"
}
],
"status_details": {"date_created": 1644525047789,
"detail": {"additional_details": [{"data": "captured",
"name": "charge_status"
},
{"data": "visa",
"name": "card_brand"
},
{"data": "credit",
"name": "card_type"
},
{"data": "24",
"name": "expiration_year"
},
{"data": "12",
"name": "expiration_month"
},
{"data": "424242",
"name": "card_bin"
},
{"data": "4242",
"name": "card_last_four_digits"
}
]
},
"message": "completed",
"status": "success"
}
}
}
}

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.

Securityoauth2 or clientKey or sessionToken

Request

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

description required	string
required	object (Amount) Detalle del monto
	object (PaymentDetail) Detalles del pago. Atención se ha descartado el uso de la información de este objeto sobre dirección, contacto y nombre ('address', 'contact', and 'name') . Por favor use 'charge.billing_details' para proveer dicha información.
	object (ProcessingInstruction) Detalles de como quieres que la transacción sea procesada
	object Detalles de la compra
	object (ConsumerDetail) Detalles del cliente
	object (BillingDetails) Información de facturación asociada a las credenciales del pago del cliente. *Nota Para asegurar altas tasas de aprobación es importante enviar los siguientes campos - first_name, last_name, email, phone_1, address_line_1, country_code, locality, postal_code, region_name_or_code
	object (ShippingDetails) Detalles sobre donde deben de ser enviados los productos comprados
	object (AdditionalDetails) Información adicional relacionada con el domicilio

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

{"description": "This is a test description",
"amount_details": {"amount": 5070,
"currency_code": "MXN"
},
"payment_detail": {"credentials": {"payment_method": {"method": "credit_or_debit_card"
},
"credit_or_debit_card": {"card_number": "4242424242424242",
"expiration_month": "12",
"expiration_year": "2024",
"card_validation_code": "324"
}
}
},
"consumer_details": {"external_consumer_id": "your_consumer_id",
"contact": {"email": "test_user@example.com"
},
"name": {"first_name": "Test",
"second_first_name": "Hola",
"first_last_name": "Cash",
"second_last_name": "User"
}
},
"billing_details": {"contact": {"email": "test_user@example.com"
},
"name": {"first_name": "Test",
"second_first_name": "Hola",
"first_last_name": "Cash",
"second_last_name": "User"
},
"address": {"address_line_1": "First line of address",
"address_line_2": "Unit number",
"locality": "CDMX",
"region_name_or_code": "CX",
"postal_code": "11503",
"country_code": "MEX"
}
},
"shipping_details": {"contact": {"email": "test_user@example.com"
},
"name": {"first_name": "Test",
"second_first_name": "Hola",
"first_last_name": "Cash",
"second_last_name": "User"
},
"address": {"address_line_1": "First line of address",
"address_line_2": "Unit number",
"locality": "CDMX",
"region_name_or_code": "CX",
"postal_code": "11503",
"country_code": "MEX"
}
},
"processing_instructions": {"auto_capture": true
}
}

Response samples

application/json

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

Reembolsa un cargo previo que haya sido capturado.

Usa una llave secreta. 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.

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

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 mayor or igual a cero que representa la cantidad en su más pequeña unidad de moneda. $50 MXN debe de ser representado como 5000 (lo que significa 50 pesos 0 centavos, o $50.00 MXN).
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

postReembolso exitoso.

postEvento de reembolso fallido.

post/transaction/refund/{id}

Request samples

Payload
cURL

application/json

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

Response samples

application/json

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

Callback payload samples

application/json

{"event_type": "refund.succeeded",
"payload": {"refund_detail": {"refund_transaction_id": "db068fc2-f07d-4a5d-bd23-59aa5595d7f4",
"refunded_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": "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": "424242XXXXXX4242",
"card_validation_code": "XXX",
"expiration_month": "12",
"expiration_year": "2024"
},
"payment_method": {"method": "credit_or_debit_card"
}
}
},
"processing_instructions": {"auto_capture": false
}
},
"id": "686dc8c1-8660-4642-85fc-a993aea51c20",
"related_transactions": [{"data": {"amount": 5000,
"currency": "MXN",
"date": 1644525036,
"id": "4fed7c82-8bb2-4d32-a683-2cb408abce26"
},
"name": "capture"
},
{"data": {"amount": 5000,
"currency": "MXN",
"date": 1644525218,
"id": "068c9a5a-496d-4eaf-aa5d-feeadf79232e"
},
"name": "refund"
}
],
"status_details": {"date_created": 1644525229484,
"detail": {"additional_details": [{"data": "refunded",
"name": "charge_status"
},
{"data": "visa",
"name": "card_brand"
},
{"data": "credit",
"name": "card_type"
},
{"data": "24",
"name": "expiration_year"
},
{"data": "12",
"name": "expiration_month"
},
{"data": "424242",
"name": "card_bin"
},
{"data": "4242",
"name": "card_last_four_digits"
}
]
},
"message": "completed",
"status": "success"
}
}
}
}

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).

Securityoauth2 or clientKey or sessionToken

Request

header Parameters

X-Cash-Anti-Fraud-Metadata

string

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

Request Body schema: application/json

El objeto orden.

required	object (Amount) Detalle del monto
description required	string
	object (PaymentDetail) Detalles del pago. Atención se ha descartado el uso de la información de este objeto sobre dirección, contacto y nombre ('address', 'contact', and 'name') . Por favor use 'charge.billing_details' para proveer dicha información.
	object (BillingDetails) Información de facturación asociada a las credenciales del pago del cliente. *Nota Para asegurar altas tasas de aprobación es importante enviar los siguientes campos - first_name, last_name, email, phone_1, address_line_1, country_code, locality, postal_code, region_name_or_code
	object (ShippingDetails) Detalles sobre donde deben de ser enviados los productos comprados
	object (ConsumerDetail) Detalles del cliente
	Array of objects (OrderItem) non-empty Detalle de los productos que serán comprados
	Array of objects (Note) Representa una lista de notas que puedes agregar a una order.
external_system_order_id	string Identificador de la orden provista por el negocio. Usualmente es el order_id del sistema interno del negocio.

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.

Callbacks

postOrden fue creada exitosamente.

postLa creación de la orden falló.

postLa actualización de la orden fue exitosa.

postLa actualización de la orden falló.

post/order

Request samples

Payload
cURL

application/json

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

Response samples

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"
}
}
]
}
}

Callback payload samples

application/json

{"event_type": "order_creation.succeeded",
"payload": {"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"
}
}
}
}

Obtiene una orden dado un ID específico.

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

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

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

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.

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

required

string

El ID de la orden por actualizar

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

header Parameters

X-Cash-Anti-Fraud-Metadata

string

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

Request Body schema: application/json

El objeto orden.

	object (Amount) Detalle del monto
description	string
	object (PaymentDetail) Detalles del pago. Atención se ha descartado el uso de la información de este objeto sobre dirección, contacto y nombre ('address', 'contact', and 'name') . Por favor use 'charge.billing_details' para proveer dicha información.
	object (BillingDetails) Información de facturación asociada a las credenciales del pago del cliente. *Nota Para asegurar altas tasas de aprobación es importante enviar los siguientes campos - first_name, last_name, email, phone_1, address_line_1, country_code, locality, postal_code, region_name_or_code
	object (ShippingDetails) Detalles sobre donde deben de ser enviados los productos comprados
	object (ConsumerDetail) Detalles del cliente
	Array of objects (OrderItem) non-empty Detalle de los productos que serán comprados
	Array of objects (Note) Representa una lista de notas que puedes agregar a una order.
external_system_order_id	string Identificador de la orden provista por el negocio. Usualmente es el order_id del sistema interno del negocio.

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

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

Response samples

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.

SecurityclientPublicKeyInQueryString

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

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"
}

Subscription

Crear y administrar suscripciones y planes

Obtiene todos los cobros beta

Servicio utilizado para obtener todos los cobros relacionados a una suscripción.

Securityoauth2 or clientKey or sessionToken

Request

query Parameters

page	integer Default: 1 El número de página a consultar
page_size	integer [ 1 .. 100 ] Default: 15 Número de elementos por página a consultar. Los límites son inclusivos.
subscription_id	string <uuid> Este id es utilizado para obtener solamente los cobros relacionados a la suscripción dada.

Responses

200

Información acerca de los cobros solicitados

400

Detalles del error retornados cuando la petición falló.

401

Las credenciales no son válidas

get/invoice

Response samples

application/json

{"page_count": 0,
"item_count": 0,
"next": "string",
"previous": "string",
"invoice_list": [{"price": {"amount": 5000,
"currency_code": "MXN"
},
"date_created": 0,
"description": "string",
"due_date": 0,
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"number_of_payment_intents": 0,
"status": "cancelled",
"subscription_id": "aa11a4c2-a467-43db-b413-c4ab0f5cf627"
}
]
}

Obtiene todos los payment intents beta

Servicio utilizado para obtener todos los payment intents relacionados a una suscripción.

Securityoauth2 or clientKey or sessionToken

Request

query Parameters

page	integer Default: 1 El número de página a consultar
page_size	integer [ 1 .. 100 ] Default: 15 Número de elementos por página a consultar. Los límites son inclusivos.
invoice_id	string <uuid> Este id es utilizado para obtener solamente los payment intents relacionados al invoice dado.
subscription_id	string <uuid> Este id es utilizado para obtener solamente los payment intents relacionados a la suscripción dada.

Responses

200

Información acerca de los payment intents solicitados

400

Detalles del error retornados cuando la petición falló.

401

Las credenciales no son válidas

get/payment-intent

Response samples

application/json

{"page_count": 0,
"item_count": 0,
"next": "string",
"previous": "string",
"payment_intent_list": [{"price": {"amount": 5000,
"currency_code": "MXN"
},
"attempt_count": 0,
"date_created": 0,
"date_updated": 0,
"description": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"invoice_id": "f4c4edb8-11e0-4b33-bcc1-482dc59ebb32",
"max_attempt_count": 0,
"next_billing_date": 0,
"next_payment_method": "card",
"status": "active",
"transaction_id": "0fec1e58-b197-4052-99cf-2218496c5482",
"was_automatic": "ed45171f-1dc1-4897-90d4-b4507cb25990"
}
]
}

Crea un plan beta

Servicio utilizado para crear un plan de suscripción y poder ser ofrecido a los clientes. El plan necesita un producto asociado, visita la sección de product para más información.

Securityoauth2 or clientKey or sessionToken

Request

Request Body schema: application/json

Información acerca del plan que se va a crear

billing_frequency	string Default: "monthly" Periodo de tiempo en el cual al cliente suscrito al plan, se le cobrará Enum: "weekly" "bi_weekly" "monthly" "annual" "daily"
description required	string Información visible para los clientes que puede incluir todo el detalle que los usuarios necesiten para conocer los beneficios que pueden obtener al suscribirse a este plan
	object Esta propiedad puede contener información sobre cómo se mostrará el plan y los ajustes de configuración del widget de pago.
name required	string Nombre del plan. Normalmente este nombre comercial visible para tu cliente. Por ejemplo, "Básico", "Premium", "Familiar", etc.
required	object El precio (monto) que se facturará cada ciclo de facturación al método de pago
product_id required	string Id del producto que será asociado a este plan. Este es el id que el servicio `POST /product` retorna.

Responses

200

Información acerca del plan que fue creado

400

Detalles del error retornados cuando la petición falló.

401

Las credenciales no son válidas

Callbacks

postPlan creado exitosamente.

postLa creación del plan falló.

post/plan

Request samples

Payload

application/json

{"name": "My plan",
"description": "My plan description",
"additional_details": { },
"product_id": "09f53b82-295a-452b-b7e5-09a1b0e5b834",
"price": {"amount": 1000,
"currency_code": "MXN"
}
}

Response samples

application/json

{"additional_details": { },
"billing_frequency": "monthly",
"date_created": 1658956845,
"description": "My description",
"id": "02e036d8-f71c-47b4-8f22-3510bffc4e25",
"name": "hello new product",
"payment_link": {"id": "IKi39Pe1OhQTwKhWng",
"url": "http://URI/IKi39Pe1OhQTwKhWng"
},
"price": {"amount": 50121,
"currency_code": "MXN"
},
"product_id": "aa87e96e-62b2-493a-bcd3-8536f7c71a02",
"status": "active"
}

Callback payload samples

application/json

{"event_type": "plan_creation.succeeded",
"payload": {"additional_details": { },
"billing_frequency": "monthly",
"date_created": 1658956845,
"description": "My description",
"id": "02e036d8-f71c-47b4-8f22-3510bffc4e25",
"name": "hello new product",
"payment_link": {"id": "IKi39Pe1OhQTwKhWng",
"url": "http://URI/IKi39Pe1OhQTwKhWng"
},
"price": {"amount": 50121,
"currency_code": "MXN"
},
"product_id": "aa87e96e-62b2-493a-bcd3-8536f7c71a02",
"status": "active"
}
}

Obtiene todos los planes beta

Servicio utilizado para obtener todos los planes de suscripción creados por el comerciante.

Securityoauth2 or clientKey or sessionToken

Request

query Parameters

page	integer Default: 1 El número de página a consultar
page_size	integer [ 1 .. 100 ] Default: 15 Número de elementos por página a consultar. Los límites son inclusivos.

Responses

200

Información acerca del plan que fue creado

400

Detalles del error retornados cuando la petición falló.

401

Las credenciales no son válidas

get/plan

Response samples

application/json

{"page_count": 0,
"item_count": 0,
"next": "string",
"previous": "string",
"plan_list": [{"billing_frequency": "daily",
"description": "string",
"additional_details": {"widget_configuration": { }
},
"name": "string",
"price": {"amount": 5000,
"currency_code": "MXN"
},
"product_id": "string",
"status": "active",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"date_created": 0,
"payment_link": {"id": "string",
"url": "http://example.com"
}
}
]
}

Obtiene detalles de un plan dado beta

Servicio utilizado para obtener los detalles de un plan dado un id de plan

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

required

string <uuid>

El id del plan a regresar.

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

Responses

200

Información acerca del plan

400

Detalles del error retornados cuando la petición falló.

401

Las credenciales no son válidas

get/plan/{id}

Response samples

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"additional_details": {"widget_configuration": { }
},
"billing_frequency": "daily",
"date_created": 0,
"description": "string",
"name": "string",
"price": {"amount": 5000,
"currency_code": "MXN"
},
"product": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"additional_details": {"widget_configuration": { }
},
"date_created": 0,
"description": "string",
"external_product_id": "string",
"name": "string",
"subaccount_id": "string",
"status": "enabled"
},
"status": "active",
"payment_link": {"id": "string",
"url": "http://example.com"
}
}

Obtiene el detalle de la suscripción beta

Servicio utilizado para obtener el detalle de la suscripción creada por el comerciante.

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

required

string <uuid>

El id del subscription a regresar.

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

Responses

200

Información acerca de la suscripción creada

400

Detalles del error retornados cuando la petición falló.

401

Las credenciales no son válidas

get/subscription/{id}

Response samples

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"auto_billing": true,
"billing_frequency": "daily",
"billing_day": 0,
"billing_method": "string",
"customer": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"date_created": 0,
"full_name": "string",
"primary_email": "user@example.com",
"primary_phone_number": "string"
},
"date_created": 0,
"end_date": 0,
"payment_method": {"card_brand": "string",
"card_last_four_digits": "string",
"bank_name": "string",
"card_type": "string",
"holder_name": "string"
},
"plan": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"additional_details": {"widget_configuration": { }
},
"billing_frequency": "daily",
"date_created": 0,
"description": "string",
"name": "string",
"price": {"amount": 5000,
"currency_code": "MXN"
},
"product": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"additional_details": {"widget_configuration": { }
},
"date_created": 0,
"description": "string",
"external_product_id": "string",
"name": "string",
"subaccount_id": "string",
"status": "enabled"
},
"status": "active",
"payment_link": {"id": "string",
"url": "http://example.com"
}
},
"start_date": 0,
"status": "active"
}

Obtiene todas las suscripciones beta

Servicio utilizado para obtener todas las transacciones creadas por el comerciante. este servicio tiene una paginación que funciona por número de páginas.

Securityoauth2 or clientKey or sessionToken

Request

query Parameters

page	integer Default: 1 El número de página a consultar
page_size	integer [ 1 .. 100 ] Default: 15 Número de elementos por página a consultar. Los límites son inclusivos.
plan_id	string or null <uuid> Este id es utilizado para obtener todas las suscripciones que están relacionadas al plan dado. Si es `null` se regresarán todas las suscripciones. El valor por defecto es `null`

Responses

200

Información acerca de las suscripciones creadas por el comerciante

400

Detalles del error retornados cuando la petición falló.

401

Las credenciales no son válidas

get/subscription

Response samples

application/json

{"page_count": 0,
"item_count": 0,
"next": "string",
"previous": "string",
"subscription_list": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"auto_billing": true,
"billing_frequency": "daily",
"billing_day": 0,
"billing_method": "string",
"customer": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"date_created": 0,
"full_name": "string",
"primary_email": "user@example.com",
"primary_phone_number": "string"
},
"date_created": 0,
"end_date": 0,
"payment_method": {"card_brand": "string",
"card_last_four_digits": "string",
"bank_name": "string",
"card_type": "string",
"holder_name": "string"
},
"plan": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"additional_details": {"widget_configuration": { }
},
"billing_frequency": "daily",
"date_created": 0,
"description": "string",
"name": "string",
"price": {"amount": 5000,
"currency_code": "MXN"
},
"product": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"additional_details": {"widget_configuration": { }
},
"date_created": 0,
"description": "string",
"external_product_id": "string",
"name": "string",
"subaccount_id": "string",
"status": "enabled"
},
"status": "active",
"payment_link": {"id": "string",
"url": "http://example.com"
}
},
"start_date": 0,
"status": "active"
}
]
}

Crea un suscripción beta

Servicio utilizado para crear una suscripción relacionado a un plan para que el cliente pueda pagar y ser cobrado de acuerdo a la frecuencia de cobros especificada.

Securityoauth2 or clientKey or sessionToken

Request

Request Body schema: application/json

Información acerca de la suscripción que se va a crear

auto_billing	boolean Default: true Si al cliente se le cobrará automáticamente o no de acuerdo a la frecuencia de pagos.
billing_frequency	string Default: "monthly" Periodo de tiempo en el cual al cliente suscrito al plan, se le cobrará
billing_day	integer Día en el cual al cliente se le hará un cargo
billing_method	string Default: "card" Método al cuál se le hará el cargo al cliente
customer_email required	string <email> Email del cliente en el sistema hola.cash el cual se suscribirá al plan de suscripción
payment_token_id	string <uuid> ID del token de pago en el sistema hola.cash que será utilizado para pagar esta suscripción. Obligatorio si payment_token_alias no es informado.
payment_token_alias	string El token de pago a usar para pagar la suscripción. Obligatorio si payment_token_id no es informado.
plan_id required	string <uuid> ID del plan en el sistema hola.cash que será asociado a esta suscripción
start_date required	integer <int64> Fecha de inicio de la suscripción

Responses

200

Información acerca de las suscripciones creadas por el comerciante

400

Detalles del error retornados cuando la petición falló.

401

Las credenciales no son válidas

Callbacks

postSuscripción creada exitosamente.

postLa creación de la suscripción falló.

post/subscription

Request samples

Payload

application/json

{"auto_billing": true,
"billing_frequency": "monthly",
"billing_day": 0,
"billing_method": "card",
"customer_email": "user@example.com",
"payment_token_id": "80bcd4f6-0f4b-4ffe-94da-19dee5dcfe20",
"payment_token_alias": "string",
"plan_id": "00713021-9aea-41da-9a88-87760c08fa72",
"start_date": 0
}

Response samples

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"auto_billing": true,
"billing_date": 0,
"billing_frequency": "daily",
"customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
"date_created": 0,
"end_date": 0,
"payment_method": {"card_brand": "string",
"card_last_four_digits": "string",
"bank_name": "string",
"card_type": "string",
"holder_name": "string"
},
"plan_id": "00713021-9aea-41da-9a88-87760c08fa72",
"start_date": 0,
"status": "active"
}

Callback payload samples

application/json

{"event_type": "subscription_creation.succeeded",
"payload": {"auto_billing": true,
"billing_frequency": "monthly",
"customer_id": "e1317f33-5115-41da-9bfd-5091243e8ad4",
"date_created": 1658958437,
"id": "93e91fdb-fd17-455a-90f0-7125b6e0fc1a",
"payment_token_id": "2f1da9a6-648d-4e60-b184-7031f53a269f",
"plan_id": "4095b885-a0cf-4910-8478-f117447ae0ef",
"start_date": 1658958437,
"status": "incomplete"
}
}

Cancela una suscripción beta

Servicio utilizado para cancelar una suscripción relacionada a un plan para que el cliente no reciba un cargo en el siguiente periodo.

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

required

string <uuid>

El id del subscription a cancelar.

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

Request Body schema: application/json

Información adicional sobre la suscripción que deseas cancelar

cancellation_reason

string or null

Comentarios adicionales sobre la cancelación

Responses

200

Información acerca de las suscripción que acaba de ser cancelada

400

Detalles del error retornados cuando la petición falló.

401

Las credenciales no son válidas

Callbacks

postSuscripción cancelada exitosamente.

postLa cancelación de la suscripción falló.

post/subscription/{id}/cancel

Request samples

Payload

application/json

{"cancellation_reason": "string"
}

Response samples

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"auto_billing": true,
"billing_date": 0,
"billing_frequency": "daily",
"customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
"date_created": 0,
"end_date": 0,
"payment_method": {"card_brand": "string",
"card_last_four_digits": "string",
"bank_name": "string",
"card_type": "string",
"holder_name": "string"
},
"plan_id": "00713021-9aea-41da-9a88-87760c08fa72",
"start_date": 0,
"status": "active"
}

Callback payload samples

application/json

{"event_type": "subscription_update.succeeded",
"payload": {"auto_billing": true,
"billing_frequency": "monthly",
"customer_id": "e1317f33-5115-41da-9bfd-5091243e8ad4",
"date_created": 1658958437,
"id": "93e91fdb-fd17-455a-90f0-7125b6e0fc1a",
"payment_token_id": "2f1da9a6-648d-4e60-b184-7031f53a269f",
"plan_id": "4095b885-a0cf-4910-8478-f117447ae0ef",
"start_date": 1658958437,
"status": "cancelled"
}
}

Product

Un Producto es una representación de una cosa o servicio que un cliente está comprando.

Crea un producto beta

Servicio utilizado para crear un producto y poder ser ofrecido a los clientes.

Securityoauth2 or clientKey or sessionToken

Request

Request Body schema: application/json

Información acerca del producto que se quiere crear

external_product_id	string ID del producto en el sistema del comerciante
name required	string Nombre del producto. Normalmente este nombre es el que ve tu cliente
description required	string Descripción para ayudar a entender al cliente el producto
status	string Default: "enabled" Estado del producto actual. Si está `enabled` el producto puede usarse para crear planes. Enum: "enabled" "disabled"
	object Metadatos asociados al producto. Esta propiedad puede contener información sobre los beneficios o características que tiene el producto. Esta información es visible para los usuarios en el widget de pagos y plugings

Responses

200

Información acerca del producto que fue creado

400

Detalles del error retornados cuando la petición falló.

401

Las credenciales no son válidas

Callbacks

postProducto creado exitosamente.

postLa creación del producto falló.

post/product

Request samples

Payload

application/json

{"description": "My description",
"name": "My new product",
"additional_details": { },
"external_product_id": "My_external_order_id"
}

Response samples

application/json

{"id": "6a9f1b7a-9b8b-4f7c-8e6e-5739a9f9751d",
"description": "My description",
"name": "My new product",
"external_product_id": "My_external_order_id",
"additional_details": { },
"date_created": 1655485973,
"status": "enabled",
"subaccount_id": "6a9f1b7a-9b8b-4f7c-8e6e-5739a9f9751d"
}

Callback payload samples

application/json

{"event_type": "product_creation.succeeded",
"payload": {"id": "6a9f1b7a-9b8b-4f7c-8e6e-5739a9f9751d",
"description": "My description",
"name": "My new product",
"external_product_id": "My_external_order_id",
"additional_details": { },
"date_created": 1655485973,
"status": "enabled",
"subaccount_id": "6a9f1b7a-9b8b-4f7c-8e6e-5739a9f9751d"
}
}

Payment link

Los Payment links son una herramienta de ventas que permite realizar cobros aceptando todos los métodos de pago de una manera segura y acorde a los lineamientos del PCI , sin la necesidad de poseer una tienda en línea o e-commerce dónde integrar una pasarela de pagos.

Obtén la lista de links de pago

Regresa una la lista de los links de pago

SecuritysessionToken or clientKey

Request

query Parameters

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`.
after_id	string El ID del sistema usado como un punto de inicio para obetener la transacción siguiente

Responses

200

Lista de links de pagos con su información

400

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

401

Las credenciales no son válidas

get/payment_link

Response samples

application/json

{"has_next": false,
"last_cursor": null,
"has_previous": false,
"first_cursor": null,
"payment_links": [ ]
}

Crea un link de pago

Securityoauth2 or clientKey or sessionToken

Request

Request Body schema: application/json

Información del link de pago

description required	string Breve descripción del link de pago
	object (Amount) Detalle del monto
required	object (AmountConstraints) Los requisitos aplicados al monto
expiration_date required	integer <int64> (Timestamp) Fecha expresada en UTC Unix Epoch Time. Puedes visitar este sitio para convertir fechas en línea.
max_num_times_can_be_paid required	integer >= 1 Número máximo de veces que se pueden realizar pagos utilizando este link de pagos. Pon este campo como `1` si quieres que este link de pago sea de un único uso.
collect_customer_notes	boolean Default: false Dictamina si va a permitir que el usuario agregue notas asociadas al pago. Esto puedo ser útil en casos que quiera recolectar información del client como número de factura, etc. Si esta variable no es asignada, se le asigna el valor `false`.
	Array of objects Detalles adicionales para guardar información relacionadas a las notas
collect_customer_shipping_address	boolean Default: false Dictamina si va a permitir que el usuario agregue información de envío.
	object or null (PaymentMethodsConfiguration) Configuración de los métodos de pago para pagar el link de pago

Responses

200

Información del link de pago creado

400

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

401

Las credenciales no son válidas

post/payment_link

Request samples

Payload

application/json

{"expiration_date": 1755921639,
"amount": {"amount": 20000,
"currency_code": "MXN"
},
"description": "Unefon",
"max_num_times_can_be_paid": 1,
"collect_customer_notes": false,
"amount_constraints": {"conformance": "fixed",
"maximum_amount": {"amount": 20000,
"currency_code": "MXN"
},
"minimum_amount": {"amount": 20000,
"currency_code": "MXN"
}
}
}

Response samples

application/json

{"date_created": 1656136054,
"id": "ZrBX9nMbSl9Kis69L8",
"num_of_completed_transactions": 0,
"status": "active",
"status_details": {"date_created": 1644525047789,
"detail": null,
"message": null,
"status": "success"
},
"url": "http://127.0.0.1:8000/ZrBX9nMbSl9Kis69L8",
"payment_link": {"amount": {"amount": 20000,
"currency_code": "MXN"
},
"collect_customer_notes": false,
"description": "Unefon",
"expiration_date": 1755921639,
"max_num_times_can_be_paid": 1,
"amount_constraints": {"conformance": "fixed",
"maximum_amount": {"amount": 20000,
"currency_code": "MXN"
},
"minimum_amount": {"amount": 20000,
"currency_code": "MXN"
}
}
}
}

Obtén un link de pago

Obtén los detalles de un link de pago dado el payment_link_id

SecuritysessionToken or clientKey

Request

path Parameters

payment_link_id

required

string

El ID de un link de pago

Responses

200

Detalles del link de pago

400

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

401

Las credenciales no son válidas

get/payment_link/{payment_link_id}

Response samples

application/json

{"date_created": 1656136054,
"id": "ZrBX9nMbSl9Kis69L8",
"num_of_completed_transactions": 0,
"status": "active",
"status_details": {"date_created": 1644525047789,
"detail": null,
"message": null,
"status": "success"
},
"url": "http://127.0.0.1:8000/ZrBX9nMbSl9Kis69L8",
"payment_link": {"amount": {"amount": 20000,
"currency_code": "MXN"
},
"collect_customer_notes": false,
"description": "Unefon",
"expiration_date": 1755921639,
"max_num_times_can_be_paid": 1,
"amount_constraints": {"conformance": "fixed",
"maximum_amount": {"amount": 20000,
"currency_code": "MXN"
},
"minimum_amount": {"amount": 20000,
"currency_code": "MXN"
}
}
}
}

Actualiza un link de pago

Actualiza un link de pago dado el payment_link_id

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

payment_link_id

required

string

El ID de un link de pago

Request Body schema: application/json

Información a actualizar para el link de pago

status	string (PaymentLinkStatus) Estado del link de pago (i.e. Expirado, Activo, etc.) `active` cuando creamos un link de pago, estará activo por defecto. `expired` cuando un link de pago supera la fecha de caducidad, entonces su estado caducó. `completed` cuando hayamos realizado el número máximo de pagos permitidos para un link de pago, se completará. `disabled` cuando marcamos un link de pago como cancelado para que ya no pueda recibir pagos, se mostrará deshabilitado. Enum: "expired" "active" "completed" "disabled"
description	string Breve descripción del link de pago
expiration_date	integer <int64> (Timestamp) Fecha expresada en UTC Unix Epoch Time. Puedes visitar este sitio para convertir fechas en línea.
collect_customer_notes	boolean Dictamina si va a permitir que el usuario agregue notas asociadas al pago. Esto puedo ser útil en casos que quiera recolectar información del client como número de factura, etc.
	Array of objects Detalles adicionales para guardar información relacionadas a las notas
collect_customer_shipping_address	boolean Dictamina si va a permitir que el usuario agregue información de envío.
	object or null (PaymentMethodsConfiguration) Configuración de los métodos de pago para pagar el link de pago

Responses

200

Link de pago actualizado

400

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

401

Las credenciales no son válidas

patch/payment_link/{payment_link_id}

Request samples

Payload

application/json

{"status": "active"
}

Response samples

application/json

{"date_created": 1656136054,
"id": "ZrBX9nMbSl9Kis69L8",
"num_of_completed_transactions": 0,
"status": "active",
"status_details": {"date_created": 1644525047789,
"detail": null,
"message": null,
"status": "success"
},
"url": "http://127.0.0.1:8000/ZrBX9nMbSl9Kis69L8",
"payment_link": {"amount": {"amount": 20000,
"currency_code": "MXN"
},
"collect_customer_notes": false,
"description": "Unefon",
"expiration_date": 1755921639,
"max_num_times_can_be_paid": 1,
"amount_constraints": {"conformance": "fixed",
"maximum_amount": {"amount": 20000,
"currency_code": "MXN"
},
"minimum_amount": {"amount": 20000,
"currency_code": "MXN"
}
}
}
}

Testing

Simula el completado de cargos pay_with_bank_account y pay_with_store en modo SANDBOX.

Una vez que crea un cargo de tipo pay_with_bank_account o pay_with_store, obtiene un id. Puede usar ese 'id' de cargo para completar la transacción de cargo. Esta funcionalidad solo funciona en ambientes SANDBOX.

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

required

string

El ID del cargo que se quiere completar.

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

Responses

200

El cargo.

400

Cargo no encontrado.

401

Las credenciales no son válidas

404

El cargo no está pendiente.

post/testing/transaction/complete/{id}

Request samples

cURL

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

Response samples

application/json

{"success_message": "string"
}

Simula la cancelación de cargos pay_with_bank_account y pay_with_store en modo SANDBOX.

Una vez que crea un cargo de tipo pay_with_bank_account o pay_with_store, obtiene un id. Puede usar ese 'id' de cargo para cancelar la transacción de cargo. Esta funcionalidad solo funciona en ambientes SANDBOX.

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

required

string

El ID del cargo que se quiere cancelar.

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

Responses

200

El cargo.

400

Cargo no encontrado.

401

Las credenciales no son válidas

404

El cargo no está pendiente.

post/testing/transaction/cancel/{id}

Request samples

cURL

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

Response samples

application/json

{"success_message": "string"
}

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.

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

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

application/json

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