Nothing Found

Iniciar sesión

Nothing Found

Hola Cash eCommerce API (1.0.0)

API to the Hola Cash platform.

Supports:
- Tokenization: Create and get payment tokens for credit cards.
- Transaction: Charge, capture, refunds or get payments.
- Order: Create or get orders.
- Checkout: Get the checkout button to embed in your app or web page.

Tokenization

Create and get an opaque payment token for a credit card. This token is used to create a Charge. Create a token from your web or mobile application so that you do not need to send credit information to your servers. Use these test card numbers to trigger different flows in your integration and ensure they are handled accordingly. Note: Use a public key in X-Api-Client-Key header. Never make a secret key publicly visible.

Creates a token once given payment credentials.

Uses the secret or the public key. Generates an opaque payment token for credit or debit cards that you can store in your system to complete one or more transactions. Read the 3DS tutorial to understand how to send information to give your customers a frictionless shopping experience.

Securityoauth2 or clientKey or sessionToken

Request

header Parameters

X-Cash-Anti-Fraud-Metadata

string

Use to send information to the system to combat fraud. The data sent over as a header is a JSON name/value structure converted to string and then base64 encoded. Better fraud detection results when you send this data.<

NOTE: make sure you collect this information from at client side.<\br><\br> The names are as follows:

The following are a set of required parameters. A request will be rejected if these are not present when the header is required. - `ip_address`: This should be valid ipv4 or ipv6 address as a string - `device_id` : Send the id of the device submitting the request. The format and content of the `device_id` is specific to your system. - `user_timezone` : Offset from UTC of the user. The format is +/-HH:MM ex: -08:00. You can use code of you client/web application ex: `date.getTimezoneOffset()` in `javascript` or a user property you associate with the user on your system

The following are a set of important but not required parameters. Sending this data helps better detect fraud.

user-agent-string : Browser user agent string. We highly recommend that you send this value when possible as it allows us to derive most of the other important values
is_rooted_device : true/false
is_incognito : true/false
location_latitude : float value
location_longitude : float value
os_version: string value
os_type : string value
phone_brand : string value
phone_carrier : string value
battery_level : float value
is_battery_charging : true/false
is_connected_to_wifi : true/false
screen_resolution_width : float value
screen_resolution_height : float value
window_position_x : float value
window_position_y : float value
color_depth : float value
pixel_depth : float value
pixel_ratio : float value

Example: ewogICAgImlwX2FkZHJlc3MiOiIxMjMuMTIzLjEyMy4xMjMiLAogICAgImRldmljZV9pZCIgOiAiMTIzNDU2IiwKICAgICJ1c2VyX3RpbWV6b25lIiA6IiswMzozNCIsCiAgICAidXJsX2RvbWFpbl9uYW1lIiA6ImhvbGFjYXNoLm14IiwKICAgICJicm93c2VyX3ZlcnNpb24iIDoiMTIzIiwKICAgICJicm93c2VyX25hbWUiIDoiTW96aWxsYSIsCiAgICAiYnJvd3Nlcl90aW1lem9uZSIgOiJQU1QiLAogICAgInNjcmVlbl9yZXNvbHV0aW9uX3dpZHRoIiA6IjEyMyIsCiAgICAic2NyZWVuX3Jlc29sdXRpb25faGVpZ2h0IiA6IjEyMyIsCiAgICAid2luZG93X3Bvc2l0aW9uX3giIDoiMTIzIiwKICAgICJ3aW5kb3dfcG9zaXRpb25feSIgOiIxMjMiLAogICAgImNvbG9yX2RlcHRoIiA6IjEyMyIKfQ====

Request Body schema: application/json

Information about the payment credential that needs to be tokenized.

required	object (PaymentCredential) Details of the payment credential used to make the payment
required	object (ConsumerDetail) Details about the consumer

Responses

200

Successful operation

400

Invalid request, see the response for detail.

401

The security credentials are not valid

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

Get a previously created payment token

Requires the secret key for authentication. Returns the payment token along with additional descriptive information. Please see PaymentCredentialMetadata for the sort of information returned.

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

required

string

The id of the payment token.

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

Responses

200

Successful operation.

400

Invalid request, see the response for detail.

401

