NAV
Example

General

Terms and Definitions

Transaction Types

The system involves two types of operations: payment and refund. In the first case, money is transferred from holder's account to the merchant, in the second - vice versa. A merchant performs a refund if a buyer wants to return goods, and it is always associated with a payment transaction, which amount returns to a holder. It is possible to refund a whole payment amount or it's part only. Money usually comes back to a holder’s card the same day, but sometimes (it depends on an issuer) it can take up to 3 days.

Payment Methods

A payment can be made using following methods:

3-D Secure

3-D Secure is a common name of Verified By Visa and MasterCard Secure Code programs from Visa and MasterCard's respectively. In general, such program shall authenticate a cardholder (that is to protect against an unauthorized card usage) by an issuer before a payment. Actually, it looks as follows: a cardholder specifies card data. Then the issuer’s web site opens, where a cardholder has to enter a password or a secret code (usually, the code is sent in a SMS message). If the code is correct, a payment will be successful. Otherwise, it will be rejected.

Plugins for CMS

WooCommerce

All versions are supported

The installation instructions can be found in the file.

PrestaShop

Currently supported versions – 1.7 or later

Please contact [email protected] for assistance with installing the plugin for this CMS.

Magento

Currently supported versions – 2.0 or later

Please contact [email protected] for assistance with installing the plugin for this CMS.

Ecwid / Lightspeed E-Series

Please contact [email protected] for assistance with installing the plugin for this CMS.

Payment Widget

Payment widget is a pop-up form to enter card data and payer’s email address. The widget automatically defines a payment system type: Visa, MasterCard, American Express, or Carnet, and an emitting bank of a card and corresponding logos. The form is optimized for use in any browsers and mobile devices. There is an iframe opens within a widget which guarantees a security of card data sending and does not require a certification for merchant's usage.

Widget Installation

To install a widget, you need to add a script on a web site to the head section:

<script src="https://widget.tiptoppay.mx/bundles/widget.js"></script>

Define a function for charge methods calling for payment form to display:


this.pay = function () {
    var widget = new tiptop.Widget();
    widget.pay('charge', 
        { //options
            publicId: 'test_api_00000000000000000000001',  //id of site (from control panel)
            description: 'Payment example (no real withdrawal)', // purpose/justification/description
            amount: 10,
            currency: 'MXN',
            accountId: '[email protected]', //customer's/user's/payer's ID (optional)
            invoiceId: '1234567', // order number  (optional)
            data: {
                myProp: 'myProp value' //arbitrary set of parameters
            }
        },
        {
            onSuccess: function (options) { // success
                //action upon successful payment
            },
            onFail: function (reason, options) { // fail
                //action upon unsuccessful payment
            },
            onComplete: function (paymentResult, options) { //It is called as soon as the widget receives a response from api.tiptoppay with the result of the transaction.
                //e.x. calling your Facebook Pixel analytics
            },
            onPendingPayment: function() { // The function is called when creating a cash payment transaction (displaying a barcode to the customer)
                // example...
}         
        }
    )
};

Call the function when some event is emitted, for example click on the «Pay» button:

$('#checkout').click(pay);

Parameters

A call of charge function defines a payment scheme:

Parameter Type Use Description
publicId String Required A web site identifier; located in Control panel
description String Required Description of a payment purpose in any format
amount Float Required Payment amount
currency String Required Currency: MXN (see the reference)
accountId String Required Payer's ID (endpoint customer)
invoiceId String Optional Order or Invoice number
email String Optional E-mail of that user
requireEmail bool Optional Require user's email address to be specified in the widget
retryPayment bool Optional Display the "Repeat payment" button if the payment is unsuccessful. (true is default)

You can define the form behaviour for successful or unsuccessful payment using the following parameters:

Parameter Type Use Description
onSuccess Function or String Optional Either a function or a web site's page is specified. If a function is specified, it will be called after successful payment completion. If a page is specified, a payer will be directed to a specified page
onFail Function or String Optional Either a function or a web site's page is specified. If a function is specified, it will be called after unsuccessful payment completion. If a page is specified , a payer will be directed to a specified page.
onComplete Function Optional A function is specified that will be called as soon as the widget receives a response with the result of the transaction. You cannot make redirects in this method.
onPendingPayment Function or String Optional Either a function or a web site's page is specified. If a function is specified, it is invoked when a cash payment transaction is created. If a page is specified, a payer will be directed to a specified page.

Widget Localization

The widget is in Spanish by default. You need to add the language parameter in the widget to localize it:

var widget = new tiptop.Widget({language: "es-ES"});

List of supported languages:

languages Timezone Value
Spanish UTC es-ES

Checkout

DEMO CHECKOUT

Both test and real card details can be used for testing. No funds will be debited.

REQUIREMENTS

FORM REQUIREMENTS:

CRYPTOGRAM REQUIREMENTS:

PCI DSS SECURITY REQUIREMENTS:

In PCI DSS terms, this type of connection is classified as "E-commerce merchants who outsource all payment processing to PCI DSS validated third parties, and who have a website(s) that does not directly receive cardholder data but that can impact the security of the payment transaction. No electronic storage, processing, or transmission of any cardholder data on the merchant's systems or premises." This means that although payment data is processed by a third party, the website is a factor in the security of card details.

You must complete the SAQ-EP self-assessment form and pass quarterly ASV testing to meet the standard requirements.

INSTALLATION

To create a cryptogram, add the checkout script to the page with the payment form:

<script src="https://checkout.tiptoppay.mx/checkout.js"></script>

Choose a card details passing method that suits you:

Next, send the card cryptogram you created to the server and invoke the payment method via API.

PASSING THE CARD DETAILS DIRECTLY TO THE SCRIPT

1) Initialize checkout script

const checkout = new tiptop.Checkout({
    publicId: 'test_api_000000000000000002',
});

2) Invoke the cryptogram generation method by passing the card details to it

const fieldValues = {
    cvv: '911',
    cardNumber: '4242 4242 4242 4242',
    expDateMonth: '12',
    expDateYear: '24',
}

checkout.createPaymentCryptogram(fieldValues)
    .then((cryptogram) => {
        console.log(cryptogram);
    }).catch((errors) => {
        console.log(errors)
    });

USING THE INPUT FORM:

1) Create a form for entering the card details: The card details input fields are to be marked with the following attributes:

<form id="paymentFormSample" autocomplete="off">
    <input type="text" data-ttp="cardNumber">
    <input type="text" data-ttp="expDateMonth">
    <input type="text" data-ttp="expDateYear">
    <input type="text" data-ttp="cvv">
    <input type="text" data-ttp="name">
    <button type="submit">Оплатить 100 р.</button>
</form>

2) Initialize checkout script

const checkout = new tiptop.Checkout({
    publicId: 'test_api_000000000000000002',
    container: document.getElementById("paymentFormSample")
});

3) Invoke the cryptogram generation method

checkout.createPaymentCryptogram()
    .then((cryptogram) => {
        console.log(cryptogram); // cryptogram
    }).catch((errors) => {
        console.log(errors)
    });

WHEN DESIGNING YOUR OWN FORM OR PASSING DATA TO A SCRIPT, MIND THE FOLLOWING POINTS:

METHODS

ASYNCHRONOUS CRYPTOGRAM GENERATION METHOD

With this method, when a card details validation error occurs, you get an error code (see example below) instead of a localized message.

async createPaymentCryptogram(fieldValues: CardData): Promise<string>

The method returns a Promise containing the cryptogram. If invalid data is passed, the Promise will be declined with an error containing an object with the error list.

const checkout = new tiptop.Checkout({
    publicId: 'test_api_000000000000000002'
});

const fieldValues = {
    cvv: '911',
    cardNumber: '4242 4242 4242 4242',
    expDateMonth: '12',
    expDateYear: '24',
}

checkout.createPaymentCryptogram(fieldValues)
    .then((cryptogram) => {
        console.log(cryptogram);
    });

CARDDATA OBJECT DESCRIPTION:

