ATH Móvil's Javascript integration provides a simple, secure and fast checkout experience to customers paying on your website. After integrating our Payment Button on your website, you will be able to receive real time payments from more than 1.5 million ATH Móvil users.
Before you begin, please review the following prerequisites:
-
An active ATH Móvil Business account is required to continue. To sign up, download "ATH Móvil Business" on the App Store or Play Store of your iOS or Android device.
-
Your ATH Móvil Business account needs to have a registered, verified and active ATH® card.
-
Have the public and private API keys of your Business account at hand. You can view your API keys on the settings section of ATH Móvil Business for iOS or Android.
If you need help signing up, adding a card or have any other question please refer to https://athmovilbusiness.com/preguntas or contact our support team at (787) 773-5466. For technical support please complete the following form: https://forms.gle/ZSeL8DtxVNP2K2iDA.
Before getting started you will need to add references to both jQuery and ATH Móvil's javascript on your project's HTML checkout file.
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script><script src="https://www.athmovil.com/api/js/v3/athmovilV3.js"></script>Notes:
- ATH Móvil's javascript must be referenced at the bottom of the document since some variables need to be previously initialized.
- jQuery can be referenced on any location. Local versions can also be used. Version 3.3.1 or higher is required.
To integrate ATH Móvil’s Payment Button on your website follow these steps:
Add the “Pay with ATH Móvil” button to your checkout view.
<div id="ATHMovil_Checkout_Button"></div>- Button width is set to fill its parent.
- Button height is proportional to the width.
Configure the payment values using the javascript script below on your checkout view.
<script type="text/javascript">
ATHM_Checkout = {
env: 'sandbox',
publicToken: 'sandboxtoken01875617264',
timeout: 600,
theme: 'btn',
lang: 'en',
total: 1.00,
tax: 1.00,
subtotal: 1.00,
metadata1: 'metadata1 test',
metadata2: 'metadata2 test',
items: [
{
"name":"First Item",
"description":"This is a description.",
"quantity":"1",
"price":"1.00",
"tax":"1.00",
"metadata":"metadata test"
},
{
"name":"Second Item",
"description":"This is another description.",
"quantity":"1",
"price":"1.00",
"tax":"1.00",
"metadata":"metadata test"
}
]
}
</script>- Details:
| Variable | Data Type | Required | Values | Description |
|---|---|---|---|---|
env |
String | Yes | sandbox or production |
Determines the environment to be used for the payment. Use sandbox for simulated payment responses or production for real payments. |
publicToken |
String | Yes | Business account public token. | Determines the Business account that the payment will be sent to. |
timeout |
Number | No | Number between 120 and 600. |
Cancels the payment process if the payment hasn't been completed by the end user after the provided amount of time (in seconds). Timer starts immediately after the end user presses the Payment Button. Default value is set to 600 seconds (10 mins). |
theme |
String | Yes | btn, btn-dark or btn-light. |
Determines the colors of the “Pay with ATH Móvil” button that is displayed on your view. |
lang |
String | Yes | en for english or es for spanish. |
Determines the language of the “Pay with ATH Móvil” button and the payment process. |
total |
Number | Yes | From 1.00 to 1500.00. |
Total amount to be paid by the end user. |
tax |
Number | No | Optional variable to display the payment tax (if applicable). | |
subtotal |
Number | No | Optional variable to display the payment subtotal to the end user (if applicable). | |
metadata1 |
String | No | Optional variable to attach key-value data to the payment object. | |
metadata2 |
String | No | Optional variable to attach key-value data to the payment object. | |
items |
Array | Yes | Optional variable to display the items that the user is purchasing on ATH Móvil's payment screen. metadata and tax are required but they can be set as null. |
theme:
| Theme | Example |
|---|---|
btn |
 |
btn-light |
 |
btn-dark |
 |
lang:
| Languages | Example |
|---|---|
en |
|
es |
 |