The security credentials are not valid

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

Update a previously created payment token

Requires the secret key for authentication. Returns the payment token along with additional descriptive information. Please see PaymentCredentialMetadata for the sort of information returned.

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

required

string

The id of the payment token.

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

Request Body schema: application/json

Information about the payment credential that needs to be updated.

required

object (ConsumerDetail)

Details about the consumer

Responses

200

Successful operation.

400

Invalid request, see the response for detail.

401

The security credentials are not valid

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

Order

Create order

Creates an order.

Creates an order in the Hola Cash system. The order_id returned can be linked to a Charge. The public or secret key can be used to call this API.

For additional information you believe is important to be send in the request, please take a look at the additional_details property.

Securityoauth2 or clientKey or sessionToken

Request

header Parameters

X-Cash-Anti-Fraud-Metadata

string

The following are a set of required parameters. A request will be rejected if these are not present when the header is required. - `ip_address`: This should be valid ipv4 or ipv6 address as a string - `device_id` : Send the id of the device submitting the request. The format and content of the `device_id` is specific to your system. - `user_timezone` : Offset from UTC of the user. The format is +/-HH:MM ex: -08:00. You can use code of you client/web application ex: `date.getTimezoneOffset()` in `javascript` or a user property you associate with the user on your system

The following are a set of important but not required parameters. Sending this data helps better detect fraud.

user-agent-string : Browser user agent string. We highly recommend that you send this value when possible as it allows us to derive most of the other important values
is_rooted_device : true/false
is_incognito : true/false
location_latitude : float value
location_longitude : float value
os_version: string value
os_type : string value
phone_brand : string value
phone_carrier : string value
battery_level : float value
is_battery_charging : true/false
is_connected_to_wifi : true/false
screen_resolution_width : float value
screen_resolution_height : float value
window_position_x : float value
window_position_y : float value
color_depth : float value
pixel_depth : float value
pixel_ratio : float value

Request Body schema: application/json

The order object.

required	object (Amount) Amount details
description required	string
	object (PaymentDetail) Details of the payment. Note that `address`, `contact` and `name` for this object are deprecated. Please use `charge.billing_details` to provide this information
	object (BillingDetails) Details of the owner of the payment credential. *Note In order to secure high approval rates, it is important that you send - first_name, last_name, email, phone_1, address_line_1, country_code, locality, postal_code, region_name_or_code
	object (ShippingDetails) Details on where the purchase needs to be shipped. *Note In order to secure high approval rates, it is important that you send - first_name, last_name, email, phone_1, address_line_1, country_code, locality, postal_code, region_name_or_code
	object (ConsumerDetail) Details about the consumer
	Array of objects (OrderItem) non-empty Details on items that were purchased.
	Array of objects (Note) Represents a list of notes you may want to add to an order.
external_system_order_id	string Order identifier provided by the merchant. Usually the order_id of the merchant's internal system.
	object (AdditionalDetails) Property to send additional information to attach to this request. Hola Cash recognizes some special fields that can be sent in the create order or create charge requests for internal processing and/or reporting. This list of fields is included below. sub_merchant_id alphanumeric string with the support of the following special characters: `+, _, .`. If this field contains invalid characters, the API will fail with validation errors. sub_merchant_name If you send these special fields in both the create charge and the create order, the create charge values will take precendence. Validations: The length of the "name" should be minimum 1 and maximum 100 characters. The length of the "data" should be minimum 1 and maximum 250 characters.

Responses

200

Successfully created an order.

400

Invalid request, see the response for detail.

401

The security credentials are not valid

429

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

Callbacks

postOrder created successfully.

postOrder creation failed.

postOrder update succeeded.

postOrder update failed.

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

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

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

Gets the order with a specific ID.

Can use the secret or the public key. Returns and order given and ID on the Hola Cash system.

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

required

string

The ID of the order to fetch

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

Responses

200

Successful obtained the oder

400

Invalid request, see the response for detail.

401

The security credentials are not valid

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

Updates the order with a specific ID.

Can use the secret or the public key. Returns and order given and ID on the HolaCash system.

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

required

string

The id of the order to update

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

header Parameters

X-Cash-Anti-Fraud-Metadata

string