export interface CardData {
    cvv?:  string; // CVV/CVC code
    cardNumber?: string; // Card number, spaces are ignored
    expDateMonth?: string; // Card expiration date – month
    expDateYear?: string; // Card expiration date – year
    expDateMonthYear?: string; // Card expiration date, all characters except digits are ignored, 
    //If the string is 2, 3, or 5 characters long, the first digit is interpreted as the month and the rest, as the year. 
    //If the string is 4 or 6 characters long, the first two characters are interpreted as the month and the rest, as the year.
}
Parameter Description Type Mandatory *
cvv CVV/CVC string No *
cardNumber Card number, spaces are ignored string Optional if the field is linked on the form
expDateMonth Card expiration date – month string Optional if the field is linked on the form or the expDateMonthYear field has been passed
expDateYear Card expiration date – year string Optional if the field is linked on the form or the expDateMonth and expDateYear fields have been passed
expDateMonthYear Card expiration date, all characters except numbers are ignored. If the string is 2, 3, or 5 characters long, the first digit is interpreted as the month and the rest, as the year. If the string is 4 or 6 characters long, the first two characters are interpreted as the month and the rest, as the year. string Optional if the field is linked on the form or the expDateMonth and expDateYear fields have been passed
name Cardholder name string No

HANDLING CARD DETAILS VALIDATION ERRORS:

const fieldValues = {
    cvv: '91', // Invalid CVV
    cardNumber: '4242 4242 4242 424', // Invalid card number
    expDateMonth: '12',
    expDateYear: '24',
}

checkout.createPaymentCryptogram(fieldValues)
    .then((cryptogram) => {
        console.log(cryptogram);
    })
        .catch((errors) => {
                console.log(errors);
             /* Prints
                {
            cardNumber: "CardNumber_Invalid,"
            cvv: "Cvv_Invalid"
                }
                */
});
Error code Description
CardNumber_Empty Blank card number
CardNumber_Invalid Invalid card number
Cvv_Empty Blank CVV
Cvv_Invalid Invalid CVV
ExpDateMonthYear_Empty Blank year and month
ExpDateMonthYear_Invalid Invalid year and month
ExpDateMonth_Empty Blank month
ExpDateMonth_Invalid Invalid month
ExpDateYear_Empty Blank year
ExpDateYear_Invalid Invalid year
Name_Empty Blank name *
Name_Invalid Invalid name *
Name_TooLong Name too long *
Name_TooShort Name too short *

CRYPTOGRAM GENERATION METHOD

This method will return a cryptogram if generated successfully, or an error list object in the event of a card details error. Unlike the createPaymentCryptogram method, the error list object contains localized descriptions of errors, not error codes

This method accepts a card details object as input, or it can be used in the legacy scheme involving a linked HTML form. Where the linked form is used and the same parameter is also found in the CardData object, an error will be returned when the attempt is made to generate a cryptogram.

Script for creating a cryptogram:

this.createCryptogram = function () {
    var result = checkout.createCryptogramPacket();

    if (result.success) {
        // cryptogram generated
        alert(result.packet);
    }
    else {
        // data input errors found, `result.messages` object in the following format: 
        // { name: "Cardholder name has too many characters," cardNumber: "Invalid card number" }
        // where `name`, `cardNumber` correspond to the values of the `<input ... data-cp="cardNumber">` attributes

       for (var msgName in result.messages) {
           alert(result.messages[msgName]);
       }
    }
};

$(function () {
    /* Creating checkout */
    checkout = new tiptop.Checkout(
    // public id from Personal Account
    "test_api_00000000000000000000001",
    // tag containing card data fields
    document.getElementById("paymentFormSample"));
});

API

API refers to the system's application programming interface for interoperation with merchant systems.

The interface, which runs at api.tiptoppay.mx, supports making payments, canceling payments, making refunds, completing two-step payments, creating and canceling recurring subscription payments, and mailing invoices.

Principle of operation

The choice of parameter passing format is determined client-side and controlled via the Content-Type request header.

The system will respond in JSON format, including at least two parameters: Success and Message:

{ "Success": false, "Message": "Invalid Amount value" }

Request authentication

HTTP Basic Auth is used to authenticate the request by sending the login and password in the HTTP request header. Public ID is used as the login name; API Secret is used as the password. Both of these can be found in your Personal Account.

API idempotence

Idempotence is a property of the API whereby the interface will return a result on a repeat request identical to that of the initial request without re-processing. This means that you can send multiple requests with the same ID to the system, but only one request will be successfully processed and all responses will be identical. This is a safeguard against network errors that may cause the generation of duplicate records and actions.

To enable idempotence, the API request header must contain an X-Request-ID key with a unique ID. The request ID is supposed to be generated on your side: it can be a guid, a combination of order number, date and amount, or any other value you choose.

Each new request to be processed must include a new X-Request-ID value. The system will store the result for 1 hour.

Test method

Here is a method you can invoke to test interoperation with the API.

Method URL:
https://api.tiptoppay.mx/test

Request parameters:
none.

Response example:
in response, the method will return a request status.

{"Success":true,"Message":"bd6353c3-0ed6-4a65-946f-083664bf8dbd"}

Payments by cryptogram

A method for paying with a cryptogram of payment data that results from an encryption algorithm. To generate a cryptogram, use the Checkout.

Method URL::
https://api.tiptoppay.mx/payments/cards/charge

Request parameters:

PARAMETER FORMAT APPLICATION DESCRIPTION
AMOUNT NUMBER Mandatory AMOUNT IN TRANSACTION CURRENCY, SEPARATOR: DOT. NUMBER OF NON-ZERO CHARACTERS AFTER DOT: 2.
CURRENCY STRING Opcional CURRENCY: USD/EUR/MXN (REFER TO THE DIRECTORY). IF THE PARAMETER IS NOT PROVIDED, IT DEFAULTS TO MXN.
IPADDRESS STRING Mandatory PAYER'S IP
CARDCRYPTOGRAMPACKET STRING Mandatory PAYMENT DATA CRYPTOGRAM
NAME STRING Opcional CARDHOLDER'S NAME IN LATIN LETTERS
PAYMENTURL STRING Opcional ADDRESS OF THE WEBSITE FROM WHICH THE CHECKOUT SCRIPT IS INVOKED
INVOICEID STRING Opcional INVOICE OR ORDER NUMBER
DESCRIPTION STRING Opcional TRANSACTION DESCRIPTION IN ARBITRARY FORM
CULTURENAME STRING Opcional NOTIFICATION LANGUAGE
ACCOUNTID STRING Opcional MANDATORY USER ID TO CREATE A SUBSCRIPTION AND RECEIVE A TOKEN
EMAIL STRING Opcional PAYER'S EMAIL ADDRESS TO WHICH THE PAYMENT RECEIPT WILL BE SENT
PAYER OBJECT Opcional ADDITIONAL FIELD FOR PAYER INFORMATION. USE THE FOLLOWING PARAMETERS: FirstName, LastName, MiddleName, Birth, Street, Address, City, Country, Phone, Postcode
JSONDATA JSON Opcional ANY OTHER DATA TO BE ASSOCIATED WITH THE TRANSACTION

In response, the server will return a JSON of three components::

Possible response variants:

Example cryptogram payment request:

{
    "Amount":10,
    "Currency":"MXT",
    "InvoiceId":"1234567",
    "IpAddress": "123.123.123.123",
    "Description":"Test",
    "AccountId":"user_x",
    "Name":"CARDHOLDER NAME", 
    "CardCryptogramPacket":"01492500008719030128SMfLeYdKp5dSQVIiO5l6ZCJiPdel4uDjdFTTz1UnXY+3QaZcNOW8lmXg0H670MclS4lI+qLkujKF4pR5Ri+T/E04Ufq3t5ntMUVLuZ998DLm+OVHV7FxIGR7snckpg47A73v7/y88Q5dxxvVZtDVi0qCcJAiZrgKLyLCqypnMfhjsgCEPF6d4OMzkgNQiynZvKysI2q+xc9cL0+CMmQTUPytnxX52k9qLNZ55cnE8kuLvqSK+TOG7Fz03moGcVvbb9XTg1oTDL4pl9rgkG3XvvTJOwol3JDxL1i6x+VpaRxpLJg0Zd9/9xRJOBMGmwAxo8/xyvGuAj85sxLJL6fA=="
    "Payer":
      { 
        "FirstName":"Test",
        "LastName":"Test",
        "MiddleName":"Test",
        "Birth":"1955-02-24",
        "Address":"test address",
        "Street":"Street",
        "City":"City",
        "Country":"MX",
        "Phone":"123",
        "Postcode":"345"
    }
}

