Cash Developer Portal
Crear cuenta

Support

Whatsapp
      
        Home
      HOLA.CASH API
        Quickstart
        API Reference
          Hola Cash eCommerce API
          tokenization
          transaction
          order
          checkout
          subscription
          product
          continuation
          payment_link
          testing
        Error codes
        Testing cards
        Sample code
      CHECKOUT WIDGET
        Quickstart
        Sample code
      E-COMMERCE PLUGINS
        Magento
        Woocommerce
      Ayuda
        Tutorials
        FAQs
      
        Contact sales




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.

Details of Error codes returned by the API in the StatusDetail object in detail.code

Error codes list
Error code Description
successOperation successful
generic_errorAn error has occurred
invalid_responseAn unexpected error occurred
unauthorizedYou're not allowed to perform this operation
validation_errorThe request contains validation errors
action_requiredFurther action is required
new_cvv_requiredNew CVV value required
blocked_by_hola_cash_fraud_detectionThis action was blocked by hola.cash fraud detection
transaction_blockedThe transaction has been blocked
invalid_security_credentialsThe security credentials are not valid
invalid_anti_fraud_header_multipleMultiple instances of the anti-fraud header found. Just send one
invalid_anti_fraud_header_formatInvalid format for anti-fraud header, must be a valid JSON object that is converted to string and base64 encoded
invalid_anti_fraud_header_missing_ip_addressInvalid anti-fraud header, missing ip_address
invalid_anti_fraud_header_missing_device_idInvalid anti-fraud header, missing device_id
invalid_anti_fraud_header_missing_user_timezoneInvalid anti-fraud header, missing user_timezone
invalid_anti_fraud_header_invalid_user_timezoneInvalid format for user_timezone in the anti-fraud header
invalid_anti_fraud_header_invalid_ip_addressInvalid format for ip_address in the anti-fraud header
bank_account_clabe_unrecognizableCLABE is invalid
bank_account_clabe_already_existsCLABE is already in use
bank_account_clabe_associated_with_hola_cashYou cannot use this CLABE with hola.cash
bank_account_clabe_not_supported_spei_with_hola_cashThis CLABE is not supported with hola.cash
transaction_not_owned_by_cashuserYou do not own this transaction
transaction_already_completedTransaction is already completed
transaction_needs_more_information_to_completeMore information is required to complete the transaction
transaction_data_mismatchCould not find this transaction
transaction_pending_information_missingPending transaction with missing information
transaction_version_mismatchVersion mismatch
transaction_tid_invalidTransaction not found
transaction_pin_requiredPIN required to perform the transaction
transaction_already_cancelled_or_completedNo more actions possible on the transaction. The transaction has already been completed or cancelled
target_subaccount_not_openMerchant not valid
subaccount_not_verifiedInvalid merchant configuration. Merchant hasn't been verified
subscription_not_createdInvalid merchant configuration. Missing information
merchant_payment_disabledInvalid merchant configuration
merchant_is_cash_merchantInvalid merchant configuration
payment_method_not_allowedPayment method is not allowed
transaction_not_valid_capture_targetCannot capture this charge
transaction_capture_amount_greater_than_transaction_amountCannot capture more than original amount
transaction_not_valid_capture_target_already_capturedCharge was already captured
transaction_not_valid_capture_target_already_settledCharge was already settled
transaction_not_valid_capture_target_no_funds_to_captureCannot capture more than original amount
transaction_not_valid_capture_target_was_refundedCharge was already refunded
transaction_not_valid_refund_target_no_funds_to_refundCannot refund more than original amount
transaction_not_valid_refund_target_has_chargebackCannot refund, transaction has a chargeback
transaction_not_valid_refund_target_payment_method_type_not_supported_for_refundsPayment method type is not currently supported for refunds
transaction_not_valid_refund_target_transaction_created_date_invalidThe transaction exceeded the maximum time to make a refund.
transaction_not_valid_refund_target_subaccount_transacting_user_does_not_existsSubaccount transacting_user is not available for this subaccount
transaction_not_valid_capture_target_payment_method_type_not_supported_for_capturesPayment method type is not currently supported for captures
transaction_not_valid_completion_target_was_not_pendingTransaction to be completed is not longer in pending status
transaction_not_valid_cancellation_target_was_not_pendingTransaction to be cancelled is not longer in pending status
amount_limit_exceededYou have exceeded amount permitted on this card. Please use a different card or contact your bank
codi_transaction_blockedThis CODI transaction has been block, please try again later
credit_card_expired_yearCredit card is expired. Please correct the expiry information or use a different card
credit_card_expired_monthCredit card is expired. Please correct the expiry information or use a different card
incorrect_pinThe PIN is incorrect, please use a correct PIN and try again
credit_card_number_invalidCredit card number invalid. Please correct the information or use a different card
credit_card_expiredCredit card is expired. Please correct the expiry information or use a different card
credit_card_validation_code_requiredEnter a card validation code (CVV) and try again
test_credit_cardThis is a test credit card. Use a different credit card and try again
credit_card_validation_code_invalidCredit card validation code is not valid. Enter a valid code and try again
three_ds_authentication_failed3DS card authentication failed. Enter valid authentication and try again
credit_card_insufficient_fundsThis card does not have sufficient funds, please add fund or user a different card and try again
credit_card_stolenThe card was reported as stolen
credit_card_fraud_detectedThis transaction was blocked by hola.cash fraud detection
credit_card_purchase_not_supportedThis purchase is not permitted on this card. Please use a different card and try again or contact your bank
credit_card_not_supported_on_lineOnline purchases are not permitted for this card. Please contact your bank or use a different card and try again
credit_card_lostThe card was reported as lost
credit_card_restricted_by_bankThe bank has restricted the card
credit_card_hold_cardThe bank has requested the card to be retained
credit_card_call_bank_to_authorizeBank authorization is required for this charge. Please contact your bank or use a different card and try again
refund_failed_retry_after_24_hourTransaction can not be partially refunded today, try tomorrow.
temporary_error_try_again_laterThere was an error completing this transaction, please try again
card_declinedThis card has been declined by your bank. Please use a different card or contact your bank
order_not_foundThe requested order was not found
payment_token_not_validThe payment token is not valid
card_amount_highEnter a lower amount for the purchase and try again
card_amount_lowEnter a higher amount for the purchase and try again
data_issues_contact_hola_cashYour transaction has issues with the data submitted. Please contact hola.cash support to correct
merchant_email_address_already_existsMerchant email already exists
merchant_phone_number_already_existsMerchant phone number already exists
merchant_address_is_requiredMerchant address is required
invalid_merchant_categoryInvalid merchant category
merchant_username_already_existsMerchant username already exists
merchant_generic_validation_errorMerchant form contains validation errors
create_processor_account_failed_retryThis transaction attempt failed. Please retry in a few minutes
funds_transfer_not_supportedYour bank does not allow this action
card_withdrawal_limit_exceededYour bank has declined the transaction as the withdrawal limit has been exceeded
issuer_not_supportedYour bank does not support this card issuer
card_already_register_with_userThis card cannot be used for this transaction. Please use another card
invalid_card_expiryThe expiration date on this card is not valid. Please review the expiration date
3D_authentication_failed3DS authentication failed. Please try again or use another card
user_not_allowed_to_perform_transactionYou are not allowed to perform this action
service_errorService error
generic_processing_errorThe operation is not allowed for this customer or transaction
order_is_requiredThe hola.cash order id is required to be able to use use_order_payment_detail processing instruction as True
payment_detail_is_requiredTo create the charge you need to pass payment_detail and customer_details
order_payment_detail_and_customer_details_are_requiredThe provided hola.cash order should have associated the payment_detail and customer_details so we can execute the charge
order_already_associated_with_chargeThe provided hola.cash order is already associated to an existing completed charge
continuation_not_foundThe external reference id is not found.
invalid_query_paramThe query param provided in the API call is invalid
merchant_sub_account_does_not_existThe merchant does not have a subaccount related
merchant_does_not_existThe merchant does not exist
limit_out_of_boundsThe limit query param is invalid
integrity_or_database_issueThere was an issue performing the query, make sure that the query parameters are correct
invalid_cursor_after_or_beforeThe query param `after_id` or `before_id` must be a base64 string
after_id_and_before_id_both_presentMake sure to only send one of the following query param [after_id, before_id]
store_card_token_validation_failedstore card token validation failed
invalid_email_addressInvalid email address
digital_service_purchase_failureWe couldn't process the digital service purchase
payment_link_cannot_be_updatedWe cannot make this update to given payment link
payment_link_does_not_existsThis payment link does not exists.
payment_link_update_validation_errorThe body of the payment link update request has some validation error
payment_link_cannot_be_disabledTo disable a payment link make sure the current status of the payment link is 'active'
payment_link_cannot_be_enabledTo enable a payment link make sure the current status of the payment link is 'disabled'
payment_link_cannot_be_enabled_already_paid_max_timeswe cannot activate a payment link if it has already been paid maximum times
payment_link_cannot_be_enabled_past_expiration_datewe cannot activate a payment link if it has already been expired
amount_constraints_max_amount_exceeds_limitamount_constraints.maximum_amount must be less than the established max amount limit stablish for your account for payment link creation
amount_exceeds_limitThe amount must be less than the established max amount limit stablish for your account for payment link creation
amount_constraints_min_amount_lesser_than_minimum_limitamount_constraints.minimum_amount must be greater than the established min amount limit stablish for your account for payment link creation
amount_lesser_than_minimum_limitThe amount must be greater than the established min amount limit stablish for your account for payment link creation
create_charge_generic_validation_errorGeneral validation error on create charge
create_charge_invalid_phone_numberInvalid phone_number error on create charge
subscriptions_customer_not_foundThe customer provided was not found in the system. The subscription can not be created.
subscriptions_plan_not_foundThe plan provided was not found in the system. The subscription can not be created
subscriptions_inactive_planYou can not create a subscription with an inactive plan
plan_payment_link_creation_failedPayment link creation failed during plan creation
customer_could_not_be_createdThe customer could not be created in the system
subscription_could_not_be_createdThe subscription could not be created in the system
subscription_not_foundThe suscription was not found in the system
username_or_password_missing_errorUsername and/or Password to create login user were not provided
username_validation_did_not_pass_errorUsername validation did not pass, it must be a valid email address
password_validation_did_not_pass_errorPassword validation did not pass
payment_method_could_not_be_createdThe payment method could not be created in the system

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 given payment credentials.