The following are a set of required parameters. A request will be rejected if these are not present when the header is required. - `ip_address`: This should be valid ipv4 or ipv6 address as a string - `device_id` : Send the id of the device submitting the request. The format and content of the `device_id` is specific to your system. - `user_timezone` : Offset from UTC of the user. The format is +/-HH:MM ex: -08:00. You can use code of you client/web application ex: `date.getTimezoneOffset()` in `javascript` or a user property you associate with the user on your system

The following are a set of important but not required parameters. Sending this data helps better detect fraud.

user-agent-string : Browser user agent string. We highly recommend that you send this value when possible as it allows us to derive most of the other important values
is_rooted_device : true/false
is_incognito : true/false
location_latitude : float value
location_longitude : float value
os_version: string value
os_type : string value
phone_brand : string value
phone_carrier : string value
battery_level : float value
is_battery_charging : true/false
is_connected_to_wifi : true/false
screen_resolution_width : float value
screen_resolution_height : float value
window_position_x : float value
window_position_y : float value
color_depth : float value
pixel_depth : float value
pixel_ratio : float value

Request Body schema: application/json

The order object.

	object (Amount) Amount details
description	string
	object (PaymentDetail) Details of the payment. Note that `address`, `contact` and `name` for this object are deprecated. Please use `charge.billing_details` to provide this information
	object (BillingDetails) Details of the owner of the payment credential. *Note In order to secure high approval rates, it is important that you send - first_name, last_name, email, phone_1, address_line_1, country_code, locality, postal_code, region_name_or_code
	object (ShippingDetails) Details on where the purchase needs to be shipped. *Note In order to secure high approval rates, it is important that you send - first_name, last_name, email, phone_1, address_line_1, country_code, locality, postal_code, region_name_or_code
	object (ConsumerDetail) Details about the consumer
	Array of objects (OrderItem) non-empty Details on items that were purchased.
	Array of objects (Note) Represents a list of notes you may want to add to an order.
external_system_order_id	string Order identifier provided by the merchant. Usually the order_id of the merchant's internal system.
	object (AdditionalDetails) Property to send additional information to attach to this request. Hola Cash recognizes some special fields that can be sent in the create order or create charge requests for internal processing and/or reporting. This list of fields is included below. sub_merchant_id alphanumeric string with the support of the following special characters: `+, _, .`. If this field contains invalid characters, the API will fail with validation errors. sub_merchant_name If you send these special fields in both the create charge and the create order, the create charge values will take precendence. Validations: The length of the "name" should be minimum 1 and maximum 100 characters. The length of the "data" should be minimum 1 and maximum 250 characters.

Responses

200

Successful updated the oder

400

Invalid request, see the response for detail.

401

The security credentials are not valid

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

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

Transaction

Create, capture, refund or get a charge.

Creates a Charge.

Can use the secret or the public key. Charge an amount to a payment credential (ex: credit_or_debit_card or pay_with_bank_account). You either place a hold on the funds using this api and capture the funds later when you have completed the purchase or you can complete the charge in a single call. Only credit/debit cards support the behavior where you can separate holding and capturing the funds. See the processing_instructions in the Charge object for more information. Use these test card numbers to trigger different flows in your integration and ensure they are handled accordingly. Read the 3DS tutorial to understand how to send information so that your customers have a frictionless experience. Read the description of error code 400 in the response to understand how to work with transactions that need additional information to continue.

For additional information you believe is important to be send in the request, please take a look at the additional_details property.

Securityoauth2 or clientKey or sessionToken

Request

header Parameters

X-Cash-Anti-Fraud-Metadata

string

The following are a set of required parameters. A request will be rejected if these are not present when the header is required. - `ip_address`: This should be valid ipv4 or ipv6 address as a string - `device_id` : Send the id of the device submitting the request. The format and content of the `device_id` is specific to your system. - `user_timezone` : Offset from UTC of the user. The format is +/-HH:MM ex: -08:00. You can use code of you client/web application ex: `date.getTimezoneOffset()` in `javascript` or a user property you associate with the user on your system

The following are a set of important but not required parameters. Sending this data helps better detect fraud.