Response example: invalid request:

{"Success":false,"Message":"Amount is required"}

Response example: 3-D Secure authentication required:

{
    "Model": {
        "TransactionId": 891463508,
        "PaReq": "+/eyJNZXJjaGFudE5hbWUiOm51bGwsIkZpcnN0U2l4IjoiNDI0MjQyIiwiTGFzdEZvdXIiOiI0MjQyIiwiQW1vdW50IjoxMDAuMCwiQ3VycmVuY3lDb2RlIjoiUlVCIiwiRGF0ZSI6IjIwMjEtMTAtMjVUMDA6MDA6MDArMDM6MDAiLCJDdXN0b21lck5hbWUiOm51bGwsIkN1bHR1cmVOYW1lIjoicnUtUlUifQ==",
        "GoReq": null,
        "AcsUrl": "https://demo.tiptoppay.mx/acs",
        "ThreeDsSessionData": null,
        "IFrameIsAllowed": true,
        "FrameWidth": null,
        "FrameHeight": null,
        "ThreeDsCallbackId": "7be4d37f0a434c0a8a7fc0e328368d7d",
        "EscrowAccumulationId": null
    },
    "Success": false,
    "Message": null
}

Response example: transaction declined. ReasonCode field contains error code (refer to the directory):

{
    "Model": {
        "ReasonCode": 5051,
        "PublicId": "pk_**********************************",
        "TerminalUrl": "http://test.test",
        "TransactionId": 891583633,
        "Amount": 10,
        "Currency": "MXN",
        "CurrencyCode": 0,
        "PaymentAmount": 10,
        "PaymentCurrency": "MXN",
        "PaymentCurrencyCode": 0,
        "InvoiceId": "1234567",
        "AccountId": "user_x",
        "Email": null,
        "Description": "Test",
        "JsonData": null,
        "CreatedDate": "/Date(1635154784619)/",
        "PayoutDate": null,
        "PayoutDateIso": null,
        "PayoutAmount": null,
        "CreatedDateIso": "2021-10-25T09:39:44",
        "AuthDate": null,
        "AuthDateIso": null,
        "ConfirmDate": null,
        "ConfirmDateIso": null,
        "AuthCode": null,
        "TestMode": true,
        "Rrn": null,
        "OriginalTransactionId": null,
        "FallBackScenarioDeclinedTransactionId": null,
        "IpAddress": "123.123.123.123",
        "IpCountry": "CN",
        "IpCity": "Beijing",
        "IpRegion": "Beijing",
        "IpDistrict": "Beijing",
        "IpLatitude": 39.9289,
        "IpLongitude": 116.3883,
        "CardFirstSix": "400005",
        "CardLastFour": "5556",
        "CardExpDate": "12/25",
        "CardType": "Visa",
        "CardProduct": null,
        "CardCategory": null,
        "EscrowAccumulationId": null,
        "IssuerBankCountry": "US",
        "Issuer": "ITS Bank",
        "CardTypeCode": 0,
        "Status": "Declined",
        "StatusCode": 5,
        "CultureName": "kk",
        "Reason": "InsufficientFunds",
        "CardHolderMessage": "InsufficientFunds",
        "Type": 0,
        "Refunded": false,
        "Name": "CARDHOLDER NAME",
        "Token": "tk_255c42192323f2e09ea17635302c3",
        "SubscriptionId": null,
        "GatewayName": "Test",
        "ApplePay": false,
        "AndroidPay": false,
        "WalletType": "",
        "TotalFee": 0
    },
    "Success": false,
    "Message": null
}

Response example: transaction accepted:

{
    "Model": {
        "ReasonCode": 0,
        "PublicId": "pk_********************************",
        "TerminalUrl": "http://test.test",
        "TransactionId": 891510444,
        "Amount": 10,
        "Currency": "MXN",
        "CurrencyCode": 0,
        "PaymentAmount": 10,
        "PaymentCurrency": "MXN",
        "PaymentCurrencyCode": 0,
        "InvoiceId": "1234567",
        "AccountId": "user_x",
        "Email": null,
        "Description": "Test",
        "JsonData": null,
        "CreatedDate": "/Date(1635150224630)/",
        "PayoutDate": null,
        "PayoutDateIso": null,
        "PayoutAmount": null,
        "CreatedDateIso": "2021-10-25T08:23:44",
        "AuthDate": "/Date(1635150224739)/",
        "AuthDateIso": "2021-10-25T08:23:44",
        "ConfirmDate": null,
        "ConfirmDateIso": null,
        "AuthCode": "A1B2C3",
        "TestMode": true,
        "Rrn": null,
        "OriginalTransactionId": null,
        "FallBackScenarioDeclinedTransactionId": null,
        "IpAddress": "123.123.123.123",
        "IpCountry": "CN",
        "IpCity": "Beijing",
        "IpRegion": "Beijing",
        "IpDistrict": "Beijing",
        "IpLatitude": 39.9289,
        "IpLongitude": 116.3883,
        "CardFirstSix": "411111",
        "CardLastFour": "1111",
        "CardExpDate": "11/25",
        "CardType": "Visa",
        "CardProduct": "C",
        "CardCategory": "Visa Signature (Signature)",
        "EscrowAccumulationId": null,
        "IssuerBankCountry": "MX",
        "Issuer": "TipTop Pay",
        "CardTypeCode": 0,
        "Status": "Authorized",
        "StatusCode": 2,
        "CultureName": "kk",
        "Reason": "Approved",
        "CardHolderMessage": "Payment success",
        "Type": 0,
        "Refunded": false,
        "Name": "CARDHOLDER NAME",
        "Token": "0a0afb77-8f41-4de2-9524-1057f9695303",
        "SubscriptionId": null,
        "GatewayName": "Test",
        "ApplePay": false,
        "AndroidPay": false,
        "WalletType": "",
        "TotalFee": 0
    },
    "Success": true,
    "Message": null
}

3-D Secure processing

To perform 3-D Secure authentication, you must direct the payer to the address specified in the AcsUrl parameter of the server response passing the following parameters:

EXAMPLE FORM:

<form name="downloadForm" action="AcsUrl" method="POST">
    <input type="hidden" name="PaReq" value="eJxVUdtugkAQ/RXDe9mLgo0Z1nhpU9PQasWmPhLYAKksuEChfn13uVR9mGTO7MzZM2dg3qSn0Q+X\nRZIJxyAmNkZcBFmYiMgxDt7zw6MxZ+DFkvP1ngeV5AxcXhR+xEdJ6BhpEZnEYLBdfPAzg56JKSKT\nAhqgGpFB7IuSgR+cl5s3NqFTG2NAPYSUy82aETqeWPYUUAdB+ClnwSmrwtz/TbkoC0BtDYKsEqX8\nZfZkDGgAUMkTi8synyFU17V5N2nKCpBuAHRVs610VijCJgmZu17UXTxhFWP34l7evYPlegsHkO6A\n0C85o5hMsI3piNIZHc+IBaitg59qJYzgdrUOQK7/WNy+3FZAeSqV5cMqAwLe5JlQwpny8T8HdFW8\netFuBqUyahV+Hjf27vWCaSx22fe+KY6kXKZfJLK1x22TZkyUS8QiHaUGgDQN6s+H+tOq7O7kf8hd\nt30=">
    <input type="hidden" name="MD" value="504">
    <input type="hidden" name="TermUrl" value="https://example.com/post3ds?order=1234567">
</form>
<script>
    window.onload = submitForm;
    function submitForm() { downloadForm.submit(); }
</script>


Use the following Post3ds method to finalize the payment.

Method URL:
https://api.tiptoppay.mx/payments/cards/post3ds

Request parameters:

PARAMETER FORMAT APPLICATION DESCRIPTION
TransactionId Long Mandatory MD value
PaRes String Mandatory Eponymous parameter value

In response to a correctly formed request, the server will either return a successful transaction report or one on a transaction declined.

Payments by token (recurring)

This method is intended for payment using the token received when paying by cryptogram or obtained via Pay.

Method URL::
https://api.tiptoppay.mx/payments/tokens/charge

Request parameters:

PARAMETER FORMAT APPLICATION DESCRIPTION
Amount Number Mandatory Amount in transaction currency, separator: dot. Number of non-zero characters after dot: 2.
Currency String Opcional Currency: USD/EUR/MXN (refer to the directory)
AccountId String Mandatory User ID
TrInitiatorCode Int Opcional Debiting initiator flag. Possible values:
0: the transaction was initiated by the merchant based on previously saved credentials;
1: the transaction was initiated by the cardholder (client) based on previously saved credentials.
Token String Mandatory Token
InvoiceId String Opcional Invoice or order number
Description String Opcional Payment purpose in arbitrary form
IpAddress String Opcional Payer's IP
Email String Opcional Payer's email address to which the payment receipt will be sent
Payer Object Opcional Additional field for payer information. Use the following parameters: FirstName, LastName, MiddleName, Birth, Street, Address, City, Country, Phone, Postcode
JsonData Json Opcional Any other data to be associated with the transaction

In response, the server returns a JSON with three components success field – the request result, message field – the error description, model object – additional information.

POSSIBLE VARIANTS

Example token payment request::

{
    "Amount":59,
    "Currency":"MXN",
    "InvoiceId":"1234567",
    "Description":"Description example",
    "AccountId":"user_x",
    "Token":"success_1111a3e0-2428-48fb-a530-12815d90d0e8",
    "Payer":
      { 
        "FirstName":"Test",
        "LastName":"Test",
        "MiddleName":"Test",
        "Birth":"1955-02-24",
        "Address":"test address",
        "Street":"Street",
        "City":"City",
        "Country":"MX",
        "Phone":"123",
        "Postcode":"345"
    }
}

Response example: invalid request

{"Success":false,"Message":"Amount is required"}

Response example: transaction declined. ReasonCode field contains error code (refer to the directory)

{
    "Model": {
        "ReasonCode": 5051,
        "PublicId": "pk_**********************************",
        "TerminalUrl": "http://test.test",
        "TransactionId": 891583633,
        "Amount": 100,
        "Currency": "MXN",
        "CurrencyCode": 0,
        "PaymentAmount": 100,
        "PaymentCurrency": "MXN",
        "PaymentCurrencyCode": 0,
        "InvoiceId": "1234567",
        "AccountId": "user_x",
        "Email": null,
        "Description": "Decription test",
        "JsonData": null,
        "CreatedDate": "/Date(1635154784619)/",
        "PayoutDate": null,
        "PayoutDateIso": null,
        "PayoutAmount": null,
        "CreatedDateIso": "2021-10-25T09:39:44",
        "AuthDate": null,
        "AuthDateIso": null,
        "ConfirmDate": null,
        "ConfirmDateIso": null,
        "AuthCode": null,
        "TestMode": true,
        "Rrn": null,
        "OriginalTransactionId": null,
        "FallBackScenarioDeclinedTransactionId": null,
        "IpAddress": "123.123.123.123",
        "IpCountry": "CN",
        "IpCity": "Beijing",
        "IpRegion": "Beijing",
        "IpDistrict": "Beijing",
        "IpLatitude": 39.9289,
        "IpLongitude": 116.3883,
        "CardFirstSix": "400005",
        "CardLastFour": "5556",
        "CardExpDate": "12/25",
        "CardType": "Visa",
        "CardProduct": null,
        "CardCategory": null,
        "EscrowAccumulationId": null,
        "IssuerBankCountry": "US",
        "Issuer": "ITS Bank",
        "CardTypeCode": 0,
        "Status": "Declined",
        "StatusCode": 5,
        "CultureName": "mx",
        "Reason": "InsufficientFunds",
        "Type": 0,
        "Refunded": false,
        "Name": "CARDHOLDER NAME",
        "Token": "tk_255c42192323f2e09ea17635302c3",
        "SubscriptionId": null,
        "GatewayName": "Test",
        "ApplePay": false,
        "AndroidPay": false,
        "WalletType": "",
        "TotalFee": 0
    },
    "Success": false,
    "Message": null
}

Response example: transaction accepted

 {
    "Model": {
        "ReasonCode": 0,
        "PublicId": "pk_**************************",
        "TerminalUrl": "http://test.test",
        "TransactionId": 897728064,
        "Amount": 59,
        "Currency": "MXN",
        "CurrencyCode": 0,
        "PaymentAmount": 59,
        "PaymentCurrency": "MXN",
        "PaymentCurrencyCode": 0,
        "InvoiceId": 1234567,
        "AccountId": "user_x",
        "Email": null,
        "Description": "Decription test",
        "JsonData": null,
        "CreatedDate": "/Date(1635562705992)/",
        "PayoutDate": null,
        "PayoutDateIso": null,
        "PayoutAmount": null,
        "CreatedDateIso": "2021-10-30T02:58:25",
        "AuthDate": "/Date(1635562706070)/",
        "AuthDateIso": "2021-10-30T02:58:26",
        "ConfirmDate": "/Date(1635562706070)/",
        "ConfirmDateIso": "2021-10-30T02:58:26",
        "AuthCode": "A1B2C3",
        "TestMode": true,
        "Rrn": null,
        "OriginalTransactionId": null,
        "FallBackScenarioDeclinedTransactionId": null,
        "IpAddress": "87.251.91.164",
        "IpCountry": "MX",
        "IpCity": "City",
        "IpRegion": "Region",
        "IpDistrict": "District",
        "IpLatitude": 55.03923,
        "IpLongitude": 82.927818,
        "CardFirstSix": "424242",
        "CardLastFour": "4242",
        "CardExpDate": "12/25",
        "CardType": "Visa",
        "CardProduct": "I",
        "CardCategory": "Visa Infinite Infinite",
        "EscrowAccumulationId": null,
        "IssuerBankCountry": "MX",
        "Issuer": "TipTop Pay",
        "CardTypeCode": 0,
        "Status": "Completed",
        "StatusCode": 3,
        "CultureName": "mx",
        "Reason": "Approved",
        "CardHolderMessage": "Payment has been successfully completed",
        "Type": 0,
        "Refunded": false,
        "Name": "SER",
        "Token": "success_1111a3e0-2428-48fb-a530-12815d90d0e8",
        "SubscriptionId": null,
        "GatewayName": "Test",
        "ApplePay": false,
        "AndroidPay": false,
        "WalletType": "",
        "TotalFee": 0
    },
    "Success": true,
    "Message": null
}

Payment confirmation

Confirmation is required for two-step payments. Payments can be confirmed in your Personal Account or by invoking the API method.

Method URL:
https://api.tiptoppay.mx/payments/confirm

Request parameters:

PARAMETER FORMAT APPLICATION DESCRIPTION
TransactionId Long Mandatory Transaction number in the system
Amount Number Mandatory Confirmed amount in transaction currency, separator: dot. Number of non-zero characters after dot: 2.
JsonData Json Opcional Any other data to be associated with the transaction

Example request:

{"TransactionId":455,"Amount":65.98}

Response example:

{"Success":true,"Message":null}

Payment cancellation

Payments can be canceled in the Personal Account or by invoking the API method.

Method URL:
https://api.tiptoppay.mx/payments/void

Request parameters:

PARAMETER FORMAT APPLICATION DESCRIPTION
TransactionId Long Mandatory Transaction number in the system

Example request:

{"TransactionId":455}

Response example:

{"Success":true,"Message":null}

Refunds

Refunds can be effectuated in the Personal Account or by invoking the API method.

Method URL:
https://api.tiptoppay.mx/payments/refund

Request parameters:

PARAMETER FORMAT APPLICATION DESCRIPTION
TransactionId Long Mandatory Payment transaction number
Amount Number Mandatory Refund amount in transaction currency, separator: dot. Number of non-zero characters after dot: 2.
JsonData Json Opcional Any other data to be associated with the transaction