Can use the secret or the public key. Generates an opaque payment token for credit or debit cards so that you can store the token can be stored on your system to complete one/more transactions.

SecurityclientKey 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 (ConsumerDetail)

Details about the consumer

required
object (PaymentCredential)

Details of the payment credential used to make the payment

Responses
200

Successful operation

400

Invalid request, see the response for detail.

401

The security credentials are not valid

429

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

post/tokenization/payment_token
Request samples
  • Payload
  • cURL
application/json
{
  • "consumer_details": {
    • "contact": {
      • "email": "abc@abc.com"
      },
    • "name": {
      • "first_last_name": "Cash",
      • "first_name": "Test",
      • "second_first_name": "Hola",
      • "second_last_name": "User"
      }
    },
  • "credential": {
    • "credit_or_debit_card": {
      • "card_number": "4242424242424242",
      • "card_validation_code": "123",
      • "expiration_month": "12",
      • "expiration_year": "2034"
      },
    • "payment_method": {
      • "method": "credit_or_debit_card"
      }
    }
}
Response samples
  • 200
  • 400
application/json
{
  • "status_details": {
    • "date_created": "1643073307052,",
    • "message": "token created",
    • "status": "success"
    },
  • "token_details": {
    • "additional_details": [
      • {
        • "data": "visa",
        • "name": "card_brand"
        },
      • {
        • "data": "34",
        • "name": "expiration_year"
        },
      • {
        • "data": "12",
        • "name": "expiration_month"
        },
      • {
        • "data": "4242",
        • "name": "card_last_four_digits"
        }
      ],
    • "token": "5c86fac0-08a5-4c71-92be-a6f3a770de2d"
    }
}

