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

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
id
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 --location --request GET 'https://sandbox.api.holacash.mx/v2/tokenization/payment_token/5c86fac0-08a5-4c71-92be-a6f3a770de2d' \
--header 'X-Api-Client-Key: <USE SECRET KEY>' \
--data-raw ''
Response samples
application/json
{
  • "status_details": {
    },
  • "token_details": {
    }
}

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

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.

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. 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
  • 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 : string 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

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.

object (AdditionalDetails)

Additional address information that does not fit into a structured address

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

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

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
id
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 --location --request GET 'https://sandbox.api.holacash.mx/v2/transaction/charge/f2e43795-fce4-424c-880a-f6c1fed8cdf7' \
--header 'X-Api-Client-Key: <USE SECRET KEY>' \
--data-raw ''
Response samples
application/json
{
  • "charge": {
    },
  • "id": "8fa9a35e-3ece-4085-860c-4deb4c9e28ed",
  • "status_details": {
    }
}

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

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.

object (AdditionalDetails)

Additional address information that does not fit into a structured address

Responses
200

Successful operation.

400

Invalid request, see the response for detail.

401

The security credentials are not valid

post/transaction/lookup
Request samples
application/json
{
  • "description": "This is a test description",
  • "amount_details": {
    },
  • "payment_detail": {
    },
  • "consumer_details": {
    },
  • "billing_details": {
    },
  • "shipping_details": {
    },
  • "processing_instructions": {
    }
}
Response samples
application/json
{
  • "options_list_id": "0a3f8ea5-78c4-4680-8952-3c7bee7f022a",
  • "options": [
    ]
}

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

Order

Create order

Creates an order.

Can use the secret or the public key. An order object or it's id on the HolaCashs it's id on the HolaCash system can be used along with the calls to make a charge in /transaction/charge. This associates the order with the Charge

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. 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
  • 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 : string 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

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.

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.

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

Gets 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
id
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 --location --request GET 'https://sandbox.api.holacash.mx/v2/order/f435579e-37c6-49b2-98c5-a21a49a433e9' \
--header 'X-Api-Client-Key: <USE PUBLIC OR SECRET KEY>' \
--data-raw ''
Response samples
application/json
{
  • "order": {
    },
  • "order_information": {
    }
}

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

The id of the order to update

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

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.

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.

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

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

Subscription

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

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

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
application/json
{
  • "name": "My plan",
  • "description": "My plan description",
  • "additional_details": { },
  • "product_id": "09f53b82-295a-452b-b7e5-09a1b0e5b834",
  • "price": {
    }
}
Response samples
application/json
{
  • "additional_details": { },
  • "billing_frequency": "monthly",
  • "date_created": 1658956845,
  • "description": "My description",
  • "id": "02e036d8-f71c-47b4-8f22-3510bffc4e25",
  • "name": "hello new product",
  • "payment_link": {},
  • "price": {
    },
  • "product_id": "aa87e96e-62b2-493a-bcd3-8536f7c71a02",
  • "status": "active"
}
Callback payload samples
application/json
{
  • "event_type": "plan_creation.succeeded",
  • "payload": {
    }
}

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

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

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

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
application/json
{
  • "auto_billing": true,
  • "billing_frequency": "monthly",
  • "billing_day": 0,
  • "billing_method": "card",
  • "customer_email": "user@example.com",
  • "payment_token_id": "80bcd4f6-0f4b-4ffe-94da-19dee5dcfe20",
  • "payment_token_alias": "string",
  • "plan_id": "00713021-9aea-41da-9a88-87760c08fa72",
  • "start_date": 0
}
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "auto_billing": true,
  • "billing_date": 0,
  • "billing_frequency": "daily",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "date_created": 0,
  • "end_date": 0,
  • "payment_method": {
    },
  • "plan_id": "00713021-9aea-41da-9a88-87760c08fa72",
  • "start_date": 0,
  • "status": "active"
}
Callback payload samples
application/json
{
  • "event_type": "subscription_creation.succeeded",
  • "payload": {
    }
}

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
id
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
application/json
{
  • "cancellation_reason": "string"
}
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "auto_billing": true,
  • "billing_date": 0,
  • "billing_frequency": "daily",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "date_created": 0,
  • "end_date": 0,
  • "payment_method": {
    },
  • "plan_id": "00713021-9aea-41da-9a88-87760c08fa72",
  • "start_date": 0,
  • "status": "active"
}
Callback payload samples
application/json
{
  • "event_type": "subscription_update.succeeded",
  • "payload": {
    }
}

Product

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
application/json
{
  • "description": "My description",
  • "name": "My new product",
  • "additional_details": { },
  • "external_product_id": "My_external_order_id"
}
Response samples
application/json
{
  • "id": "6a9f1b7a-9b8b-4f7c-8e6e-5739a9f9751d",
  • "description": "My description",
  • "name": "My new product",
  • "external_product_id": "My_external_order_id",
  • "additional_details": { },
  • "date_created": 1655485973,
  • "status": "enabled",
  • "subaccount_id": "6a9f1b7a-9b8b-4f7c-8e6e-5739a9f9751d"
}
Callback payload samples
application/json
{
  • "event_type": "product_creation.succeeded",
  • "payload": {
    }
}

Testing

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
id
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 --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
id
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 --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
id
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}
Request samples
curl --location --request GET 'https://sandbox.api.holacash.mx/v2/continuation/f435579e-37c6-49b2-98c5-a21a49a433e9' \
--header 'X-Api-Client-Key: <USE PUBLIC OR SECRET KEY>' \
--data-raw ''
Response samples
application/json
{
  • "created_on": 1643144893400,
  • "charge_id": "f435579e-37c6-49b2-98c5-a22a49a433e9",
  • "action": "3ds_authenticate"
}