API to the Hola Cash platform.
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.
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.
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 |
Successful operation
Invalid request, see the response for detail.
The security credentials are not valid
Too many requests per minute. Please retry the request with an exponential backoff.
{- "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"
}
}
}
{- "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"
}
}
Requires the secret key for authentication. Returns the payment token along with additional descriptive information. Please see PaymentCredentialMetadata
for the sort of information returned.
Successful operation.
Invalid request, see the response for detail.
The security credentials are not valid
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 ''
{- "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"
}
}
Requires the secret key for authentication. Returns the payment token along with additional descriptive information. Please see PaymentCredentialMetadata
for the sort of information returned.
Successful operation.
Invalid request, see the response for detail.
The security credentials are not valid
{- "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"
}
}
}
{- "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"
}
}
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.
The order object.
Successfully created an order.
Invalid request, see the response for detail.
The security credentials are not valid
Too many requests per minute. Please retry the request with an exponential backoff.
{- "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": [ ]
}
{- "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": [ ]
}
}
{- "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"
}
}
}
}
Can use the secret or the public key. Returns and order given and ID on the Hola Cash system.
Successful obtained the oder
Invalid request, see the response for detail.
The security credentials are not valid
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 ''
{- "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"
}
}
Can use the secret or the public key. Returns and order given and ID on the HolaCash system.
The order object.
Successful updated the oder
Invalid request, see the response for detail.
The security credentials are not valid
{- "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": [ ]
}
{- "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"
}
}
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.
Details on what you need to authorize.
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
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 atdetail.additional_details
for more information for the next steps.
If the payment_method
is credit_or_debit_card
then your may get3ds_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 indetail.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
The security credentials are not valid
{- "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
}
}
{- "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"
}
}
{- "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"
}
}
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.
search_key | string Query param used to search by:
|
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 |
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 |
payment_methods | string The payment method type of the charges. This is a comma separated list of values from |
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
|
Information related to the charges
Check the detail.code
property from the response. These are the error codes that the service might return:
Check Error codes
section for more details.
The security credentials are not valid
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'
{- "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"
}
}
]
}
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
The charge.
The security credentials are not valid
Charge was not found.
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 ''
{- "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"
}
}
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
The amount to capture.
Successful operation.
Invalid request, see the response for detail.
The security credentials are not valid
{- "amount": 5000,
- "currency_code": "MXN"
}
{- "capture_transaction_id": "f2e43795-fce4-424c-880a-f6c1fed8cdf7",
- "captured_amount": {
- "amount": 5000,
- "currency_code": "MXN"
}, - "status_details": {
- "message": "captured",
- "status": "success"
}
}
{- "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"
}
}
}
}
Use secret key. Will return a list with the available installment options if any or an empty array otherwise
Charge to evaluate
Successful operation.
Invalid request, see the response for detail.
The security credentials are not valid
{- "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
}
}
{- "options_list_id": "0a3f8ea5-78c4-4680-8952-3c7bee7f022a",
- "options": [
- {
- "id": 1,
- "unit": "months",
- "value": 3
}, - {
- "id": 2,
- "unit": "months",
- "value": 6
}
]
}
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
.
The amount to refund.
Successful operation.
Invalid request, see the response for detail.
The security credentials are not valid
{- "amount": 5000,
- "currency_code": "MXN"
}
{- "refund_transaction_id": "db068fc2-f07d-4a5d-bd23-59aa5595d7f4",
- "status_details": {
- "message": "refunded",
- "status": "success"
}
}
{- "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"
}
}
}
}
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
The checkout button image.
Invalid request. See the response for detail
The security credentials are not valid
curl --location --request GET 'https://sandbox.api.holacash.mx/v2/checkout/button?public_key=<USE PUBLIC KEY>'
{- "date_created": 1643093191130,
- "detail": {
- "additional_details": [ ],
- "code": "invalid_security_credentials",
- "message": "The security credentials are not valid"
}, - "message": "Could not authenticate",
- "status": "failure"
}
Service used to get all the invoices related to a subscription.
Information about the requested invoices
Error details returned when the request failed.
The security credentials are not valid
{- "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"
}
]
}
Service used to get all the payment intents related to a subscription.
Information about the requested payment intents
Error details returned when the request failed.
The security credentials are not valid
{- "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"
}
]
}
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.
Information about the plan you want to create
Information about the plan just created
Error details return when the request failed.
The security credentials are not valid
{- "name": "My plan",
- "description": "My plan description",
- "additional_details": { },
- "product_id": "09f53b82-295a-452b-b7e5-09a1b0e5b834",
- "price": {
- "amount": 1000,
- "currency_code": "MXN"
}
}
{- "additional_details": { },
- "billing_frequency": "monthly",
- "date_created": 1658956845,
- "description": "My description",
- "id": "02e036d8-f71c-47b4-8f22-3510bffc4e25",
- "name": "hello new product",
- "price": {
- "amount": 50121,
- "currency_code": "MXN"
}, - "product_id": "aa87e96e-62b2-493a-bcd3-8536f7c71a02",
- "status": "active"
}
{- "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",
- "price": {
- "amount": 50121,
- "currency_code": "MXN"
}, - "product_id": "aa87e96e-62b2-493a-bcd3-8536f7c71a02",
- "status": "active"
}
}
Service used to get all the subscriptions plans created by the merchant.
Information about the plan just created
Error details return when the request failed.
The security credentials are not valid
{- "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,
}
]
}
Service used to get the plan details of the given plan Id.
Information about the plan
Error details return when the request failed.
The security credentials are not valid
{- "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",
}
Service used to get the details of the given subscription created by the merchant.
Information about the subscription created
Error details return when the request failed.
The security credentials are not valid
{- "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",
}, - "start_date": 0,
- "status": "active"
}
Service used to get all the subscriptions created by the merchant. This service has a pagination that works with a number of pages.
Information about the subscriptions created by the merchant
Error details return when the request failed.
The security credentials are not valid
{- "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",
}, - "start_date": 0,
- "status": "active"
}
]
}
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.
Information about the subscriptionthat you want to create
Information about the subscriptions created by the merchant
Error details return when the request failed.
The security credentials are not valid
{- "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
}
{- "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"
}
{- "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"
}
}
Service used to cancel a subscription related to a plan so that the client will not be billed again in the next billing period.
Additional information about the subscription that you wish to cancel
Information about the subscription that was just cancelled
Error details return when the request failed.
The security credentials are not valid
{- "cancellation_reason": "string"
}
{- "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"
}
{- "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"
}
}
Service used to create a product to be offered to customers.
Information about the product you want to create
Information about the product just created
Error details return when the request failed.
The security credentials are not valid
{- "description": "My description",
- "name": "My new product",
- "additional_details": { },
- "external_product_id": "My_external_order_id"
}
{- "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"
}
{- "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 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.
Returns a list of payment links
List of payment links details
Invalid request. See the response for detail
The security credentials are not valid
{- "has_next": false,
- "last_cursor": null,
- "has_previous": false,
- "first_cursor": null,
- "payment_links": [ ]
}
Creates a payment link
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 |
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 |
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 |
Information about the created payment link
Invalid request. See the response for detail
The security credentials are not valid
{- "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"
}
}
}
{- "date_created": 1656136054,
- "id": "ZrBX9nMbSl9Kis69L8",
- "num_of_completed_transactions": 0,
- "status": "active",
- "status_details": {
- "date_created": 1644525047789,
- "detail": null,
- "message": null,
- "status": "success"
}, - "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 the details of a payment link by payment_link_id
Details of the payment link
Invalid request. See the response for detail
The security credentials are not valid
{- "date_created": 1656136054,
- "id": "ZrBX9nMbSl9Kis69L8",
- "num_of_completed_transactions": 0,
- "status": "active",
- "status_details": {
- "date_created": 1644525047789,
- "detail": null,
- "message": null,
- "status": "success"
}, - "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 the payment link given the payment_link_id
Updates to the payment link
status | string (PaymentLinkStatus) Payment link status (i.e. Expired, Active, etc.). |
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 |
Updated payment link
Invalid request. See the response for detail
The security credentials are not valid
{- "status": "active"
}
{- "date_created": 1656136054,
- "id": "ZrBX9nMbSl9Kis69L8",
- "num_of_completed_transactions": 0,
- "status": "active",
- "status_details": {
- "date_created": 1644525047789,
- "detail": null,
- "message": null,
- "status": "success"
}, - "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"
}
}
}
}
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.
The charge.
Charge was not found.
The security credentials are not valid
Charge was not pending.
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 ''
{- "success_message": "string"
}
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.
The charge.
Charge was not found.
The security credentials are not valid
Charge was not pending.
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 ''
{- "success_message": "string"
}
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.
Successful obtained the continuation info
Invalid request, see the response for detail.
The security credentials are not valid