Get a previously created payment token

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

SecurityclientKey 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
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
  • 200
  • 400
application/json
{
  • "status_details": {
    • "date_created": 1643086863215,
    • "message": "token obtained",
    • "status": "success"
    },
  • "token_details": {
    • "additional_details": [
      • {
        • "data": "visa",
        • "name": "card_brand"
        },
      • {
        • "data": "34",
        • "name": "expiration_year"
        },
      • {
        • "data": "12",
        • "name": "expiration_month"
        },
      • {
        • "data": "424242",
        • "name": "card_bin"
        },
      • {
        • "data": "4242",
        • "name": "card_last_four_digits"
        },
      • {
        • "data": "abc@abc.com",
        • "name": "holder_email"
        },
      • {
        • "data": "Snoop the Doggy Dog",
        • "name": "holder_name"
        }
      ],
    • "token": "5c86fac0-08a5-4c71-92be-a6f3a770de2d"
    }
}

transaction

Create, capture, refund or get a charge.

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

SecurityclientKey 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). The smallest value allowed is 1 MXN represented as 100.

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 failed event
postCapture succeeded event
post/transaction/capture/{id}
Request samples
  • Payload
  • cURL
application/json
{
  • "amount": 5000,
  • "currency_code": "MXN"
}
Response samples
  • 200
  • 400
application/json
{
  • "capture_transaction_id": "f2e43795-fce4-424c-880a-f6c1fed8cdf7",
  • "captured_amount": {
    • "amount": 5000,
    • "currency_code": "MXN"
    },
  • "status_details": {
    • "message": "captured",
    • "status": "success"
    }
}
Callback payload samples
application/json
{
  • "event_type": "capture.failed",
  • "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": "abcd",
          • "name": {
            • "first_last_name": "Cash",
            • "first_name": "Test",
            • "second_first_name": "Hola",
            • "second_last_name": "User"
            }
          },
        • "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"
              }
            }
          }
        },
      • "id": "8fa9a35e-3ece-4085-860c-4deb4c9e28ed",
      • "status_details": {
        • "date_created": 1643144893400,
        • "detail": {
          • "additional_details": [ ],
          • "code": "transaction_not_valid_capture_target_already_settled",
          • "message": "Charge was already settled"
          },
        • "message": "Could not capture charge",
        • "status": "failure"
        }
      }
    }
}

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.

SecurityclientKey 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
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

Responses
200

Information related to the charges

400

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

  • invalid_query_param
  • merchant_sub_account_does_not_exist
  • merchant_does_not_exist
  • limit_out_of_bounds
  • integrity_or_database_issue
  • invalid_cursor_after_or_before
  • after_id_and_before_id_both_present

Check Error codes section for more details.

401

The security credentials are not valid

get/transaction/charge
Request samples
  • Default request
  • Request with limit
  • Request with filters
  • Request with after_id and filters
curl --location --request GET 'https://sandbox.api.holacash.mx/v2/transaction/charge' \
--header 'X-Api-Client-Key: <USE SECRET KEY>' \
--header 'Content-Type: application/json'
Response samples
  • 200
  • 400