Example request:

{"TransactionId":455, "Amount": 100}

Response example:

{
    "Model": {
        "TransactionId": 568
    },
    "Success": true,
    "Message": null
}

Cash payments

Method URL:
https://api.tiptoppay.mx/payments/altpay/pay

Example request:

{
  "PublicId": "pk_**************************",
  "Amount": 100,
  "Currency": "MXN",
  "Description": "A basket of oranges",
  "CultureName": "en",
  "PaymentUrl": "https://www.google.com",
  "InvoiceId": "42",
  "AccountId": "[email protected]",
  "Scenario": 3,
  "AltPayType": "CashOxxo",
  "Scheme": 0,
  "ReturnRedirectUrl": "{redirectUrl}"
  "Email": "[email protected]",
  "Payer": {
    "FirstName": "Client",
    "Email": "[email protected]"
  }
}

Depending on the store selected in the POST: /payments/altpay/pay request, a specific AltPayType will be sent

SPEI payment

Method URL:
https://api.tiptoppay.mx/payments/altpay/pay

Example request:

{
  "PublicId": "pk_**************************",
  "AltPayType": 5,
  "Scenario": 3,
  "Amount": 111,
  "Currency": "MXN",
  "Description": "SPEI",
  "Email": "[email protected]",
  "InvoiceId": "20",
  "JsonData": null,
  "CultureName": "es-ES"
}

Response example:

{ 
  "Model": {
    "transactionId": 0,
    "providerTransactionId": "string",
    "status": "Unknown",
    "statusCode": 0,
    "extensionData": {
      "clabe": 0,
      "expiredDate": "2022-07-10T05:05:40.078Z",
      "link": "string",
      "gateway": "string"
    },
    "amount": 0,
  },
  "Success": true,
  "Message": "string"
}

Response example: Invalid request format

{
  "ErrorCode": "400",
}

Response example: CLABE account has already been generated for this TransactionID

{
  "ErrorCode": "401",
  "ErrorMessage": "CLABE account has already been generated for this TransactionID"
}

Response example: All unique values for the CLABE account are occupied

{
  "ErrorCode": "402",
  "ErrorMessage": "All unique values for the CLABE account are occupied"
}

Response example: Internal server error

{
  "ErrorCode": "500",
}

Creating a subscription with recurring payments

The method for creating a subscription with recurring payments.

Method URL:
https://api.tiptoppay.mx/subscriptions/create

Request parameters:

PARAMETER FORMAT APPLICATION DESCRIPTION
Token String Mandatory Card token issued by system after initial payment
AccountId String Mandatory User ID
Description String Mandatory Payment purpose in arbitrary form
Email String Opcional Payer's email
Amount Number Mandatory Amount in transaction currency, separator: dot. Number of non-zero characters after dot: 2.
Currency String Mandatory Currency: USD/EUR/MXN (refer to the directory)
RequireConfirmation Bool Mandatory If "true", the payments will be processed under the two-step scheme
StartDate DateTime Mandatory The date and time of the plan's first payment in the UTC timezone. The value has to be dated in the future
Interval String Mandatory Interval. Available values: Day, Week, Month
Period Int Mandatory Period. Combined with interval; 1 Month means once a month; 2 Weeks means every two weeks. Must be above 0
MaxPeriods Int Opcional Maximum number of payments per subscription. If specified, must be greater than 0

In response to a correctly generated request, the system will return a message reporting a completed transaction and a subscription ID.

Example request:

{  
   "token": "477BBA133C182267FE5F086924ABDC5DB71F77BFC27F01F2843F2CDC69D89F05",
   "accountId": "user_x",
   "description": "Subscription on example.com",
   "email": "[email protected]",
   "amount": 399,
   "Currency": "MXN",
   "requireConfirmation": false,
   "startDate": "2021-11-02T21:00:00",
   "interval": "Day",
   "period": 5
}

Response example:

 {
    "Model": {
        "Id": "sc_221da6421dc44dbd2cc3464f6f083",
        "AccountId": "user_x",
        "Description": "Subscription on example.com",
        "Email": "[email protected]",
        "Amount": 399,
        "CurrencyCode": 0,
        "Currency": "MXN",
        "RequireConfirmation": false,
        "StartDate": "/Date(1635886800000)/",
        "StartDateIso": "2021-11-02T21:00:00",
        "IntervalCode": 2,
        "Interval": "Day",
        "Period": 5,
        "MaxPeriods": null,
        "CultureName": "mx",
        "StatusCode": 0,
        "Status": "Active",
        "SuccessfulTransactionsNumber": 0,
        "FailedTransactionsNumber": 0,
        "LastTransactionDate": null,
        "LastTransactionDateIso": null,
        "NextTransactionDate": "/Date(1635886800000)/",
        "NextTransactionDateIso": "2021-11-02T21:00:00",
        "FailoverSchemeId": null
    },
    "Success": true,
    "Message": null
}

Requesting subscription details

The method for obtaining subscription status info.

Method URL:
https://api.tiptoppay.mx/subscriptions/get

Request parameters:

PARAMETER FORMAT APPLICATION DESCRIPTION
Id String Mandatory Subscription ID

Example request:

{"Id":"sc_8cf8a9338fb8ebf7202b08d09c938"}

Response example:

{
    "Model": {
        "Id": "sc_8cf8a9338fb8ebf7202b08d09c938",
        "AccountId": "user_x",
        "Description": null,
        "Email": "[email protected]",
        "Amount": 399,
        "CurrencyCode": 0,
        "Currency": "MXN",
        "RequireConfirmation": false,
        "StartDate": "/Date(1635886800000)/",
        "StartDateIso": "2021-11-02T21:00:00",
        "IntervalCode": 2,
        "Interval": "Day",
        "Period": 5,
        "MaxPeriods": null,
        "CultureName": "mx",
        "StatusCode": 3,
        "Status": "Cancelled",
        "SuccessfulTransactionsNumber": 0,
        "FailedTransactionsNumber": 0,
        "LastTransactionDate": null,
        "LastTransactionDateIso": null,
        "NextTransactionDate": null,
        "NextTransactionDateIso": null,
        "Receipt": null,
        "FailoverSchemeId": null
    },
    "Success": true,
    "Message": null
}

The method for obtaining a list of subscriptions for a specific account.

Method URL:
https://api.tiptoppay.mx/subscriptions/find

Request parameters:

PARAMETER FORMAT APPLICATION DESCRIPTION
accountId String Mandatory User ID

Example request:

{"accountId":"[email protected]"}

Response example:

{
    "Model": [
{
            "Id": "sc_221da6421dc44dbd2cc3464f6f083",
            "AccountId": "user_x",
            "Description": null,
            "Email": "[email protected]",
            "Amount": 399,
            "CurrencyCode": 0,
            "Currency": "MXN",
            "RequireConfirmation": false,
            "StartDate": "/Date(1635886800000)/",
            "StartDateIso": "2021-11-02T21:00:00",
            "IntervalCode": 2,
            "Interval": "Day",
            "Period": 5,
            "MaxPeriods": null,
            "CultureName": "mx",
            "StatusCode": 3,
            "Status": "Cancelled",
            "SuccessfulTransactionsNumber": 0,
            "FailedTransactionsNumber": 0,
            "LastTransactionDate": null,
            "LastTransactionDateIso": null,
            "NextTransactionDate": null,
            "NextTransactionDateIso": null,
            "FailoverSchemeId": null
        },
        {
            "Id": "sc_3ffc96c001e152b341817341b075a",
            "AccountId": "user_x",
            "Description": null,
            "Email": "[email protected]",
            "Amount": 999,
            "CurrencyCode": 0,
            "Currency": "MXN",
            "RequireConfirmation": false,
            "StartDate": "/Date(1635973200000)/",
            "StartDateIso": "2021-11-03T21:00:00",
            "IntervalCode": 2,
            "Interval": "Day",
            "Period": 5,
            "MaxPeriods": null,
            "CultureName": "mx",
            "StatusCode": 0,
            "Status": "Active",
            "SuccessfulTransactionsNumber": 0,
            "FailedTransactionsNumber": 0,
            "LastTransactionDate": null,
            "LastTransactionDateIso": null,
            "NextTransactionDate": "/Date(1635973200000)/",
            "NextTransactionDateIso": "2021-11-03T21:00:00",
            "FailoverSchemeId": null
        }
    ],
    "Success": true,
    "Message": null
}