Handle all payment responses.
- Completed
onCompletedPayment: function (response)
{
//Handle response
},- Cancelled
onCancelledPayment: function (response)
{
//Handle response
},- Expired
onExpiredPayment: function (response)
{
//Handle response
}- Completed
responsedata example
{
"status": "completed",
"date": "2019-06-06 16:12:02.0",
"referenceNumber": "a387643827-fdew98ffw9fbfewkjb",
"dailyTransactionID": "1234",
"name": "Valeria Herrero",
"phoneNumber": "7871234567",
"email": "valher@gmail.com",
"message": "",
"total": 1.00,
"tax": 1.00,
"subtotal": 1.00,
"fee": 0.06,
"netAmount": 0.94,
"totalRefundedAmount": 0.00,
"metadata1": "metadata1 test",
"metadata2": "metadata2 test",
"items": "[{\"name\":\"First Item\",\"description\":\"This is a description.\",\"quantity\":\"1\",\"price\":\"1.00\",\"tax\":\"1.00\",\"metadata\":\"metadata test\"},{\"name\":\"Second Item\",\"description\":\"This is another description.\",\"quantity\":\"1\",\"price\":\"1.00\",\"tax\":\"1.00\",\"metadata\":\"metadata test\"}]"
}To test ATH Móvil’s Payment Button on your website follow these steps:
-
Set
envtosandbox. -
Set
publicTokentosandboxtoken01875617264. -
Test the payment process with the new configuration.
-
Use any username and password to log in.
-
Complete, cancel or wait for the payment to expire to test all possible responses.
The following services can be used to search for transactions, perform refunds and request information of multiple payments received in a given time frame.
- Method:
POST - Headers:
Content-Type-application/json - Endpoint:
https://www.athmovil.com/rs/v3/searchTransaction - Body Example:
{
"publicToken": "hdb932832klnasKJGDW90291",
"privateToken": "JHEFEWP2048FNDFLKJWB2",
"referenceNumber": "a387643827-fdew98ffw9fbfewkjb",
"dailyTransactionID": "1234",
"name": "Valeria Herrero",
"phoneNumber": "(787) 123-4567",
"email": "valher@gmail.com",
"total": "1.00",
"metadata1": "metadata1 test",
"metadata2": "metadata2 test"
}-
Only
publicToken,privateTokenany other field is required to search for a transaction. -
The value of phoneNumber needs to be formatted as in the provided example.
-
To find results the provided field value must be an exact match with the field value of at least one transaction.
-
Multiple fields can be used simultaneously on the request.
-
Reponse Example:
{
"transactionType": "ecommerce",
"status": "completed",
"date": "2019-06-06 16:12:02.0",
"referenceNumber": "402894d56b240610016b2e6c78a6003a",
"dailyTransactionID": 1,
"name": "Valeria Herrero",
"phoneNumber": "(787) 123-4567",
"email": "valher@gmail.com",
"message": "",
"total": 1.00,
"tax": 1.00,
"subtotal": 1.00,
"fee": 0.06,
"netAmount": 0.94,
"totalRefundedAmount": 0.00,
"metadata1": "metadata1 test",
"metadata2": "metadata2 test",
"items": [
{
"name": "First Item",
"description": "This is a description.",
"quantity": "1",
"price":"1.00",
"tax": "1.00",
"metadata": "metadata test"
},
{
"name": "Second Item",
"description": "This is another description.",
"quantity": "1",
"price": "1.00",
"tax": "1.00",
"metadata":"metadata test"
}
]
}- If more than one transaction matches the provided fields all matching payments will be sent on the response as a list.
- Method:
POST - Headers:
Content-Type-application/json - Endpoint:
https://www.athmovil.com/rs/v3/refundTransaction - Body Example:
{
"publicToken": "hdb932832klnasKJGDW90291",
"privateToken": "JHEFEWP2048FNDFLKJWB2",
"referenceNumber": "387643827-fdew98ffw9fbfewkjb"
"amount":"1.00"
}- Response Example:
{
"transactionType": "Refund",
"status": "completed",
"refundedAmount": 1.00,
"date": "2019-06-06 16:12:02.0",
"referenceNumber": "402894d56b240610016b2e6c78a6003a",
"dailyTransactionID": "1",
"name": "Valeria Herrero",
"phoneNumber": "7871234567",
"email": "valher@gmail.com",
"message": "",
"total": 1.00,
"tax": 1.00,
"subtotal": 1.00,
"fee": 0.06,
"netAmount": 0.94,
"totalRefundedAmount": 1.00,
"metadata1": "metadata1 test",
"metadata2": "metadata2 test",
"items": [
{
"name": "First Item",
"description": "This is a description.",
"quantity": "1",
"price":"1.00",
"tax": "1.00",
"metadata": "metadata test"
},
{
"name": "Second Item",
"description": "This is another description.",
"quantity": "1",
"price": "1.00",
"tax": "1.00",
"metadata":"metadata test"
}
]
}- Method:
GET - Headers:
Content-Type-application/json - Endpoint:
https://www.athmovil.com/transactions/v3/transactionReport - Body Example:
{
"publicToken": "hdb932832klnasKJGDW90291",
"privateToken": "JHEFEWP2048FNDFLKJWB2",
"fromDate": "2019-01-01 16:12:02",
"toDate":"2019-06-06 16:12:02"
}- Response Example:
[
{
"transactionType": "ECOMMERCE",
"status": "COMPLETED",
"date": "2019-06-06 16:12:02",
"referenceNumber": "4028f9e0744c744a01744c7af12e0000",
"dailyTransactionID": 3,
"name": "Valeria Herrero",
"phoneNumber": "(787) 123-4567",
"email": "valher@gmail.com",
"message": "",
"total": 1.00,
"tax": 1.00,
"subtotal": 1.00,
"fee": 0.06,
"netAmount": 0.94,
"totalRefundedAmount": 1.00,
"metadata1": "metadata1 test",
"metadata2": "metadata2 test",
"items": [
{
"name": "First Item",
"description": "This is a description.",
"quantity": "1",
"price":"1.00",
"tax": "1.00",
"metadata": "metadata test"
},
{
"name": "Second Item",
"description": "This is another description.",
"quantity": "1",
"price": "1.00",
"tax": "1.00",
"metadata":"metadata test"
}
]
},
{
"transactionType": "ECOMMERCE",
"status": "COMPLETED",
"date": "2019-01-01 16:12:02",
"referenceNumber": "4028f9e0744c744a01744c7af12e0000",
"dailyTransactionID": 3,
"name": "Valeria Herrero",
"phoneNumber": "(787) 123-4567",
"email": "valher@gmail.com",
"message": "",
"total": 1.00,
"tax": 1.00,
"subtotal": 1.00,
"fee": 0.06,
"netAmount": 0.94,
"totalRefundedAmount": 1.00,
"metadata1": "metadata1 test",
"metadata2": "metadata2 test",
"items": [
{
"name": "First Item",
"description": "This is a description.",
"quantity": "1",
"price":"1.00",
"tax": "1.00",
"metadata": "metadata test"
},
{
"name": "Second Item",
"description": "This is another description.",
"quantity": "1",
"price": "1.00",
"tax": "1.00",
"metadata":"metadata test"
}
]
}
]
The use of this API and any related documentation is governed by and must be used in accordance with the Terms and Conditions of Use of ATH Móvi Business ®, which may be found at: https://athmovilbusiness.com/terminos.