application/json
{
  • "has_next": true,
  • "has_previous": false,
  • "last_cursor": "MjAyMi0wMy0wMyAwNjo0MDozNS44MzY4MjYrMDA6MDA=",
  • "merchant_payment_transactions": [
    • {
      • "TID": "d49efac5-c834-4ff9-ae92-c8678148601a",
      • "amount_details": {
        • "amount": 5000,
        • "currency_code": "MXN"
        },
      • "charge_status": "completed",
      • "creator_email": "test_user@example.com",
      • "date_created": 1650904681,
      • "description": "Pago por cuenta bancaria",
      • "is_refundable": false,
      • "original_amount": {
        • "amount": 5000,
        • "currency_code": "MXN"
        },
      • "payment_info": {
        • "external_system_order_id": "my_order_id",
        • "holacash_system_order_id": "3966995a-0853-4b19-83aa-d242e223a14b",
        • "payment_method": "pay_with_bank_account",
        • "transaction_clabe": "646180280999990299"
        },
      • "payment_link_id": "DR3LzwGjcXn5zZOaWX"
      }
    ]
}

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.

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

object (AdditionalDetails)

Additional address information that does not fit into a structured address

required
object (Amount)

Amount details

object (ConsumerDetail)

Details about the consumer

description
required
string
object (PaymentDetail)

Details of the payment

object (ProcessingInstruction)

Hints on how you want the transaction to be processed.

object

Details of the purchase

object (ShippingDetails)

Details on where the purchase needs to be shipped.

Responses
200

Details on what was authorized.

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 on 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
  • 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
  • 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 case redirect the customer to the URL specified in redirect_url 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 cancelled event.
postCharge failed event
postChange pending event
postCharge succeeded event.
post/transaction/charge
Request samples
  • Payload
  • cURL
application/json
{
  • "amount_details": {
    • "amount": 5000,
    • "currency_code": "MXN"
    },
  • "consumer_details": {
    • "contact": {
      • "email": "test_user@example.com",
      • "id": "1234"
      },
    • "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": "4242424242424242",
        • "card_validation_code": "324",
        • "expiration_month": "12",
        • "expiration_year": "2024"
        },
      • "payment_method": {
        • "method": "credit_or_debit_card"
        }
      }
    },
  • "processing_instructions": {
    • "auto_capture": true
    }
}
Response samples
  • 200
  • 400
application/json
{
  • "charge": {
    • "amount_details": {
      • "amount": 5000,
      • "currency_code": "MXN"
      },
    • "consumer_details": {
      • "contact": {
        • "email": "test_user@example.com"
        },
      • "external_consumer_id": "abcd",
      • "name": {
        • "first_last_name": "Cash",
        • "first_name": "Test",
        • "second_first_name": "Hola",
        • "second_last_name": "User"
        }
      },
    • "description": "This is a test description",
    • "payment_detail": {
      • "credentials": {
        • "credit_or_debit_card": {
          • "card_number": "XXXXXXXXXXXXXXXX",
          • "card_validation_code": "XXX",
          • "expiration_month": "12",
          • "expiration_year": "2024"
          },
        • "payment_method": {
          • "method": "credit_or_debit_card"
          }
        }
      },
    • "processing_instructions": {
      • "auto_capture": true
      }
    },
  • "id": "8fa9a35e-3ece-4085-860c-4deb4c9e28ed",
  • "status_details": {
    • "date_created": 1643132896227,
    • "detail": {
      • "additional_details": [
        • {
          • "data": "visa",
          • "name": "card_brand"
          },
        • {
          • "data": "credit",
          • "name": "card_type"
          },
        • {
          • "data": "424242",
          • "name": "card_bin"
          },
        • {
          • "data": "4242",
          • "name": "card_last_four_digits"
          },
        • {
          • "data": "MXN",
          • "name": "currency_code"
          },
        • {
          • "data": "24",
          • "name": "expiration_year"
          },
        • {
          • "data": "12",
          • "name": "expiration_month"
          },
        • {
          • "data": "captured",
          • "name": "charge_status"
          }
        ]
      },
    • "message": "charge created",
    • "status": "success"
    }
}
Callback payload samples
application/json
{
  • "event_type": "charge.cancelled",
  • "payload": {
    • "cancellation_reason": "None",
    • "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": 1643157023494,
      • "detail": {
        • "additional_details": [ ],
        • "code": "expired",
        • "message": "charge expired"
        },
      • "message": "Could not create charge",
      • "status": "cancelled"
      }
    }
}

Gets the details of an 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.

SecurityclientKey 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
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
  • 200
application/json
{
  • "charge": {
    • "amount_details": {
      • "amount": 5000,
      • "currency_code": "MXN"
      },
    • "consumer_details": {
      • "contact": {
        • "email": "test_user@example.com"
        },
      • "external_consumer_id": "abcd",
      • "name": {
        • "first_last_name": "Cash",
        • "first_name": "Test",
        • "second_first_name": "Hola",
        • "second_last_name": "User"
        }
      },
    • "description": "This is a test description",
    • "payment_detail": {
      • "credentials": {
        • "credit_or_debit_card": {
          • "card_number": "XXXXXXXXXXXXXXXX",
          • "card_validation_code": "XXX",
          • "expiration_month": "12",
          • "expiration_year": "2024"
          },
        • "payment_method": {
          • "method": "credit_or_debit_card"
          }
        }
      },
    • "processing_instructions": {
      • "auto_capture": true
      }
    },
  • "id": "8fa9a35e-3ece-4085-860c-4deb4c9e28ed",
  • "status_details": {
    • "date_created": 1643132896227,
    • "detail": {
      • "additional_details": [
        • {
          • "data": "visa",
          • "name": "card_brand"
          },
        • {
          • "data": "credit",
          • "name": "card_type"
          },
        • {
          • "data": "424242",
          • "name": "card_bin"
          },
        • {
          • "data": "4242",
          • "name": "card_last_four_digits"
          },
        • {
          • "data": "MXN",
          • "name": "currency_code"
          },
        • {
          • "data": "24",
          • "name": "expiration_year"
          },
        • {
          • "data": "12",
          • "name": "expiration_month"
          },
        • {
          • "data": "captured",
          • "name": "charge_status"
          }
        ]
      },
    • "message": "charge created",
    • "status": "success"
    }
}

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