Modifying a subscription with recurring payments

Method for modifying an existing subscription.

Method URL:
https://api.tiptoppay.mx/subscriptions/update

Request parameters:

PARAMETER FORMAT APPLICATION DESCRIPTION
Id String Mandatory Subscription ID
Description String Opcional To change the payment purpose
Amount Number Opcional To change the payment amount in the respective currency, separator: dot. Number of non-zero characters after dot: 2.
Currency String Opcional Currency: USD/EUR/MXN (refer to the directory)
RequireConfirmation Bool Opcional To change the payment scheme
StartDate DateTime Opcional To change the date and time of the first or subsequent payment in the UTC timezone
Interval String Opcional To change the interval. Available values: Day, Week, Month
Period Int Opcional To change the period. In combination with interval; 1 Month means once a month; 2 Week means every two weeks
MaxPeriods Int Opcional To change the maximum number of payments per subscription
CultureName String Opcional Notification language

In response to a correctly generated request, the system will return a message reporting a completed transaction and subscription parameters.

Example request:

{  
   "Id":"sc_3ffc96c001e152b341817341b075a",
   "description":"changing recurrence",
   "amount":499,
   "Currency":"MXN"
}

Response example:

{
    "Model": {
        "Id": "sc_3ffc96c001e152b341817341b075a",
        "AccountId": "user_x",
        "Description": "changing recurrence",
        "Email": "[email protected]",
        "Amount": 499,
        "CurrencyCode": 0,
        "Currency": "MXN",
        "RequireConfirmation": false,
        "StartDate": "/Date(1635973200000)/",
        "StartDateIso": "2021-11-03T21:00:00",
        "IntervalCode": 2,
        "Interval": "Day",
        "Period": 2,
        "MaxPeriods": null,
        "CultureName": "mx",
        "StatusCode": 0,
        "Status": "Active",
        "SuccessfulTransactionsNumber": 0,
        "FailedTransactionsNumber": 0,
        "LastTransactionDate": null,
        "LastTransactionDateIso": null,
        "NextTransactionDate": "/Date(1635973200000)/",
        "NextTransactionDateIso": "2021-11-03T21:00:00",
        "FailoverSchemeId": null
    },
    "Success": true,
    "Message": null
}

Cancelling a subscription with recurring payments

The method for canceling a subscription with recurring payments.

Method URL:

https://api.tiptoppay.mx/subscriptions/cancel
Request parameters:

PARAMETER FORMAT APPLICATION DESCRIPTION
Id String Mandatory Subscription ID

In response to a correctly generated request, the system will return a message reporting a completed transaction.

Example request:

{"Id":"sc_cc673fdc50b3577e60eee9081e440"}

Response example:

{"Success":true,"Message":null}

Request for terminal settings

Method to retrieve available payment methods by public ID of the terminal, passed in Query parameter.

Method URL:

https://api.tiptoppay.mx/merchant/configuration/?terminalPublicId=?&paymentUrl=?&language=?

Request parameters:

No. Name Type Data type Description
1 terminalPublicId query string public ID of the terminal
2 paymentUrl query string address of the website from which invocation is made
3 language query enum localization

Example request:

https://api.tiptoppay.mx/merchant/configuration/?terminalPublicId=pk_798df82a361070a52485c827dc6f4&paymentUrl=https%3A%2F%2Fdemo-pre-mx.tiptoppay.mx&language=es

Response example:

{
  "Model": {
    "LogoUrl": "https://static.tiptoppay.mx/test_api_00000000000000000000002/logo.PNG",
    "TerminalUrl": "demo.tiptoppay.mx",
    "TerminalFullUrl": "https://demo.tiptoppay.mx",
    "WidgetUrl": "https://widget.tiptoppay.mx/",
    "IsCharity": false,
    "IsTest": true,
    "TerminalName": "Demo site",
    "SkipExpiryValidation": true,
    "AgreementPath": "",
    "IsCvvRequired": true,
    "ExternalPaymentMethods": [
      {
        "Type": 16,
        "Enabled": true
      }
    ],
    "Features": {
      "IsAllowedNotSanctionedCards": true,
      "IsQiwi": false,
      "IsForeignCurrencyGateway": false,
      "IsSaveCard": 2,
      "IsPayOrderingEnabled": true,
      "IsThreeCardInput": true
    },
    "SupportedCards": [
      0,
      1,
      2,
      3,
      4,
      5,
      6,
      7,
      8,
      9,
      10,
      11,
      12,
      13,
      14,
      15,
      16,
      17,
      100
    ],
    "DisplayAdvertiseBannerOnWidget": false,
    "BannerAdvertiseUrl": null,
    "Status": 0
  },
  "Success": true,
  "Message": null,
  "ErrorCode": null
}

Retrieving details for installment payment by card

The endpoint is designed to retrieve the installment periods available for installment purchases and the approximate monthly payment amount for these periods.

Method URL:

https://api.tiptoppay.mx/installments/calculate/sum-by-period?amount=&terminalPublicId=

Request parameters:

No. Name Type Data type Description
1 terminalPublicId query string public ID of the terminal
2 amount query decimal installment payment by card amount

Example request:

https://api.tiptoppay.mx/installments/calculate/sum-by-period?terminalPublicId=pk_798df82a361070a52485c827dc6f4&amount=110

Response example:

{
    "Model": {
        "IsCardInstallmentAvailable": true,
        "Configuration": [
            {
                "Term": 3,
                "MonthlyPayment": 36.67
            }
        ]
    },
    "Success": true,
    "Message": null,
    "ErrorCode": null
}

Checking card by bin

The method is designed to retrieve accurate bank card details by the first 6, 7, or 8 digits of its number.

Method URL:

https://api.tiptoppay.mx/bins/info?Bin=&currency=&amount=&isAllowedNotSanctionedCards=&isQiwi=&IsCheckCard=&TerminalPublicId=&SevenNumberHash=&EightNumberHash=

Request parameters:

Field Type Data type Description
Bin query string first 6 digits of the card number
currency query string transaction currency
amount query decimal transaction amount
isAllowedNotSanctionedCards query boolean support for non-sanctioned cards
isQiwi query boolean whether the gateway from which the payment is made is a Qiwi gateway
isForeignCurrencyGateway query boolean the gateway from which the payment is made is limited to transactions in foreign currency
SevenNumberHash query string hash of the first 7 digits of the card number
EightNumberHash query string hash of the first 8 digits of the card number
TerminalPublicId query string public ID of the terminal; required to check the card for installment payment eligibility
IsCheckCard query boolean used for checking card for installment payments
true: check the card
false: do not check the card
mandatory: pass the value true to check the card for installment payment eligibility

Example request:

https://api.tiptoppay.mx/bins/info?Bin=400000&currency=MXN&amount=110&isAllowedNotSanctionedCards=true&isQiwi=false&IsCheckCard=true&TerminalPublicId=pk_798df82a361070a52485c827dc6f4&SevenNumberHash=5033663954b22fc24d494bbf51402ee403bafc1ff40f35b7a1f5ae4e9e4b0ffe7598574ea0c8e56597f69b6f617a5fb37c278b3273c3ff6df3d6f9f4e16af052&EightNumberHash=68a1a1fd4de784e3a2e0e956d0a63ac4ca540ef90e7fd9a2ddc92cf68e52e29792db64f6615054a6e5460467f0b7abe055c899136d98ce6ebab3d580bc55ec86

Response example:

{
    "Model": {
        "LogoUrl": "",
        "BankName": "Bank Banorte Mexico",
        "Currency": null,
        "ConvertedAmount": null,
        "HideCvvInput": false,
        "CardType": null,
        "CountryCode": 484,
        "IsCardAllowed": true
    },
    "Success": true,
    "Message": null,
    "ErrorCode": null
}

