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 una vez dadas las credenciales de pago.

Usa tu llave pública o privada. Genera un token de pago para tarjetas de crédito o débito que puedes almacenar en tu sistema para completar una o varias transacciones. Lee el Tutorial 3DS 2.0 para más detalle sobre cómo enviar la información requerida y brindarle a tus clientes una experiencia de compra 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
application/json
{
  • "credential": {
    },
  • "consumer_details": {
    }
}
Response samples
application/json
{
  • "status_details": {
    },
  • "token_details": {
    }
}

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
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 --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": {
    },
  • "token_details": {
    }
}

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
id
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
application/json
{
  • "consumer_details": {
    }
}
Response samples
application/json
{
  • "status_details": {
    },
  • "token_details": {
    }
}

Transaction

Crea, captura, reembolsa u obtiene cargos.

Crea un cargo.

Se puede usar la llave secreta o pública. 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

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

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

Muestra los detalles de lo que se autorizó.
Revisa additional_detail para más información relacionada al resultado mostrado.
Por ejemplo, additional_detail puede contener el authorization_code
para transacciones realizadas con tarjeta de débito o crédito si el
banco pertinente lo provee.

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
application/json
{
  • "description": "This is a test description",
  • "amount_details": {
    },
  • "payment_detail": {
    },
  • "consumer_details": {
    },
  • "billing_details": {
    },
  • "shipping_details": {
    },
  • "processing_instructions": {
    }
}
Response samples
application/json
{
  • "charge": {
    },
  • "id": "8fa9a35e-3ece-4085-860c-4deb4c9e28ed",
  • "status_details": {
    }
}
Callback payload samples
application/json
{
  • "event_type": "charge.succeeded",
  • "payload": {
    },
  • "id": "8fa9a35e-3ece-4085-860c-4deb4c9e28ed",
  • "status_details": {
    }
}

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

Obtiene el detalle de un cargo

Una vez se haya realizado un cargo exitoso obtendrás un id que puedes utilizar después para obtener detalles de la transacción. Adicional a esto, se te regresa un authorization_code bajo los status_detail.detail.additional_details

Securityoauth2 or clientKey or sessionToken
Request
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 --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": {
    },
  • "id": "8fa9a35e-3ece-4085-860c-4deb4c9e28ed",
  • "status_details": {
    }
}

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
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 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
application/json
{
  • "amount": 5000,
  • "currency_code": "MXN"
}
Response samples
application/json
{
  • "capture_transaction_id": "f2e43795-fce4-424c-880a-f6c1fed8cdf7",
  • "captured_amount": {
    },
  • "status_details": {
    }
}
Callback payload samples
application/json
{
  • "event_type": "capture.succeeded",
  • "payload": {
    }
}

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
application/json
{
  • "description": "This is a test description",
  • "amount_details": {
    },
  • "payment_detail": {
    },
  • "consumer_details": {
    },
  • "billing_details": {
    },
  • "shipping_details": {
    },
  • "processing_instructions": {
    }
}
Response samples
application/json
{
  • "options_list_id": "0a3f8ea5-78c4-4680-8952-3c7bee7f022a",
  • "options": [
    ]
}

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
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 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
application/json
{
  • "amount": 5000,
  • "currency_code": "MXN"
}
Response samples
application/json
{
  • "refund_transaction_id": "db068fc2-f07d-4a5d-bd23-59aa5595d7f4",
  • "status_details": {
    }
}
Callback payload samples
application/json
{
  • "event_type": "refund.succeeded",
  • "payload": {
    }
}

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

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

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
application/json
{
  • "order_total_amount": {
    },
  • "description": "This is a test order",
  • "purchases": [
    ]
}
Response samples
application/json
{
  • "order": {
    }
}
Callback payload samples
application/json
{
  • "event_type": "order_creation.succeeded",
  • "payload": {
    }
}

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
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 --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": {
    },
  • "order_information": {
    }
}

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
id
required
string

El ID de la orden por actualizar

Example: f435579e-37c6-49b2-98c5-a22a49a433e9
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

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
application/json
{
  • "order_total_amount": {
    },
  • "description": "This is a test order",
  • "purchases": [
    ]
}
Response samples
application/json
{
  • "order": {
    },
  • "order_information": {
    }
}

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 --location --request GET 'https://sandbox.api.holacash.mx/v2/checkout/button?public_key=<USE PUBLIC KEY>'
Response samples
application/json
{
  • "date_created": 1643093191130,
  • "detail": {
    },
  • "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": [
    ]
}

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

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
application/json
{
  • "name": "My plan",
  • "description": "My plan description",
  • "additional_details": { },
  • "product_id": "09f53b82-295a-452b-b7e5-09a1b0e5b834",
  • "price": {
    }
}
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": {},
  • "price": {
    },
  • "product_id": "aa87e96e-62b2-493a-bcd3-8536f7c71a02",
  • "status": "active"
}
Callback payload samples
application/json
{
  • "event_type": "plan_creation.succeeded",
  • "payload": {
    }
}

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

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
id
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": {
    },
  • "billing_frequency": "daily",
  • "date_created": 0,
  • "description": "string",
  • "name": "string",
  • "price": {
    },
  • "product": {
    },
  • "status": "active",
  • "payment_link": {}
}

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
id
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": {
    },
  • "date_created": 0,
  • "end_date": 0,
  • "payment_method": {
    },
  • "plan": {
    },
  • "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": [
    ]
}

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
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": {
    },
  • "plan_id": "00713021-9aea-41da-9a88-87760c08fa72",
  • "start_date": 0,
  • "status": "active"
}
Callback payload samples
application/json
{
  • "event_type": "subscription_creation.succeeded",
  • "payload": {
    }
}

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
id
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
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": {
    },
  • "plan_id": "00713021-9aea-41da-9a88-87760c08fa72",
  • "start_date": 0,
  • "status": "active"
}
Callback payload samples
application/json
{
  • "event_type": "subscription_update.succeeded",
  • "payload": {
    }
}

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

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