SecurityclientKey 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

object (AdditionalDetails)

Additional address information that does not fit into a structured address

required
object (Amount)

Amount details

object (ConsumerDetail)

Details about the consumer

description
required
string
object (PaymentDetail)

Details of the payment

object (ProcessingInstruction)

Hints on how you want the transaction to be processed.

object

Details of the purchase

object (ShippingDetails)

Details on where the purchase needs to be shipped.

Responses
200

Successful operation.

400

Invalid request, see the response for detail.

401

The security credentials are not valid

post/transaction/lookup
Request samples
  • Payload
  • cURL
application/json
{
  • "amount_details": {
    • "amount": 5070,
    • "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": "4242424242424242",
        • "card_validation_code": "324",
        • "expiration_month": "12",
        • "expiration_year": "2024"
        },
      • "payment_method": {
        • "method": "credit_or_debit_card"
        }
      }
    },
  • "processing_instructions": {
    • "auto_capture": true
    }
}
Response samples
  • 200
  • 400
application/json
{
  • "options": [
    • {
      • "id": 1,
      • "unit": "months",
      • "value": 3
      },
    • {
      • "id": 2,
      • "unit": "months",
      • "value": 6
      }
    ],
  • "options_list_id": "0a3f8ea5-78c4-4680-8952-3c7bee7f022a"
}

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.

SecurityclientKey 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). The smallest value allowed is 1 MXN represented as 100.

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 failed event.
postRefund succeeded.
post/transaction/refund/{id}
Request samples
  • Payload
  • cURL
application/json
{
  • "amount": 5000,
  • "currency_code": "MXN"
}
Response samples
  • 200
  • 400
application/json
{
  • "refund_transaction_id": "db068fc2-f07d-4a5d-bd23-59aa5595d7f4",
  • "status_details": {
    • "message": "refunded",
    • "status": "success"
    }
}
Callback payload samples
application/json
{
  • "event_type": "refund.failed",
  • "payload": {
    • "charge_detail": {
      • "charge": {
        • "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"
            }
          },
        • "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"
              }
            }
          }
        },
      • "id": "8fa9a35e-3ece-4085-860c-4deb4c9e28ed",
      • "status_details": {
        • "date_created": 1643145296384,
        • "detail": {
          • "additional_details": [ ],
          • "code": "transaction_not_valid_refund_target_no_funds_to_refund",
          • "message": "Cannot refund more than original amount"
          },
        • "message": "Could not refund charge",
        • "status": "failure"
        }
      },
    • "refund_detail": {
      • "refund_transaction_id": "db068fc2-f07d-4a5d-bd23-59aa5595d7f4",
      • "refunded_amount": {
        • "amount": 5000,
        • "currency_code": "MXN"
        }
      }
    }
}

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

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

object (ConsumerDetail)

Details about the consumer

description
string
Array of objects (Note)

Represents a list of notes you may want to add to an order.

required
object (Amount)

Amount details

object (PaymentDetail)

Details of the payment

Array of objects (OrderItem) non-empty

Details on items that were purchased.

object (ShippingDetails)

Details on where the purchase needs to be shipped.

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.

post/order
Request samples
  • Payload
  • cURL
application/json
{
  • "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"
        }
      }
    ]
}
Response samples
  • 200
  • 400
application/json
{
  • "order": {
    • "description": "This is a test order",
    • "order_total_amount": {
      • "amount": 5000,
      • "currency_code": "MXN"
      },
    • "purchases": [
      • {
        • "description": "This is an item in the order",
        • "id": "1234",
        • "item_total_amount": {
          • "amount": 5000,
          • "currency_code": "MXN"
          },
        • "quantity": 1,
        • "unit_amount": {
          • "amount": 5000,
          • "currency_code": "MXN"
          }
        }
      ]
    }
}

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.

SecurityclientKey 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
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
  • 200
  • 400
application/json
{
  • "order": {
    • "description": "This is a test order",
    • "order_total_amount": {
      • "amount": 5000,
      • "currency_code": "MXN"
      },
    • "purchases": [
      • {
        • "description": "This is an item in the order",
        • "id": "1234",
        • "item_total_amount": {
          • "amount": 5000,
          • "currency_code": "MXN"
          },
        • "quantity": 1,
        • "unit_amount": {
          • "amount": 5000,
          • "currency_code": "MXN"
          }
        }
      ]
    },
  • "order_information": {
    • "order_id": "f435579e-37c6-49b2-98c5-a22a49a433e9"
    }
}

Updates the order with a specific ID.

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

SecurityclientKey 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 (ConsumerDetail)