Notifications

Notification is an HTTP request from the system to your site. Similar requests are also called callback or webhook. The system provides several types of notifications: check whether it is possible to make a payment, information about successful and unsuccessful payments.

Check

The Check notification is performed once a cardholder filled in a payment form and pressed the “Pay” button. It serves the purpose of payment validation: the system sends a request to a merchant's website address with payment information, and the website must validate and define if it's needed to confirm or reject the payment.

The list of parameters transmitted in the request body is presented in the table:

Parameter Format Use Description
TransactionId Numeric Required Transaction number in the system
Amount Numeric, dot as separator, two digits after dot Required Amount specified in payment parameters
Currency String Required Currency: MXN specified in payment parameters (see reference)
DateTime yyyy-MM-dd HH:mm:ss Required Payment creation date / time in the UTC time zone
CardFirstSix String(6) Required First 6 digits of a card number
CardLastFour String(4) Required Last 4 digits of a card number
CardType String Required Card Payment System: Visa, MasterCard, American Express, or Carnet
CardExpDate String Required Expiration date in MM/YY format
TestMode Bit (1 or 0) Required Test mode sign
Status String Required Payment status if successful: Completed — for SMS sheme
OperationType String Required Transaction type: Payment/Refund
InvoiceId String Optional Order number specified in payment parameters
Name String Optional Cardholder's name
Email String Optional Payer's E-mail address
IpAddress String Optional Payer's IP address
IpCountry String(2) Optional Two-letter code of a country of a payer's location by ISO3166-1
IpCity String Optional Payer's location city
IpRegion String Optional Payer's location region
IpDistrict String Optional Payer's location district
Issuer String Optional Name of a card issuing bank
IssuerBankCountry String(2) Optional Two-letter country code of a card issuer by ISO3166-1
Description String Optional Payment description specified in payment parameters

The system expects a response in JSON format with the required parameter code:

{"code":0}

The code defines a payment result and can take the following values:

Code Description Result
0 Payment can be done The system will authorize a payment
10 Invalid order number Payment will be declined
11 Invalid AccountId Payment will be declined
12 Invalid amount Payment will be declined
13 Payment cannot be accepted Payment will be declined
20 Payment overdue Payment will be declined, a payer will receive a notification

Pay

The Pay notification is performed once a payment is successfully completed and an issuer's authorization is received.

It serves the purpose of information about a payment: the system sends a request to a merchant's website address with payment information, and the merchant's site has to register the fact of payment.

The list of parameters transmitted in the request body is presented in the table:

Parameter Format Use Description
TransactionId Numeric Required Transaction number in the system
Amount Numeric, dot as separator, two digits after dot Required Amount specified in payment parameters
Currency String Required Currency: MXN specified in payment parameters (see reference)
DateTime yyyy-MM-dd HH:mm:ss Required Payment creation date / time in the UTC time zone
CardFirstSix String(6) Required First 6 digits of a card number
CardLastFour String(4) Required Last 4 digits of a card number
CardType String Required Card Payment System: Visa, MasterCard, American Express, or Carnet
CardExpDate String Required Expiration date in MM/YY format
TestMode Bit (1 or 0) Required Test mode sign
Status String Required Payment status once authorized: Completed — for SMS sheme
OperationType String Required Operation type: Payment/Refund
GatewayName String Required Acquiring Bank Identifier
InvoiceId String Optional Order or Invoice number specified in payment parameters
Name String Optional Cardholder's name
Email String Optional Payer's E-mail address
IpAddress String Optional Payer's IP address
IpCountry String(2) Optional The Two-letter code of a country of a payer's location by ISO3166-1
IpCity String Optional Payer's location city
IpRegion String Optional Payer's location region
IpDistrict String Optional Payer's location district
Issuer String Optional Name of a card issuing bank
IssuerBankCountry String(2) Optional Two-letter country code of a card issuer by ISO3166-1
Description String Optional Payment description specified in payment parameters
TotalFee Decimal Required Total fee value
CardProduct String Optional Card Product Type
Rrn String Optional RRN is a unique transaction identifier assigned by the acquiring bank
CustomFields Array Optional The custom fields that the merchant passes in the payment request

The system expects a response in JSON format with the required parameter code:

{"code":0}

The code defines a payment result and can take only one value:

Code Value
0 Payment is registered

Fail

The Fail notification is performed if a payment was declined and is used to analyze a number and causes of failures.

You need to consider that a fact of decline is not final since a user can pay the second time.

The list of parameters transmitted in the request body is presented in the table:

Parameter Format Use Description
TransactionId Numeric Required Transaction number in the system
Amount Numeric, dot as separator, two digits after dot Required Amount specified in payment parameters
Currency String Required Currency: MXN specified in the payment parameters (see reference)
DateTime yyyy-MM-dd HH:mm:ss Required Payment creation date / time in the UTC time zone
CardFirstSix String(6) Required First 6 digits of a card number
CardLastFour String(4) Required Last 4 digits of a card number
CardType String Required Card Payment System: Visa, MasterCard, American Express, or Carnet
CardExpDate String Required Expiration date in MM/YY format
TestMode Bit (1 or 0) Required Test mode sign
Reason String Required Decline reason
ReasonCode Int Required Error Code (see the reference)
OperationType String Required Operation type: Payment/Refund
InvoiceId String Optional Order or Invoice number specified in payment parameters
Name String Optional Cardholder's name
Email String Optional Payer's E-mail address
IpAddress String Optional Payer's IP address
IpCountry String(2) Optional The Two-letter code of a country of a payer's location by ISO3166-1
IpCity String Optional Payer's location city
IpRegion String Optional Payer's location region
IpDistrict String Optional Payer's location district
Issuer String Optional Name of a card issuing bank
IssuerBankCountry String(2) Optional Two-letter country code of a card issuer by ISO3166-1
Description String Optional Payment description specified in payment parameters
Rrn String Optional RRN is a unique transaction identifier assigned by the acquiring bank
CustomFields Array Optional The custom fields that the merchant passes in the payment request

The system expects a response in JSON format with the required parameter code:

{"code":0}

The code defines a payment result and can take only one value:

Code Value
0 Attempt is registered

Refund

The Refund notification is performed if a payment was refunded (fully or partially) on your initiative via Control panel.

The list of parameters transmitted in the request body is presented in the table:

Parameter Format Use Description
TransactionId Numeric Required Refund transaction number in the system
PaymentTransactionId Int Required Payment transaction number in the system (original)
Amount Numeric, dot as separator, two digits after dot Required Refund amount in payment currency
DateTime yyyy-MM-dd HH:mm:ss Required Refund date / time in UTC time zone
OperationType String Required Operation type: Payment/Refund
InvoiceId String Optional Invoice or Order number of the original transaction
AccountId String Optional Payer's ID of the original transaction
Email String Optional Payer's E-mail address
Rrn String Optional RRN is a unique transaction identifier assigned by the acquiring bank
CustomFields Array Optional The custom fields that the merchant passes in the payment request

The system expects a response in JSON format with the required parameter code:

{"code":0}

The code defines a payment result and can take only one value:

Code Value
0 Refund is registered

Notification Validation

All the notifications — check, pay, fail and refund - have the X-Content-HMAC and Content-HMAC HTTP headers which contains a validation value of a request which is calculated using the HMAC algorithm. The only difference is that the first one is generated from URL decoded (or not encoded) parameters, and the second one is generated from URL encoded parameters (which can cause problems). If you need to verify authenticity and integrity of notifications, you can calculate a validation value on your side and compare it with the request value. The coincidence confirms that you received the notification we sent in the original form.

Please pay attention to the following points when implementing notification validation:

HMAC calculation Examples in different programming languages.

The system sends notifications from the following addresses: 54.176.98.0/32.

For you, this means that:

Learn more how to opt out of SSL3. After June 8, https notifications to servers that support only SSL3 may not be delivered.


Installment payment by card

TipTop Pay offers installment payments by card as a payment method. Installment payments by card are only available to holders of credit cards issued with a Mexican bank. To activate installment payments, contact your personal manager at TipTop Pay.

Installment payments in the widget

