General

Terms and Definitions

• System — TipTop Pay payment gateway.
  
• Merchant — TipTop Pay client who works with the System.
  
• Control panel — merchant's control panel in the system, located at merchant.tiptoppay.mx
• Card — a bank card of Visa, MasterCard, American Express or Carnet.
• Acquirer — a settlement bank.
  
• Issuer — a bank that issued a card.
• Cardholder — an owner of a card issued by a bank.
• Widget — payment form, provided by the system to enter card data by a holder and perform a further authorization.
• 3-D Secure — protocol to verify a holder by the issuer.
  

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:

• Via payment form — widget. Add a script that opens a secure payment form (iframe) to enter card data.

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

The installation instructions can be found in the file.

PrestaShop

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

Magento

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
            }         
        }
    )
};    

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:

• charge for single

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

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

• For notifications sent by POST method the message is represented by a request body. For GET method it is string parameters;
  
• When calculating HMAC, use UTF8 encoding;
• Hash is calculated by SHA256 function;
  
• The secret API is used as a key, which can be obtained in your Control panel;
  
• The calculated value is passed in base64 encoding.

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:

• If you do not use Pay / Check / Fail / Refund notifications, then you do not need to do anything;
• If you are using at least one of these notifications, then you need to check which https encryption protocols your server supports. If your server only supports SSL3, then you need to upgrade it to at least TLS11. It will be even better if you upgrade to TLS13. As a last resort, you can translate notifications to the http protocol.

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

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:

• Add the widget script on your site;
• Specify an email address for payment notifications in Control panel.

Payment Registering

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

• Add the script on your site;

• Make a payment registering:

  • Create a handler for Pay notification, for example https://site.com/webhooks/tiptoppay/pay;
  • Provide a logic of a payment registration in the handler and a response in JSON format;
  • Enable the Pay notifications function in Control panel.

Payment Checking and Registering

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

• Add the widget script on your site;

• Make a payment checking:

  • Create a handler for Check notification, for example on, https://site.com/webhooks/tiptoppay/check;
  • Provide a logic of a payment registration in the handler and a response in JSON format;

• Make a payment registering:

  • Create a handler for Pay notification, for example on, https://site.com/webhooks/tiptoppay/pay;
  • Provide a logic of a payment registration in the handler and a response in JSON format;

• Enable the Check and Pay notifications function in Control panel.

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:

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.

Check notitifcation processig responses

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

Operation Types

The following table presents codes of operation types in notifications.

Transaction Statuses

The following table presents transaction statuses, conditions of use, and possible 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.

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.