Details about the consumer

description
string
Array of objects (Note)

Represents a list of notes you may want to add to an order.

object (Amount)

Amount details

object (PaymentDetail)

Details of the payment

Array of objects (OrderItem) non-empty

Details on items that were purchased.

object (ShippingDetails)

Details on where the purchase needs to be shipped.

Responses
200

Successful updated the oder

400

Invalid request, see the response for detail.

401

The security credentials are not valid

patch/order/{id}
Request samples
  • Payload
  • cURL
application/json
{
  • "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"
        }
      }
    ]
}
Response samples
  • 200
  • 400
application/json
{
  • "order": {
    • "description": "This is the test order updated",
    • "order_total_amount": {
      • "amount": 5000,
      • "currency_code": "MXN"
      },
    • "purchases": [
      • {
        • "description": "This is an item in the updated order",
        • "id": "1234",
        • "item_total_amount": {
          • "amount": 5000,
          • "currency_code": "MXN"
          },
        • "quantity": 2,
        • "unit_amount": {
          • "amount": 5000,
          • "currency_code": "MXN"
          }
        }
      ]
    },
  • "order_information": {
    • "order_id": "f435579e-37c6-49b2-98c5-a22a49a433e9"
    }
}

checkout

Access checkout related configuration

Gets the checkout button.

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

SecurityclientPublicKeyInQueryString
Responses
200

The checkout button image.

400

Invalid request. See the response for detail

401

The security credentials are not valid

get/checkout/button
Request samples
  • cURL
curl --location --request GET 'https://sandbox.api.holacash.mx/v2/checkout/button?public_key=<USE PUBLIC KEY>'
Response samples
  • 400
application/json
{
  • "date_created": 1643093191130,
  • "detail": {
    • "additional_details": [ ],
    • "code": "invalid_security_credentials",
    • "message": "The security credentials are not valid"
    },
  • "message": "Could not authenticate",
  • "status": "failure"
}

subscription

Create and manage subscriptions and plans

Get all plans beta

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

SecurityclientKey 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
  • 200
  • 400
application/json
{
  • "item_count": 0,
  • "next": "string",
  • "page_count": 0,
  • "plan_list": [
    • {
      • "additional_details": {
        • "widget_configuration": { }
        },
      • "billing_frequency": "daily",
      • "date_created": 0,
      • "description": "string",
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "name": "string",
      • "payment_link": {
        • "id": "string",
        • "url": "http://example.com"
        },
      • "price": {
        • "amount": 5000,
        • "currency_code": "MXN"
        },
      • "product_id": "string",
      • "status": "active"
      }
    ],
  • "previous": "string"
}

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.

SecurityclientKey or sessionToken
Request
Request Body schema: application/json

Information about the plan you want to create

object

This property can contain information about how the plan will be displayed and Payment widget configuration settings.

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

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 creation failed.
postPlan created successfully.
post/plan
Request samples
  • Payload
application/json
{
  • "additional_details": { },
  • "description": "My plan description",
  • "name": "My plan",
  • "price": {
    • "amount": 1000,
    • "currency_code": "MXN"
    },
  • "product_id": "09f53b82-295a-452b-b7e5-09a1b0e5b834"
}
Response samples
  • 200
  • 400
application/json
{
  • "additional_details": { },
  • "billing_frequency": "monthly",
  • "date_created": 1658956845,
  • "description": "My description",
  • "id": "02e036d8-f71c-47b4-8f22-3510bffc4e25",
  • "name": "hello new product",
  • "payment_link": {
    • "id": "IKi39Pe1OhQTwKhWng",
    • "url": "http://URI/IKi39Pe1OhQTwKhWng"
    },
  • "price": {
    • "amount": 50121,
    • "currency_code": "MXN"
    },
  • "product_id": "aa87e96e-62b2-493a-bcd3-8536f7c71a02",
  • "status": "active"
}
Callback payload samples
application/json
{
  • "event_type": "plan_creation.failed",
  • "payload": {
    • "date_created": 1658957145625,
    • "detail": {
      • "additional_details": [ ],
      • "code": "plan_payment_link_creation_failed",
      • "message": "Payment link creation failed during plan creation"
      },
    • "message": "The payment link associated to the plan 5c305c3e-5004-4a16-a930-3fa427c6e12f could not be created",
    • "status": "failure"
    }
}

Get details of a given plan beta

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

SecurityclientKey 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
  • 200
  • 400
