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

The installation instructions can be found in the file

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:

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.

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

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

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

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

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.


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

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