user-agent-string : Browser user agent string. We highly recommend that you send this value when possible as it allows us to derive most of the other important values
is_rooted_device : true/false
is_incognito : true/false
location_latitude : float value
location_longitude : float value
os_version: string value
os_type : string value
phone_brand : string value
phone_carrier : string value
battery_level : float value
is_battery_charging : true/false
is_connected_to_wifi : true/false
screen_resolution_width : float value
screen_resolution_height : float value
window_position_x : float value
window_position_y : float value
color_depth : float value
pixel_depth : float value
pixel_ratio : float value

Request Body schema: application/json

Details on what you need to authorize.

description required	string
required	object (Amount) Amount details
	object (PaymentDetail) Details of the payment. Note that `address`, `contact` and `name` for this object are deprecated. Please use `charge.billing_details` to provide this information
	object (ProcessingInstruction) Hints on how you want the transaction to be processed.
	object Details of the purchase
	object (ConsumerDetail) Details about the consumer
	object (BillingDetails) Details of the owner of the payment credential. *Note In order to secure high approval rates, it is important that you send - first_name, last_name, email, phone_1, address_line_1, country_code, locality, postal_code, region_name_or_code
	object (ShippingDetails) Details on where the purchase needs to be shipped. *Note In order to secure high approval rates, it is important that you send - first_name, last_name, email, phone_1, address_line_1, country_code, locality, postal_code, region_name_or_code
	object (AdditionalDetails) Property to send additional information to attach to this request. Hola Cash recognizes some special fields that can be sent in the create order or create charge requests for internal processing and/or reporting. This list of fields is included below. sub_merchant_id alphanumeric string with the support of the following special characters: `+, _, .`. If this field contains invalid characters, the API will fail with validation errors. sub_merchant_name If you send these special fields in both the create charge and the create order, the create charge values will take precendence. Validations: The length of the "name" should be minimum 1 and maximum 100 characters. The length of the "data" should be minimum 1 and maximum 250 characters.

Responses

200

Details on what was authorized.
See additional_detail for information related to the result.
For example, additional_detail may contain authorization_code
for credit/debit card transactions if the bank provides one

400

Check the status variable on the response object to determine next steps.
The status could be failure, pending or success

When the status is pending please take a look at the detail.code.
If the detail.code indicates action_required then look at
detail.additional_details for more information for the next steps.

If the payment_method is credit_or_debit_card then your may get
3ds_authenticate in the action field in detail.additional_details.
In case redirect the customer to the URL specified in redirect_url.
See the 3DS tutorial for more information

If the payment_method is pay_with_store or pay_with_bank_account
then your may get collect_payment in the action field in
detail.additional_details. In this case use the provided information
in the additional_details to direct the customer to complete the payment
See the Cash Payment tutorial or Bank Transfer tutorial for more information

If the payment_method is pay_with_bnpl then your may get complete_at_bnpl_provider
in the action field in detail.additional_details. In this case redirect the customer
to the URL specified in redirect_url
See the BNPL tutorial for more information

In either of the above situations you can continue to the poll the system
using the /transaction/{id} endpoint or register for a webhook to get
notified of the result of processing

401

The security credentials are not valid

Callbacks

postCharge succeeded event.

postChange pending event

postCharge failed event

postCharge cancelled event.

postDisbursement succeeded event.

postDisbursement failed event.

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",
"phone_1": 5512345678
},
"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",
"phone_1": 5512345678
},
"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"
},
{"data": "801585",
"name": "authorization_code"
}
]
},
"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"
}
}

Gets a list of charges.

Use the secret key. Gets a paginated list of charges in real time ordered by creation date in descendent order. The pagination works on a cursor based fashion, where the response object contains information about the current cursor and the list of transactions belonging the page size (limit). These are some query parameters that you can use:

limit - Maximum number of transactions to be returned.
after_id - Request transaction after that pointer based on the limit.
before_id - Request transaction before that pointer based on the limit.

You can find all the available query parameters in the Query Parameters section in the Request section. Response object attributes of the cursor :

first_cursor - Indicates the newest cursor from limit from the current response.
has_next - Indicates they are older transactions to retrieve.
has_previous - Indicates that are newer transactions to retrieve.
last_cursor - Indicates the oldest cursor from limit from the current response.