application/json
{
  • "additional_details": {
    • "widget_configuration": { }
    },
  • "billing_frequency": "daily",
  • "date_created": 0,
  • "description": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "payment_link": {
    • "id": "string",
    • "url": "http://example.com"
    },
  • "price": {
    • "amount": 5000,
    • "currency_code": "MXN"
    },
  • "product": {
    • "additional_details": {
      • "widget_configuration": { }
      },
    • "date_created": 0,
    • "description": "string",
    • "external_product_id": "string",
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "string",
    • "status": "enabled",
    • "subaccount_id": "string"
    },
  • "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.

SecurityclientKey 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
  • 200
  • 400
application/json
{
  • "item_count": 0,
  • "next": "string",
  • "page_count": 0,
  • "previous": "string",
  • "subscription_list": [
    • {
      • "auto_billing": true,
      • "billing_day": 0,
      • "billing_frequency": "daily",
      • "billing_method": "string",
      • "customer": {
        • "date_created": 0,
        • "full_name": "string",
        • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        • "primary_email": "user@example.com",
        • "primary_phone_number": "string"
        },
      • "date_created": 0,
      • "end_date": 0,
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "payment_token_id": "80bcd4f6-0f4b-4ffe-94da-19dee5dcfe20",
      • "plan": {
        • "additional_details": {
          • "widget_configuration": { }
          },
        • "billing_frequency": "daily",
        • "date_created": 0,
        • "description": "string",
        • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        • "name": "string",
        • "payment_link": {
          • "id": "string",
          • "url": "http://example.com"
          },
        • "price": {
          • "amount": 5000,
          • "currency_code": "MXN"
          },
        • "product": {
          • "additional_details": {
            • "widget_configuration": { }
            },
          • "date_created": 0,
          • "description": "string",
          • "external_product_id": "string",
          • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          • "name": "string",
          • "status": "enabled",
          • "subaccount_id": "string"
          },
        • "status": "active"
        },
      • "start_date": 0,
      • "status": "active"
      }
    ]
}

Creates a subscription beta

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

SecurityclientKey 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_day
required
integer

Day in which the customer will be billed

billing_frequency
string
Default: "monthly"

The period of time or frequency when the customer subscribed to this plan 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
required
string <uuid>

ID of the payment token on the hola.cash system that is going to be used to pay this subscription

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 creation failed.
postSubscription created successfully.
post/subscription
Request samples
  • Payload
application/json
{
  • "auto_billing": true,
  • "billing_day": 0,
  • "billing_frequency": "monthly",
  • "billing_method": "card",
  • "customer_email": "user@example.com",
  • "payment_token_id": "80bcd4f6-0f4b-4ffe-94da-19dee5dcfe20",
  • "plan_id": "00713021-9aea-41da-9a88-87760c08fa72",
  • "start_date": 0
}
Response samples
  • 200
  • 400
application/json
{
  • "auto_billing": true,
  • "billing_date": 0,
  • "billing_frequency": "daily",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "date_created": 0,
  • "end_date": 0,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "payment_token_id": "80bcd4f6-0f4b-4ffe-94da-19dee5dcfe20",
  • "plan_id": "00713021-9aea-41da-9a88-87760c08fa72",
  • "start_date": 0,
  • "status": "active"
}
Callback payload samples
application/json
{
  • "event_type": "subscription_creation.failed",
  • "payload": {
    • "date_created": 1658958235375,
    • "detail": {
      • "additional_details": [ ],
      • "code": "subscription_could_not_be_created",
      • "message": "The subscription could not be created in the system"
      },
    • "message": "The subscription 3fb978f4-0eba-411a-8e83-8750fe088918 could not be created",
    • "status": "failed"
    }
}

Get details of a subscription beta

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

SecurityclientKey or sessionToken
Request
path Parameters
id
required
string <uuid>

The id of the subscription to be 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
  • 200
  • 400
application/json
{
  • "auto_billing": true,
  • "billing_day": 0,
  • "billing_frequency": "daily",
  • "billing_method": "string",
  • "customer": {
    • "date_created": 0,
    • "full_name": "string",
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "primary_email": "user@example.com",
    • "primary_phone_number": "string"
    },
  • "date_created": 0,
  • "end_date": 0,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "payment_token_id": "80bcd4f6-0f4b-4ffe-94da-19dee5dcfe20",
  • "plan": {
    • "additional_details": {
      • "widget_configuration": { }
      },
    • "billing_frequency": "daily",
    • "date_created": 0,
    • "description": "string",
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "string",
    • "payment_link": {
      • "id": "string",
      • "url": "http://example.com"
      },
    • "price": {
      • "amount": 5000,
      • "currency_code": "MXN"
      },
    • "product": {
      • "additional_details": {
        • "widget_configuration": { }
        },
      • "date_created": 0,
      • "description": "string",
      • "external_product_id": "string",
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "name": "string",
      • "status": "enabled",
      • "subaccount_id": "string"
      },
    • "status": "active"
    },
  • "start_date": 0,
  • "status": "active"
}

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.

SecurityclientKey or sessionToken
Request
Request Body schema: application/json

Information about the product you want to create

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

description
required
string

A helpful description to help the customer understand the product

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

status
string
Default: "enabled"

Status of the current product. If enabled the product can be used to create a plan.

Enum: "enabled" "disabled"
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 creation failed.
postProduct created successfully.
post/product
Request samples
  • Payload
application/json
{
  • "additional_details": { },
  • "description": "My description",
  • "external_product_id": "My_external_order_id",
  • "name": "My new product"
}
Response samples
  • 200
  • 400
application/json
{
  • "additional_details": { },
  • "date_created": 1655485973,
  • "description": "My description",
  • "external_product_id": "My_external_order_id",
  • "id": "6a9f1b7a-9b8b-4f7c-8e6e-5739a9f9751d",
  • "name": "My new product",
  • "status": "enabled",
  • "subaccount_id": "6a9f1b7a-9b8b-4f7c-8e6e-5739a9f9751d"
}
Callback payload samples
application/json
{
  • "event_type": "product_creation.failed",
  • "payload": {
    • "date_created": 1658957921886,
    • "detail": {
      • "additional_details": [ ],
      • "code": "validation_error",
      • "message": "The request contains validation errors"
      },
    • "message": "Invalid additional details",
    • "status": "failure"
    }
}

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.

SecurityclientKey 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
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
  • 200
  • 400
application/json
{
  • "action": "3ds_authenticate",
  • "charge_id": "f435579e-37c6-49b2-98c5-a22a49a433e9",
  • "created_on": 1643144893400
}

payment_link

Gets a list of payment links

Returns a list of payment links

SecuritysessionToken or clientKey
Request
query Parameters
limit
integer

The number of transactions in a set. The minimun value is 1 (inclusive) and the maximum value is 100 (inclusive). If this query param is not present in the API call the default value will be 10.

after_id
string

ID in the system as the starting point to get transaction after.

Responses
200

List of payment links details

400

Invalid request. See the response for detail

401

The security credentials are not valid

get/payment_link
Response samples
  • 200
  • 400
application/json
{
  • "first_cursor": null,
  • "has_next": true,
  • "has_previous": false,
  • "last_cursor": "MjAyMi0wNS0xNyAyMDozNDozNC41MjIpMjIrMDA6MDA=",
  • "payment_links": [
    • {
      • "date_created": 1656136054,
      • "id": "ZrBX9nMbSl9Kis69L8",
      • "num_of_completed_transactions": 0,
      • "payment_link": {
        • "amount": null,
        • "amount_constraints": {
          • "conformance": "variable",
          • "maximum_amount": {
            • "amount": 20000,
            • "currency_code": "MXN"
            },
          • "minimum_amount": {
            • "amount": 10000,
            • "currency_code": "MXN"
            }
          },
        • "collect_customer_notes": false,
        • "description": "Unefon",
        • "expiration_date": 1755921639,
        • "max_num_times_can_be_paid": 1
        },
      • "status": "active",
      • "status_details": {
        • "date_created": 1644525047789,
        • "detail": null,
        • "message": null,
        • "status": "success"
        },
      • "url": "http://127.0.0.1:8000/ZrBX9nMbSl9Kis69L8"
      }
    ]
}

Creates a payment link

Creates a payment link

SecurityclientKey or sessionToken
Request
Request Body schema: application/json

Information about this payment link

object (Amount)

Amount details

required
object (AmountConstraints)

The constraints that apply to an amount

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. When not specified, this defaults to false

description
required
string

Short description of the payment link

expiration_date
required
integer <int64> (Timestamp)

Date in UTC expressed here in Unix EpochTime. You can check this site to convert dates online.

max_num_times_can_be_paid
required
integer >= 1

The maximum number of times a payment can be made using this payment link. Set it to 1 if you want a one-time use payment link.

Responses
200

Information about the created payment link

400

Invalid request. See the response for detail

401

The security credentials are not valid

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

Get a payment link

Get the details of a payment link by payment_link_id

SecuritysessionToken or clientKey
Request
path Parameters
payment_link_id
required
string

The ID of the payment link

Responses
200

Details of the payment link

400

Invalid request. See the response for detail

401

The security credentials are not valid

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

Updates a payment link

Updates the payment link given the payment_link_id

SecurityclientKey or sessionToken
Request
path Parameters
payment_link_id
required
string

The ID of the payment link

Request Body schema: application/json

Updates to the payment link

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.

status
string (PaymentLinkStatus)

Payment link status (i.e. Expired, Active, etc.). active when we create a payment link it will be active by default. expired when a payment link passes expiration_date then its status would be expired. completed when we have made the maximum number of payments allowed for a payment link it will be completed. disabled when we mark a payment link as cancelled so that it can not receive payments anymore then it will be shown disbaled.

Enum: "expired" "active" "completed" "disabled"
Responses
200

Updated payment link

400

Invalid request. See the response for detail

401

The security credentials are not valid

patch/payment_link/{payment_link_id}
Request samples
  • Payload
application/json
{
  • "status": "active"
}
Response samples
  • 200
  • 400
application/json
{
  • "date_created": 1656136054,
  • "id": "ZrBX9nMbSl9Kis69L8",
  • "num_of_completed_transactions": 0,
  • "payment_link": {
    • "amount": {
      • "amount": 20000,
      • "currency_code": "MXN"
      },
    • "amount_constraints": {
      • "conformance": "fixed",
      • "maximum_amount": {
        • "amount": 20000,
        • "currency_code": "MXN"
        },
      • "minimum_amount": {
        • "amount": 20000,
        • "currency_code": "MXN"
        }
      },
    • "collect_customer_notes": false,
    • "description": "Unefon",
    • "expiration_date": 1755921639,
    • "max_num_times_can_be_paid": 1
    },
  • "status": "active",
  • "status_details": {
    • "date_created": 1644525047789,
    • "detail": null,
    • "message": null,
    • "status": "success"
    },
  • "url": "http://127.0.0.1:8000/ZrBX9nMbSl9Kis69L8"
}

testing

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.

SecurityclientKey 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
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
  • 200
application/json
{
  • "success_message": "string"
}

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.

SecurityclientKey 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
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
  • 200
application/json
{
  • "success_message": "string"
}