If the website allows installment payment for goods, the widget shows the client a button called "Pagar en meses sin intereses"; by clicking it, the client proceeds to a separate page of the widget.

On the installment payment page, the client must enter card details*, select the installment period* and click Pay.

*Requirements for card details and available installment periods can be clarified with your personal manager at TipTop Pay.

To integrate installment payments by card, the following procedure is required:

  1. Check if your website allows installment payments by card; to check, invoke the method GET: /merchant/configuration/?terminalPublicId=&paymentUrl=&language=
    1. If the response contains the array "ExternalPaymentMethods" with { "Type": 16, "Enabled": true }, then installment payments are allowed on your website. Proceed to the next step.
    2. Otherwise, installment payments are not available at your terminal.
  2. Retrieve the available installment payment periods and the approximate monthly payment amount for these periods to pay for this purchase. To do this, invoke the method GET: api/installments/calculate/sum-by-period?amount=&terminalPublicId=
    1. If the response contains IsCardInstallmentAvailable:false, then it is not possible to pay for this purchase in installments.
    2. If the response contains IsCardInstallmentAvailable:true, then the Configuration array will be retrieved with the periods to pay for this installment purchase and the approximate monthly payment amount for each period.
  3. To make an installment payment, the client must enter card details that meet the requirements for installment payments, select the installment period, and click Pay.
    1. You can perform checks for card details on your side or use our mechanism to check cards for installment payment eligibility.
      • In order to check card details for installment payment eligibility in the TipTopPay system, invoke GET: bins/info; in Path params, in addition to the fields with the card number, pass IsCheckCard:true, TerminalPublicId: <your TerminalPublicId>.
        1. If the response contains IsCardAllowed:true field, then the card is eligible for installment payments.
        2. If the response contains IsCardAllowed:false field, then the card is ineligible for installment payment. The client must use a different card. Installment payment attempts with such a card will be rejected with an error message.
  4. To execute an installment payment request, invoke the method POST: /payments/cards/charge; in its body, pass the installment data in the InstallmentData field. See the field description in the /payments/cards/charge method description. In response, the data for 3DS is retrieved.
  5. Execute 3DS on installment payments by card. The 3DS process is identical to the 3DS process for a card payment without installments. For a description of the 3DS process, see the corresponding section.
  6. After completing 3DS, the result of the installment payment by card will be retrieved. See the payment result field description in the /payments/cards/charge method response fields description

Integration Scenarios

The system offers various integration options from very simple to infinitely functional depending on the requirements.

Payment Form

If you do not need to check payments before payment and record a fact after payment:

Payment Registering

If you need to register payments in your system without pre-check, then your actions are:

Payment Checking and Registering

If you need to check and register payments in your system, then your actions are:

Testing

Once you have an access to Control panel, it is in a test mode already which means that payments and other operations will take place in emulation mode.

For testing, you can use the following card data:

Type Card Number Payment result
Card Visa with 3-D Secure 4242 4242 4242 4242 Successful result
Card MasterCard with 3-D Secure 5555 5555 5555 4444 Successful result
Card Visa with 3-D Secure 4012 8888 8888 1881 Insufficient funds
Card MasterCard with 3-D Secure 5105 1051 0510 5100 Insufficient funds

Reference

Error Codes

You can see the error codes below that determine the reason of payment rejection.

The payment widget displays an error message automatically.

Code Name Reason Message for payer
5001 Refer To Card Issuer Issuer declined the operation Contact your bank or use another card
5003 Invalid Merchant Issuer declined the operation Contact your bank or use another card
5004 Pick Up Card Lost Card Contact your bank or use another card
5005 Do Not Honor Issuer declined without explanation
- CVV code is incorrect for MasterCard;
- Issuer Bank internal limitations;
- card is locked or not activated yet;
- card is not allowed for online payments or has no 3-D secure.		 Contact your bank or use another card
5006 Error Network failure to perform an operation or incorrect CVV code Check the correctness of entered card data or use another card
5007 Pick Up Card Special Conditions Lost Card Contact your bank or use another card
5012 Invalid Transaction The card is not intended for online payments Contact your bank or use another card
5013 Amount Error Too small or too large transaction amount Check the correctness of the amount
5014 Invalid Card Number Invalid Card Number Check the correctness of entered card data or use another card
5015 No Such Issuer Unknown card issuer Use another card
5019 Transaction Error Issuer declined without explanation
- CVV code is incorrect for MasterCard;
- Issuer Bank internal limitations;
- card is locked or not activated yet;
- card is not allowed for online payments or has no 3-D secure.		 Contact your bank or use another card
5030 Format Error Error on the side of the acquirer - incorrectly formed transaction Try again later
5031 Bank Is Not Supported By Switch Unknown card issuer Use another card
5033 Expired Card Pickup Expired Card Pickup Contact your bank or use another card
5034 Suspected Fraud Issuer failure - fraud is suspected Contact your bank or use another card
5036 Restricted Card The card is not intended for online payments Contact your bank or use another card
5041 Lost Card Lost Card Contact your bank or use another card
5043 Stolen Card Stolen Card Contact your bank or use another card
5051 Insufficient Funds Insufficient Funds Insufficient Funds
5054 Expired Card Card is expired or expiration date is incorrect Check the correctness of entered card data or use another card
5057 Transaction Is Not Permitted Card limitation
— internal limitations of Issuer
— card is locked or not activated yet;
— card is not allowed for online payments or has no 3-D secure.		 Contact your bank or use another card
5062 Restricted Card 2 The card is not intended for online payments Contact your bank or use another card
5063 Security Violation The card is blocked by security violation Use another card
5065 Exceed Withdrawal Frequency Card transactions limit is exceeded Contact your bank or use another card
5082 Incorrect CVV Incorrect CVV code Incorrect CVV code
5091 Timeout Issuer is not available Try again later or use another card
5092 Cannot Reach Network Issuer is not available Try again later or use another card
5096 System Error Acquiring bank or network error Try again later
5204 Unable To Process The operation cannot be processed for other reasons Contact your bank or use another card
5206 Authentication failed 3-D secure Authentication failed Contact your bank or use another card
5207 Authentication unavailable 3-D secure Authentication unavailable Contact your bank or use another card
5300 Anti Fraud Acquirer Transaction Limits Use another card
5302 Automatic authentication retry 3DS authentication is requested by Antifraud, a subsequent transaction will be created automatically –
6018 Payment method not supported Currently selected payment method is not supported Use another payment method
6019 Amount limit not found Amount limits for conducting transactions using the selected payment method are not configured Use another payment method
6020 Installment period not found Installment period for conducting transactions using the selected payment method are not configured Use another payment method

Check notitifcation processig responses

You can see the codes below how system registers your replies on check notification.

Code Name Reason
3001 InvalidInvoiceId Callback handler returned {"code":10}
3002 InvalidAccountId Callback handler returned {"code":11}
3003 InvalidAmount Callback handler returned {"code":12}
3004 OutOfDate Callback handler returned {"code":20}
3005 FormatError Callback handler returned a different code from expected
3006 Unavailable Service unavailable
3007 UnableToConnect Unable to connect (404, 504, 508 etc)
3008 NotAccepted Callback handler returned {"code":13}

Operation Types

The following table presents codes of operation types in notifications.

Code Name
Payment Payment
Refund Refund

Transaction Statuses

The following table presents transaction statuses, conditions of use, and possible actions.

Status Description Use Possible actions
AwaitingAuthentication Awaiting Authentication When a payer is visiting an issuer's website while waiting for 3-D Secure results No actions
Authorized Authorized When authorized Confirm, Cancel
Completed Completed When operation is confirmed Refund
Cancelled Cancelled In case of cancellation of operation No actions
Declined Declined In case of failure to complete transaction (Insufficient Funds, etc) No actions

Currency List

Our partners accept payments in MX.

The following table presents the names of the currencies and their codes which can be assigned to the currency parameter of the Widget.

Name Code
Mexican peso MXN

If the currency you need is not listed, email us at [email protected] and we will update the list.

Notification Types

The table below contains the types of notifications.

Code Name
Check Check
Pay Pay
Fail Fail
Refund Refund
Example