Sending both after_id and before_id or an invalid cursor will cause an error (after_id_and_before_id_both_present and integrity_or_database_issue respectively). Check Error codes section for more details. To move forward among transactions pages, send the value of first_cursor in the before_id request parameter. To move backward among transactions pages, send the value of last_cursor in the after_id request parameter.

Securityoauth2 or clientKey or sessionToken

Request

query Parameters

search_key	string Query param used to search by: `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> The start time of search range in UTC expressed here in Unix Epoch Time. You can check this site to convert dates online.
end_time	integer <int64> The end time of search range in UTC expressed here in Unix Epoch Time. You can check this site to convert dates online.
limit	integer The number of transactions in a set. The minimun value is `1` (inclusive) and the maximum value is `100` (inclusive). If this query param is not present in the API call the default value will be `10`.
before_id	string ID in the system as the starting point to get transaction before
after_id	string ID in the system as the starting point to get transaction after.
monthly_installments	string Boolean flag to indicate if the transaction was done through MSI.
transaction_status	string The status of the charges. This is a comma separated list of values from `TransactionStatus`
payment_methods	string The payment method type of the charges. This is a comma separated list of values from `PaymentMethods`
payment_networks	string Comma separated string of valid BNPL Payment Networks
subscription	string Boolean flag to indicate if the transaction was paid by a subscription
channel	string Channel through which the customer paid. This is a comma separated string of the following channels plugin.woocommerce plugin.magento commerce_api checkout_widget payment_link

Responses

200

Information related to the charges

400

Check the detail.code property from the response. These are the error codes that the service might return:

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

Check Error codes section for more details.

401

The security credentials are not valid

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

Gets a charge.

Once you run an charge, you get an id if the charge is successful. You can use this charge id to look up the details for this charge transaction later. Additionally authorization_code is returned under status_details.detail.additional_details

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

required

string

The id of the charge to be returned.

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

Responses

200

The charge.

401

The security credentials are not valid

404

Charge was not found.

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"
},
{"data": "801585",
"name": "authorization_code"
}
]
},
"message": "charge created",
"status": "success"
}
}

Captures a previous successfully uncaptured charge.

Use secret key. If you only held funds during the charge by setting the auto_capture to false or not including (defaults to false), then you can use this API to capture some/all of the un-captured funds. A charge is capturable when it's status is completed. You can only capture a charge once at which point the status of the charge changes to captured

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

required

string

The id of the charge that is to be captured.

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

Request Body schema: application/json

The amount to capture.

amount required	integer Non-negative integer representing the amount in the smallest unit for the currency. $50 MXN will be represented as 5000 (meaning 50 pesos 0 cents, or $50.00 MXN).
currency_code required	string Three character currency code Value: "MXN"

Responses

200

Successful operation.

400

Invalid request, see the response for detail.

401

The security credentials are not valid

Callbacks

postCapture succeeded event

postCapture failed event

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

Lookup if a charge is elegible for monthly installment options.

Use secret key. Will return a list with the available installment options if any or an empty array otherwise

Securityoauth2 or clientKey or sessionToken

Request

query Parameters

monthly_installments

required

boolean

Indicate that we are looking up installment options

Request Body schema: application/json

Charge to evaluate

description required	string
required	object (Amount) Amount details
	object (PaymentDetail) Details of the payment. Note that `address`, `contact` and `name` for this object are deprecated. Please use `charge.billing_details` to provide this information
	object (ProcessingInstruction) Hints on how you want the transaction to be processed.
	object Details of the purchase
	object (ConsumerDetail) Details about the consumer
	object (BillingDetails) Details of the owner of the payment credential. *Note In order to secure high approval rates, it is important that you send - first_name, last_name, email, phone_1, address_line_1, country_code, locality, postal_code, region_name_or_code
	object (ShippingDetails) Details on where the purchase needs to be shipped. *Note In order to secure high approval rates, it is important that you send - first_name, last_name, email, phone_1, address_line_1, country_code, locality, postal_code, region_name_or_code
	object (AdditionalDetails) Property to send additional information to attach to this request. Hola Cash recognizes some special fields that can be sent in the create order or create charge requests for internal processing and/or reporting. This list of fields is included below. sub_merchant_id alphanumeric string with the support of the following special characters: `+, _, .`. If this field contains invalid characters, the API will fail with validation errors. sub_merchant_name If you send these special fields in both the create charge and the create order, the create charge values will take precendence. Validations: The length of the "name" should be minimum 1 and maximum 100 characters. The length of the "data" should be minimum 1 and maximum 250 characters.

Responses

200

Successful operation.

400

Invalid request, see the response for detail.

401

The security credentials are not valid

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",
"phone_1": 5512345678
},
"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",
"phone_1": 5512345678
},
"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
}
]
}

Refunds a prior charge that was captured.

Use a secret key. If you ran the charge with the auto_capture processing_instruction set to false and you did not capture, then only the full amount of the charge is refunded regardless of the amount you specify. This in effect cancels the charge. If you ran the charge with the auto_capture processing_instruction set to true then you can refund up to the full amount of the charge.

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

required

string

The id of the charge that is to be refunded.

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

Request Body schema: application/json

The amount to refund.

amount required	integer Non-negative integer representing the amount in the smallest unit for the currency. $50 MXN will be represented as 5000 (meaning 50 pesos 0 cents, or $50.00 MXN).
currency_code required	string Three character currency code Value: "MXN"

Responses

200

Successful operation.

400

Invalid request, see the response for detail.

401

The security credentials are not valid

Callbacks

postRefund succeeded.

postRefund failed event.

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

Checkout

Access checkout related configuration

Gets the checkout button.

Returns the checkout button for a merchant. Note: We currently return the same button for all clients and will introduce capability to customize the button in a later release

SecurityclientPublicKeyInQueryString

Responses

200

The checkout button image.

400

Invalid request. See the response for detail

401

The security credentials are not valid

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

Create and manage subscriptions and plans

Get all invoices beta

Service used to get all the invoices related to a subscription.

Securityoauth2 or clientKey or sessionToken

Request

query Parameters

page	integer Default: 1 The number of the page to fetch
page_size	integer [ 1 .. 100 ] Default: 15 Number of elements return by page to fetch. The limits are inclusive.
subscription_id	string <uuid> This id is used to get only the invoices related to the given subscription.

Responses

200

Information about the requested invoices

400

Error details returned when the request failed.

401

The security credentials are not valid

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

Get all payment intents beta

Service used to get all the payment intents related to a subscription.

Securityoauth2 or clientKey or sessionToken

Request

query Parameters

page	integer Default: 1 The number of the page to fetch
page_size	integer [ 1 .. 100 ] Default: 15 Number of elements return by page to fetch. The limits are inclusive.
invoice_id	string <uuid> This id is used to get only the payment intents related to the given invoice.
subscription_id	string <uuid> This id is used to get only the payment intents related to the given subscription.

Responses

200

Information about the requested payment intents

400

Error details returned when the request failed.

401

The security credentials are not valid

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

Creates a plan beta

Service used to create a subscription plan to be offered to customers. This plan needs a product associated, see the product section for more information.

Securityoauth2 or clientKey or sessionToken

Request

Request Body schema: application/json

Information about the plan you want to create

billing_frequency	string Default: "monthly" The period of time or frequency when the customer subscribed to this plan will be billed Enum: "weekly" "bi_weekly" "monthly" "annual" "daily"
description required	string Information visible to the customers that can include as much detail the users would need to know the benefits that they can get by subscribing to this plan
	object This property can contain information about how the plan will be displayed and Payment widget configuration settings.
name required	string Name of the plan. Typically this is the commercial name of the plan displayed to your customer. For example, “Premium”, “Basic”, “Familiar”, etc.
required	object The price (amount) that will be billed every billing cycle to the billing method
product_id required	string Id of the product to be associated to this plan. This is the id that `POST /product` returns.

Responses

200

Information about the plan just created

400

Error details return when the request failed.

401

The security credentials are not valid

Callbacks

postPlan created successfully.

postPlan creation failed.

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

Get all plans beta

Service used to get all the subscriptions plans created by the merchant.

Securityoauth2 or clientKey or sessionToken

Request

query Parameters

page	integer Default: 1 The number of the page to fetch
page_size	integer [ 1 .. 100 ] Default: 15 Number of elements return by page to fetch. The limits are inclusive.

Responses

200

Information about the plan just created

400

Error details return when the request failed.

401

The security credentials are not valid

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

Get details of a given plan beta

Service used to get the plan details of the given plan Id.

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

required

string <uuid>

The id of the plan to be fetched.

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

Responses

200

Information about the plan

400

Error details return when the request failed.

401

The security credentials are not valid

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

Get details of a subscription beta

Service used to get the details of the given subscription created by the merchant.

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

required

string <uuid>

The id of the subscription to fetch.

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

Responses

200

Information about the subscription created

400

Error details return when the request failed.

401

The security credentials are not valid

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

Get all subscriptions beta

Service used to get all the subscriptions created by the merchant. This service has a pagination that works with a number of pages.

Securityoauth2 or clientKey or sessionToken

Request

query Parameters

page	integer Default: 1 The number of the page to fetch
page_size	integer [ 1 .. 100 ] Default: 15 Number of elements return by page to fetch. The limits are inclusive.
plan_id	string or null <uuid> This id is used to get all the subscriptions that are related to the given plan. If `null` all the subscriptions will be fetched. Default value is `null`.

Responses

200

Information about the subscriptions created by the merchant

400

Error details return when the request failed.

401

The security credentials are not valid

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

Creates a subscription beta

Service used to create a subscription related to a plan so that the client can pay and be billed according to the billing frequency specified.

Securityoauth2 or clientKey or sessionToken

Request

Request Body schema: application/json

Information about the subscriptionthat you want to create

auto_billing	boolean Default: true Wheter the client will be billing automatically or not according to the billing frequency
billing_frequency	string Default: "monthly" The period of time or frequency when the customer subscribed to this plan will be billed
billing_day	integer Day in which the customer will be billed
billing_method	string Default: "card" Method used to charged the client
customer_email required	string <email> Email of the customer on the hola.cash system that is going to be subscribed to the subscription plan
payment_token_id	string <uuid> ID of the payment token on the hola.cash system that is going to be used to pay this subscription. Required if payment_token_alias is not informed.
payment_token_alias	string The payment token alias to be used for paying a subscription. Required if payment_token_id is not informed.
plan_id required	string <uuid> ID of the plan on the hola.cash system that is going to be associated to this subscription
start_date required	integer <int64> Start date of the subscription

Responses

200

Information about the subscriptions created by the merchant

400

Error details return when the request failed.

401

The security credentials are not valid

Callbacks

postSubscription created successfully.

postSubscription creation failed.

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

Cancels a subscription beta

Service used to cancel a subscription related to a plan so that the client will not be billed again in the next billing period.

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

required

string <uuid>

The id of the subscription to cancel.

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

Request Body schema: application/json

Additional information about the subscription that you wish to cancel

cancellation_reason

string or null

Additional comments for the cancellation

Responses

200

Information about the subscription that was just cancelled

400

Error details return when the request failed.

401

The security credentials are not valid

Callbacks

postSubscription cancelled successfully.

postSubscription cancellation failed.

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

A Product is a representation of a thing or service a customer is buying.

Creates a product beta

Service used to create a product to be offered to customers.

Securityoauth2 or clientKey or sessionToken

Request

Request Body schema: application/json

Information about the product you want to create

external_product_id	string ID of the product on the merchant system
name required	string Name of the product. Typically this is displayed to your customer
description required	string A helpful description to help the customer understand the product
status	string Default: "enabled" Status of the current product. If `enabled` the product can be used to create a plan. Enum: "enabled" "disabled"
	object Associated metadata for this product. This property can hold information about the benefits or features that the product has. This information is visible to the users in Payment Widget and plugins

Responses

200

Information about the product just created

400

Error details return when the request failed.

401

The security credentials are not valid

Callbacks

postProduct created successfully.

postProduct creation failed.

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

Payment links are a safe and PCI-compliant solution that allows you to collect payments through a variety of payment methods, without having to set up an online checkout platform.

Gets a list of payment links

Returns a list of payment links

SecuritysessionToken or clientKey

Request

query Parameters

limit	integer The number of transactions in a set. The minimun value is `1` (inclusive) and the maximum value is `100` (inclusive). If this query param is not present in the API call the default value will be `10`.
after_id	string ID in the system as the starting point to get transaction after.

Responses

200

List of payment links details

400

Invalid request. See the response for detail

401

The security credentials are not valid

get/payment_link

Response samples

application/json

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

Creates a payment link

Securityoauth2 or clientKey or sessionToken

Request

Request Body schema: application/json

Information about this payment link

description required	string Short description of the payment link
	object (Amount) Amount details
required	object (AmountConstraints) The constraints that apply to an amount
expiration_date required	integer <int64> (Timestamp) Date in UTC expressed here in Unix EpochTime. You can check this site to convert dates online.
max_num_times_can_be_paid required	integer >= 1 The maximum number of times a payment can be made using this payment link. Set it to `1` if you want a one-time use payment link.
collect_customer_notes	boolean Default: false Configure this payment link to collect notes from the customer. Notes can be used to collect instructions or additional information from the customer to the merchant. When not specified, this defaults to `false`
	Array of objects Additional details to save information related to the notes
collect_customer_shipping_address	boolean Default: false Configure this payment link to collect shipping address from the customer.
	object or null (PaymentMethodsConfiguration) Payment method configuration used to pay this payment link
collect_billing_information	boolean Default: false Enable this to allow input of billing information
	object (ThemeStyle) Object that contains look and feel style information

Responses

200

Information about the created payment link

400

Invalid request. See the response for detail

401

The security credentials are not valid

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

Get a payment link

Get the details of a payment link by payment_link_id

SecuritysessionToken or clientKey

Request

path Parameters

payment_link_id

required

string

The ID of the payment link

Responses

200

Details of the payment link

400

Invalid request. See the response for detail

401

The security credentials are not valid

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

Updates a payment link

Updates the payment link given the payment_link_id

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

payment_link_id

required

string

The ID of the payment link

Request Body schema: application/json

Updates to the payment link

status	string (PaymentLinkStatus) Payment link status (i.e. Expired, Active, etc.). `active` when we create a payment link it will be active by default. `expired` when a payment link passes expiration_date then its status would be expired. `completed` when we have made the maximum number of payments allowed for a payment link it will be completed. `disabled` when we mark a payment link as cancelled so that it can not receive payments anymore then it will be shown disbaled. Enum: "expired" "active" "completed" "disabled"
description	string Short description of the payment link
expiration_date	integer <int64> (Timestamp) Date in UTC expressed here in Unix EpochTime. You can check this site to convert dates online.
collect_customer_notes	boolean Configure this payment link to collect notes from the customer. Notes can be used to collect instructions or additional information from the customer to the merchant.
	Array of objects Additional details to save information related to the notes
collect_customer_shipping_address	boolean Configure this payment link to collect shipping address from the customer.
collect_billing_information	boolean Enable this to allow input of billing information
	object or null (PaymentMethodsConfiguration) Payment method configuration used to pay this payment link

Responses

200

Updated payment link

400

Invalid request. See the response for detail

401

The security credentials are not valid

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

Simulates completing pay_with_bank_account and pay_with_store charges in SANDBOX mode

Once you create a charge type pay_with_bank_account or pay_with_store, you get an id. You can use that charge id to Complete the charge transaction. This functionality only works in SANDBOX environment.

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

required

string

The ID of the charge to be completed.

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

Responses

200

The charge.

400

Charge was not found.

401

The security credentials are not valid

404

Charge was not pending.

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

Simulates cancelling pay_with_bank_account and pay_with_store charges in SANDBOX mode

Once you create a charge type pay_with_bank_account or pay_with_store, you get an id. You can use that charge id to Cancel the charge transaction. This functionality only works in SANDBOX environment.

Securityoauth2 or clientKey or sessionToken

Request

path Parameters

required

string

The ID of the charge to be cancelled.

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

Responses

200

The charge.

400

Charge was not found.

401

The security credentials are not valid

404

Charge was not pending.

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

Gets the continuation info of a transaction given the id of the continuation.

The continuation id is the UUID value at the end of the continuation URL returned by the create charge when you need to direct the user to get consent using 3DS, for example. Can use secret or public key. Returns information about the charge associated to this 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

Successful obtained the continuation info

400

Invalid request, see the response for detail.

401

The security credentials are not valid

get/continuation/{id}