Payin HPP

Credit cards are the most popular payment method in Mexico, used by 40% of customers. Our solution allows you to accept both credit and debit card transactions while achieving high approval rates. We support major credit cards like Visa, Mastercard, American Express, and Carnet, as well as debit cards from BBVA Bancomer, Banamex, Santander, and Banorte.

Payment flow:

1. The client on the merchant's website selects this payment method and specifies the payment amount
2. The merchant creates a transaction by calling the method /transaction/create. In response to the request, the merchant will receive a pay_url to the payment page, to which it redirects the client
   attention

   The fields request parameters are optional for creating a transaction and are used for pre-filling on the payment page. If there are no fields parameters in the request, the client needs to specify details on the payment page himself

3. The client specifies bank card details and checks/fills in personal data (phone number and email address) on the payment page
   • The client will see his personal data on the page with the possibility to edit it, on condition that it is provided by the merchant in the request
   • If these data are not provided in the request, the client needs to specify them on the payment page himself
4. The client confirms the payment
5. The maximum lifetime of a transaction is up to 90 minutes. The merchant expects to receive a callback, and may also use the /transaction/find method to get the payment status
6. After receiving the final status of the payment, the client is redirected to the page of successful/unsuccessful payment

Create a transaction

To create a transaction, use the /transaction/create API method.

All requests to the payment gateway API are sent in JSON format using the POST method.
Requests must contain header Content-Type: application/json, otherwise, the request will be considered invalid even if it has valid JSON.

Request parameters

Authorization parameters

Name	Type	Mandatory	Description
auth	object	Yes	Authorization data
auth.point	integer	Yes	This is your point_id from the credentials you received earlier
auth.key	integer	Yes	Session key generated on the merchant's side. You can use unixtime as a key value
auth.hash	string	Yes	md5 hash of a string obtained by concatenating point_id, api_token and key: md5(point + api_token + key) An example of a correctly calculated hash (the data in the example is random): point_id = 111 key = 1234 api_token = aiGha$et0ainah4%*eu9Vish8oo Correct hash: fda3ff2903690ed6795ea997a8cc1773

General request parameters

Name	Type	Mandatory	Max. length	Description
locale	string	Yes	2	Language of the payment page Format: language code in the ISO 639-1 standard Example: es – Spanish, en – English
external_customer_id	string	Yes	45	Client ID in the merchant's system. Used for improvement of the transaction's search during incidents analysis, as well as for the operation of the anti-fraud system. If such parameter is absent in the system, it is necessary to send an alternative value for payer's identification, for example: mobile phone number or email
customer_ip_address	string	Yes	39	Client's IP address. Both IPv4 and IPv6 addresses are allowed. It is important to send the client's real IP to avoid false positives in the anti-fraud system ⚠️ If the client's IP address belongs to one of the prohibited countries, the payment creation will be rejected with an error 243
external_transaction_id	string	No	128	Transaction ID in the merchant system. Must be unique for each transaction. If a transaction already exists with the same point_id and external_transaction_id, payment creation will be rejected with an error 203
external_order_id	string	No	48	Order ID in the merchant system. It is allowed to create multiple transactions with the same external_order_id
account_id	integer	Yes	—	Merchant account ID in the payment gateway. Provided by the Payonhost manager
wallet_id	integer	Yes	—	Merchant wallet ID in the payment gateway. Provided by the Payonhost manager
service_id	integer	Yes	—	Payment gateway service ID. Provided by the Payonhost manager
description	string	No	100	Description of payment purpose
amount	integer	Yes	—	Payment amount multiplied by 100 Format: positive integer without decimals Examples: 5000.00 MXN is transmitted as 500000 (5000.00 x 100 = 500000) 1534.20 MXN is transmitted as 153420 (1534.20 x 100 = 153420)
amount_currency	string	Yes	3	Currency code Format: fiat currency code in ISO 4217 standard Example: MXN
point	object	No	—	A set of point parameters for payment creation. The parameters, that could possibly be passed inside of the point object are given below
point.callback_url	string	No	1000	URL for callback transmission to the merchant. See the Callbacks section for details. The parameter cannot be empty, must be valid and must not lead to an IP from the local network ⚠️ We recommend correctly configuring callback_url to provide real-time transaction status updates
point.return_url	string	No	1000	URL to redirect the client back to the merchant's site before the final transaction status is received

Request parameters – fields for creating a transaction

warning

The format and necessity of passing these parameters may vary. Please contact the manager for details on the use of these parameters

Name	Type	Mandatory	Max. length	Description
fields	object	No	—	Set of parameters for creating a transaction
fields.email	string	No	255	Client's email address Must contain the @ symbol and correct domain Allowed: Latin letters in lower case (a-z), numbers (0-9) and symbols (@ . _ % + -) Format: username@domain.extension Example: example@mail.com
fields.phone	string	No	14	Client's phone number in international format The number starts with +52 and consists of 14 characters Format: +52XXXXXXXXXXX Example: +5215512345678
fields.first_name	string	No	50	Client's first name At least one word with two or more letters Allowed: Latin letters (A-Z a-z) Not allowed: numbers and special characters (@ # % etc.)
fields.last_name	string	No	50	Client's last name At least one word with two or more letters Allowed: Latin letters (A-Z a-z) Not allowed: numbers and special characters (@ # % etc.)
fields.date_of_birth	string	No	10	Client's date of birth Allowed: numbers (0-9) and hyphens (-) Format: YYYY-MM-DD Example: 1992-03-19
fields.tax_id_type	string	No	3	Type of document: RFC – Federal taxpayer registry code CURP – Social security number
fields.tax_id	string	No	18	RFC transmitted in one of the formats: 12 symbols for companies Allowed: Latin letters (A-Z) and numbers (0-9) Format: XXXXXXXXXXXX Example: EXA920320JW4 13 symbols for individuals Allowed: Latin letters (A-Z) and numbers (0-9) Format: XXXXXXXXXXXXX Example: DOGJ9203192K6 CURP transmitted in the format: Allowed: Latin letters (A-Z) and numbers (0-9) 18 symbols Format: XXXXXXXXXXXXXXXXXX Example: DOGJ920319HGRXRH06
fields.address	string	No	255	Full address of the client 💡 If this parameter is not received from the merchant, we can compile it from the fields city, street, building_number and zip_code
fields.street	string	No	100	Client's street name
fields.building_number	string	No	10	Client's house number, related to the fields.street parameter
fields.district	string	No	50	District of the client
fields.city	string	No	50	City of the client
fields.state	string	No	50	State or province of the client
fields.country	string	No	50	Country of the client
fields.zip_code	string	No	5	Postal code of the client

Request example

Request: /transaction/create

{
   "auth": {
       "point": 111,
       "key": 1234,
       "hash": "fda3ff2903690ed6795ea997a8cc1773"
   },
   "locale": "es",
   "external_customer_id": "123",
   "customer_ip_address": "166.139.8.122",
   "external_order_id": "100",
   "account_id": 123,
   "wallet_id": 123,
   "service_id": 123,
   "amount": 500000,
   "amount_currency": "MXN",
   "description": "Test payment",
   "point": {
       "callback_url": "https://your.server.callback.url"
   },
   "fields": {
       "email": "example@mail.com",
       "phone": "+5215512345678",
       "first_name": "John",
       "last_name": "Doe",
       "date_of_birth": "1992-03-19",
       "tax_id_type": "RFC",
       "tax_id": "DOGJ9203192K6",
       "address": "Chilpancingo, Jose Lopez Portillo, 39074",
       "street": "Jose Lopez Portillo",
       "building_number": "",
       "district": "Sta. Cruz",
       "city": "Chilpancingo",
       "state": "Guerrero",
       "country": "Mexico",
       "zip_code": "39074"
   }
}

Response parameters

All API responses always contain an error object with error data, even if there is no error. If no error occurred during request processing (error.code = 0), the response will contain a response object with the parameters of the created transaction (for details, see Response structure).

Name	Type	Description
error	object	Error data
error.code	integer	Error code If no errors occurred during request processing, the code will be 0 (see API error messages)
error.title	string	Error description
error.message	string	Detailed error description
response	object	Parameters of the created transaction
response.account_id	integer	Merchant account ID in the payment gateway
response.amount	integer	Payment amount multiplied by 100 Format: positive integer without decimals Examples: 5000.00 MXN is transmitted as 500000 (5000.00 x 100 = 500000) 1534.20 MXN is transmitted as 153420 (1534.20 x 100 = 153420)
response.amount_currency	string	Currency code Format: fiat currency code in ISO 4217 standard Example: MXN
response.external_customer_id	string	Client ID in the merchant system
response.external_order_id	string	Order ID in the merchant system
response.external_transaction_id	string	Transaction ID in the merchant system
response.id	integer	Identifier of the created transaction in the payment gateway
response.is_test	boolean	Parameter indicating whether the transaction is a test one. Automatically affixed to all transactions created using a merchant's test account
response.point_id	integer	Payment acceptance point ID
response.result	object	The result of transaction creation. Contains the pay_url of the payment page
response.result.pay_url	string	Link to the payment page
response.service_id	integer	Payment gateway service ID
response.status	integer	Transaction status The created transaction, if there is no error, will have a non-final status of 0 (NEW) or 10 (PENDING) (see Status reference)
response.status_description	string	Description of the payment status (in case of unsuccessful status)
response.wallet_id	integer	Merchant wallet ID in the payment gateway

Response examples

Successful

Response: /transaction/create

{
    "error": {
        "code": 0,
        "title": "Success"
    },
    "response": {
        "account_id": 123,
        "amount": 500000,
        "amount_currency": "MXN",
        "external_customer_id": "123",
        "external_order_id": "100",
        "external_transaction_id": "1234567890",
        "id": 1234567890,
        "is_test": false,
        "point_id": 111,
        "result": {
            "pay_url": "https://payment.page.url"
        },
        "service_id": 123,
        "status": 10,
        "wallet_id": 123
    }
}

Unsuccessful

Response: /transaction/create

{
    "error": {
        "code": 203,
        "message": null,
        "title": "Transaction with such external id already exists"
    }
}

Displaying the payment page to the customer

The transaction can be considered successfully created after receiving the pay_url. The customer can then be redirected to the provided URL.

This can be done in one of the following ways:

• Use iframe to open the page on your site;
• Redirect the customer from your site to the received pay_url;
• Send the link to the customer using any method.

NOTE

To combat fraud, some merchants may have restrictions on the domains where payments are allowed. If this restriction is active, the Referer header, which contains the domain of the website initiating the transition, will be checked when the payment page is accessed.

In such cases, the payment page can only be displayed to the customer in one of the following ways:

• By using an iframe;
• By using JavaScript.

⚠️ When redirecting with HTTP status code 302, the Referer header is not sent

Waiting for payment to complete

After the customer navigates to the payment page, the merchant must wait for a callback from the Payonhost payment gateway, which will be sent as soon as the transaction reaches its final status. You can read more about callbacks in the Callbacks section.

It is important to note that the back-redirect of the customer to the merchant's page is not directly related to the callback being sent. It is possible that the redirect will occur first, and the callback will be delivered shortly afterward. This should be taken into account during integration.

Payment status request

The merchant can send the /transaction/find request to get the current status of the transaction. You can read more about the /transaction/find method on the method description page.

⚠️ After successful completion, the transaction will have a final status of 1 (SUCCESS) (see Status reference).

Request example

Request: /transaction/find

{
    "auth": {
        "point": 111,
        "key": 1234,
        "hash": "fda3ff2903690ed6795ea997a8cc1773"
    },
    "id": 1234567890
}

Response example

Response: /transaction/find

{
    "error": {
        "code": 0,
        "title": "Success"
    },
    "response": {
        "account_id": 123,
        "account_wallet_amount": 500000,
        "account_wallet_currency": "MXN",
        "amount": 500000,
        "amount_currency": "MXN",
        "created_at": "2025-01-21 10:14:44",
        "description": "Test payment",
        "external_customer_id": "123",
        "external_order_id": "100",
        "external_transaction_id": "1234567890",
        "extra": {},
        "failure_reason_code": null,
        "failure_reason_message": "",
        "id": 1234567890,
        "is_test": false,
        "point_id": 111,
        "service_id": 123,
        "status": 1,
        "status_description": "",
        "wallet_id": 123
    }
}