### Complete ATH Móvil Checkout Example
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/api-reference/athm-checkout.md
This HTML example demonstrates the full integration of the ATH Móvil Checkout, including setting the public token, loading the library, and configuring checkout parameters and callbacks.
```html
ATH Móvil Checkout
```
--------------------------------
### Find Payment Response Example
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/endpoints.md
Example of a successful response when a transaction is found and its status is COMPLETED.
```json
{
"status": "success",
"data": {
"ecommerceStatus": "COMPLETED",
"ecommerceId": "730e2c49-9387-11ed-8f43-c31784ccfc6c",
"referenceNumber": "215070443-402894c185ab1be40185acfe61c2000b",
"transactionDate": "2023-01-13 16:17:06",
"total": 1.00,
"fee": 0.60,
"netAmount": 0.40
}
}
```
--------------------------------
### HTML Setup for ATH Móvil Button
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/integration-guide.md
Include the necessary HTML elements and the athmovil_base.js library from the CDN to initialize the payment button.
```html
```
--------------------------------
### Initial Payment Response Example
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/endpoints.md
This is a success response for creating a new payment transaction. It includes the ecommerceId and auth_token needed for subsequent operations.
```json
{
"status": "success",
"data": {
"ecommerceId": "ad42df37-f989-11ed-8935-cd14e3558bc7",
"auth_token": "eyJraWQiOiJNeUtVRXZvb2NSMWptbnZocHZXVEI0WmZvcU1wbEx6TWF5VzdjUWd1ck5FIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ..."
}
}
```
--------------------------------
### Update Phone Number Request Example
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/endpoints.md
This example demonstrates how to update a customer's phone number for an existing transaction using a cURL request. Ensure you include the correct authorization token and transaction details.
```bash
curl --location --request POST 'https://payments.athmovil.com/api/business-transaction/ecommerce/updatePhoneNumber' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--data-raw '{
"ecommerceId": "ad42df37-f989-11ed-8935-cd14e3558bc7",
"phoneNumber": "(787) 123-4567",
"publicToken": "a66ce73d04f2087615f6320b724defc5b4eedc55"
}'
```
--------------------------------
### Error Response Example
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/endpoints.md
This is an example of an error response from the payment API. It indicates the status, a descriptive message, an error code, and null data.
```json
{
"status": "error",
"message": "The transfer amount is under Minimum allowed",
"errorcode": "BTRA_0001",
"data": null
}
```
--------------------------------
### Complete Payment Page Integration
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/README.md
This example demonstrates a full payment page integration. It includes setting up the checkout details, displaying the payment button, and handling success, failure, and cancellation scenarios.
```html
Checkout
Order Checkout
Order Summary
Subtotal: $89.99
Tax: $10.00
Total: $99.99
```
--------------------------------
### Search Transaction Response Body
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/README.md
This is an example of a successful response when searching for transactions. If multiple transactions match the query, they will be returned as a list.
```json
{
"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"
}
]
}
```
--------------------------------
### Full ATH Móvil Checkout Configuration
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/configuration.md
This example demonstrates a comprehensive configuration for the ATH Móvil checkout, including detailed item information, taxes, and advanced metadata. Use this for complex transactions requiring more specific data.
```javascript
const ATHM_Checkout = {
env: 'production',
publicToken: 'a66ce73d04f2087615f6320b724defc5b4eedc55',
timeout: 600,
orderType: 'ecommerce',
theme: 'btn-dark',
lang: 'es',
total: 49.99,
subtotal: 45.00,
tax: 4.99,
metadata1: 'location-pr-001',
metadata2: 'campaign-spring-2024',
items: [
{
name: 'Wireless Headphones',
description: 'Bluetooth over-ear headphones',
quantity: '1',
price: '25.00',
tax: '2.50',
metadata: 'electronics'
},
{
name: 'Phone Case',
description: 'Protective phone case',
quantity: '2',
price: '10.00',
tax: '1.00',
metadata: 'accessories'
}
],
phoneNumber: '(787) 123-4567'
};
```
--------------------------------
### Basic HTML Setup for ATH Móvil Payment
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/README.md
This snippet shows the essential HTML structure, including placeholder for the button, public token definition, library loading, and initial configuration for the ATH Móvil payment button.
```html
ATH Móvil Payment
```
--------------------------------
### ATH Móvil Payment Callback Functions
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/README.md
Provides example implementations for callback functions that handle payment completion, cancellation, and timeouts. These functions are invoked by the ATH Móvil library based on transaction events.
```javascript
// Called when payment completes
async function authorizationATHM() {
const response = await authorization();
// response.data has full transaction details
}
// Called when payment is cancelled
async function cancelATHM() {
const response = await findPaymentATHM();
// response.data.ecommerceStatus = "CANCEL"
}
// Called when payment times out
async function expiredATHM() {
const response = await findPaymentATHM();
// response.data.ecommerceStatus = "CANCEL"
}
```
--------------------------------
### JavaScript Example: Full Refund
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/api-reference/server-api.md
Demonstrates how to perform a full refund for a transaction using the server API. Ensure you have the correct tokens and transaction details. This function also handles updating the order status upon successful refund.
```javascript
// Full refund
async function refundTransaction(referenceNumber, amount) {
const response = await fetch(
'https://payments.athmovil.com/api/business-transaction/ecommerce/refund',
{
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
publicToken: 'a66ce73d04f2087615f6320b724defc5b4eedc55',
privateToken: 'JHEFEWP2048FNDFLKJWB2',
referenceNumber: referenceNumber,
amount: amount.toString(),
message: 'Customer requested refund'
})
}
);
const data = await response.json();
if (data.status === 'success') {
console.log('Refund completed');
console.log('Refund ref:', data.data.refund.referenceNumber);
console.log('Refund amount:', data.data.refund.refundedAmount);
// Update order status to refunded
await updateOrderStatus(referenceNumber, 'refunded');
} else {
console.error('Refund failed:', data.errorcode);
}
return data;
}
// Partial refund
async function partialRefund(referenceNumber, refundAmount) {
return refundTransaction(referenceNumber, refundAmount);
}
```
--------------------------------
### Backend Payment Reconciliation with Node.js/Express
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/integration-guide.md
Verify payment status on your backend using this Node.js/Express example. It includes verifying the payment with ATH Móvil and updating order status.
```javascript
// Node.js / Express example
app.post('/api/orders/confirm-payment', async (req, res) => {
const { referenceNumber, ecommerceId, amount } = req.body;
try {
// Verify with ATH Móvil
const verification = await verifyPayment(
ecommerceId,
amount,
referenceNumber
);
if (verification.ecommerceStatus === 'COMPLETED') {
// Payment confirmed, update order
await updateOrderStatus(referenceNumber, 'paid');
// Update inventory
await updateInventory(req.orderId);
// Send confirmation email
await sendConfirmationEmail(req.orderId);
res.json({ success: true });
} else {
res.status(400).json({
error: 'Payment not in completed state',
status: verification.ecommerceStatus
});
}
} catch (error) {
res.status(500).json({ error: error.message });
}
});
async function verifyPayment(ecommerceId, expectedAmount, referenceNumber) {
const response = await fetch(
'https://payments.athmovil.com/api/business-transaction/ecommerce/business/findPayment',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer ' + getAuthToken()
},
body: JSON.stringify({
ecommerceId: ecommerceId,
publicToken: process.env.ATH_PUBLIC_TOKEN
})
}
);
const data = await response.json();
if (data.status === 'error') {
throw new Error('Transaction verification failed: ' + data.errorcode);
}
// Validate amount matches
if (data.data.total !== expectedAmount) {
throw new Error('Amount mismatch');
}
// Validate reference number
if (data.data.referenceNumber !== referenceNumber) {
throw new Error('Reference number mismatch');
}
return data.data;
}
```
--------------------------------
### Transaction Search Response Example
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/endpoints.md
This JSON object shows a successful response for a single transaction search. It details the transaction's type, status, date, reference number, total amount, fees, and metadata.
```json
{
"transactionType": "ECOMMERCE",
"status": "COMPLETED",
"date": "2019-06-06 16:12:02.0",
"referenceNumber": "402894d56b240610016b2e6c78a6003a",
"total": 1.00,
"fee": 0.06,
"netAmount": 0.94,
"metadata1": "store-123",
"metadata2": "order-456"
}
```
--------------------------------
### Completed Transaction Response
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/README.md
Example JSON response for a completed transaction. The 'ecommerceStatus' field will be 'COMPLETED'.
```json
{
"status": "success",
"data": {
"ecommerceStatus": "COMPLETED",
"ecommerceId": "730e2c49-9387-11ed-8f43-c31784ccfc6c",
"referenceNumber": "215070443-402894c185ab1be40185acfe61c2000b",
"businessCustomerId": "402894d56e713892016e7f2963de0010",
"transactionDate": "2023-01-13 16:17:06",
"dailyTransactionId": "0006",
"businessName": "I Love Puerto Rico",
"businessPath": "ilovepr",
"industry": "ENTERTAINMENT",
"subTotal": 0,
"tax": 0.00,
"total": 1,
"fee": 0.6000000238418579,
"netAmount": 0.40,
"totalRefundedAmount": 0,
"metadata1": "Metadata 1",
"metadata2": "Metada 2",
"items": [
{
"name": "Diego MO",
"description": "Diego",
"quantity": 1,
"price": 10,
"tax": 0,
"metadata": "ATH Movil es lo mejor"
}
],
"isNonProfit": false
}
}
```
--------------------------------
### Refund Success Response Example
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/endpoints.md
This JSON structure represents a successful response after a refund operation. It includes details about the refund itself and the original transaction's status.
```json
{
"status": "success",
"data": {
"refund": {
"transactionType": "REFUND",
"status": "COMPLETED",
"refundedAmount": 1.00,
"date": "123412341234",
"referenceNumber": "402894d56b240610016b2e6c78a6003a",
"dailyTransactionID": "0107"
},
"originalTransaction": {
"transactionType": "PAYMENT",
"status": "COMPLETED",
"total": 1.00,
"totalRefundedAmount": 1.00
}
}
}
```
--------------------------------
### Pending Transaction Response
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/README.md
Example JSON response for a transaction that is pending confirmation by the ATH Movil customer. The 'ecommerceStatus' field will be 'OPEN'.
```json
{
"status": "success",
"data": {
"ecommerceStatus": "OPEN",
"ecommerceId": "39906664-e44e-11ed-b127-a519df48811e",
"referenceNumber": "",
"businessCustomerId": "402894d56e713892016e7f2963de0010",
"transactionDate": "",
"dailyTransactionId": "",
"businessName": "I Love Puerto Rico",
"businessPath": "ilovepr",
"industry": "COMPUTERS",
"subTotal": 1.33,
"tax": 1.00,
"total": 2.33,
"fee": 0.00,
"netAmount": 0,
"totalRefundedAmount": 0,
"metadata1": "Metadata 1",
"metadata2": "Metada 2",
"items": [
{
"name": "Diego MO",
"description": "Diego",
"quantity": 1,
"price": 1.33,
"tax": 1,
"metadata": "ATH Movil es lo mejor",
"formattedPrice": "",
"sku": ""
}
],
"isNonProfit": false
}
}
```
--------------------------------
### GET /transactionReport
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/endpoints.md
Retrieves all transactions for a business within a specified date range. Requires business tokens and valid date parameters.
```APIDOC
## GET /transactionReport
### Description
Retrieves all transactions for a business within a date range.
### Method
GET
### Endpoint
`https://www.athmovil.com/transactions/v4/transactionReport`
### Parameters
#### Query Parameters (in request body as JSON):
- **publicToken** (string) - Required - Business public token
- **privateToken** (string) - Required - Business private token
- **fromDate** (string) - Required - Start date (format: `YYYY-MM-DD HH:mm:ss`). Cannot be future date.
- **toDate** (string) - Required - End date (format: `YYYY-MM-DD HH:mm:ss`). Must be after fromDate. Cannot be future date. Date range cannot exceed system limit.
### Request Example
```bash
curl --location --request GET 'https://www.athmovil.com/transactions/v4/transactionReport' \
--header 'Content-Type: application/json' \
--data-raw '{
"publicToken": "hdb932832klnasKJGDW90291",
"privateToken": "JHEFEWP2048FNDFLKJWB2",
"fromDate": "2019-01-01 16:12:02",
"toDate": "2019-06-06 16:12:02"
}'
```
### Response
`TransactionReportResponse` — Array of `PaymentData` objects, sorted chronologically.
#### Success Response (200)
- **transactionType** (string) - Type of transaction.
- **status** (string) - Status of the transaction.
- **date** (string) - Date and time of the transaction.
- **referenceNumber** (string) - Unique reference number for the transaction.
- **dailyTransactionID** (integer) - Daily transaction identifier.
- **total** (number) - Total amount of the transaction.
- **fee** (number) - Transaction fee.
- **netAmount** (number) - Net amount after fees.
#### Response Example
```json
[
{
"transactionType": "ECOMMERCE",
"status": "COMPLETED",
"date": "2021-07-08 00:36:39.0",
"referenceNumber": "402894d56b240610016b2e6c78a6003a",
"dailyTransactionID": 35,
"total": 1.00,
"fee": 0.00,
"netAmount": 1.00
}
]
```
#### Error Responses
- **400**: Invalid date format or date range invalid.
- **403**: Invalid tokens.
- **422**: Date range exceeds maximum allowed days.
- **500**: Internal server error.
```
--------------------------------
### Transaction Report Response Example
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/endpoints.md
This JSON structure represents a successful response from the /transactionReport endpoint, containing an array of completed payment data objects.
```json
[
{
"transactionType": "ECOMMERCE",
"status": "COMPLETED",
"date": "2021-07-08 00:36:39.0",
"referenceNumber": "402894d56b240610016b2e6c78a6003a",
"dailyTransactionID": 35,
"total": 1.00,
"fee": 0.00,
"netAmount": 1.00
},
{
"transactionType": "ECOMMERCE",
"status": "COMPLETED",
"date": "2021-07-08 00:35:43.0",
"referenceNumber": "402894d56b240610016b2e6c78a6003a",
"dailyTransactionID": 33,
"total": 5.00,
"fee": 0.00,
"netAmount": 5.00
}
]
```
--------------------------------
### Get Transaction Report
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/endpoints.md
Use this cURL command to retrieve all transactions for a business within a specified date range. Ensure you provide valid public and private tokens, and correctly formatted fromDate and toDate.
```bash
curl --location --request GET 'https://www.athmovil.com/transactions/v4/transactionReport' \
--header 'Content-Type: application/json' \
--data-raw '{
"publicToken": "hdb932832klnasKJGDW90291",
"privateToken": "JHEFEWP2048FNDFLKJWB2",
"fromDate": "2019-01-01 16:12:02",
"toDate": "2019-06-06 16:12:02"
}'
```
--------------------------------
### Get Transaction Report
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/README.md
Retrieves a transaction report.
```APIDOC
## Get Transaction Report
### Description
Retrieves a transaction report.
### Method
GET
### Endpoint
/transactionReport
### Purpose
Get transaction report
```
--------------------------------
### Cancel Transaction Success Response
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/endpoints.md
Example of a successful response after cancelling a payment.
```json
{
"status": "success",
"data": "Payment Cancelled."
}
```
--------------------------------
### Confirmation Pending Response
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/README.md
Example JSON response for a transaction confirmed by the customer but pending merchant processing. The 'ecommerceStatus' field will be 'CONFIRM'.
```json
{
"status": "success",
"data": {
"ecommerceStatus": "CONFIRM",
"ecommerceId": "39906664-e44e-11ed-b127-a519df48811e",
"referenceNumber": "",
"businessCustomerId": "402894d56e713892016e7f2963de0010",
"transactionDate": "",
"dailyTransactionId": "",
"businessName": "I Love Puerto Rico",
"businessPath": "ilovepr",
"industry": "COMPUTERS",
"subTotal": 1.33,
"tax": 1.00,
"total": 2.33
```
--------------------------------
### Set Environment
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/api-reference/athm-checkout.md
Configures the environment for the API endpoint. Currently, only the 'production' environment is supported.
```javascript
ATHM_Checkout.env = 'production';
```
--------------------------------
### Get Monthly Transaction Report
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/api-reference/server-api.md
Retrieves a report of all transactions within a specified month and year. Requires the year and month as input.
```APIDOC
## GET https://www.athmovil.com/transactions/v4/transactionReport
### Description
Retrieves a report of all transactions within a specified month and year. Requires the year and month as input.
### Method
GET
### Endpoint
https://www.athmovil.com/transactions/v4/transactionReport
### Parameters
#### Query Parameters
- **fromDate** (string) - Required - The start date and time for the report (YYYY-MM-DD HH:mm:ss).
- **toDate** (string) - Required - The end date and time for the report (YYYY-MM-DD HH:mm:ss).
#### Request Body
- **publicToken** (string) - Required - Your public API token.
- **privateToken** (string) - Required - Your private API token.
### Request Example
```json
{
"publicToken": "a66ce73d04f2087615f6320b724defc5b4eedc55",
"privateToken": "JHEFEWP2048FNDFLKJWB2",
"fromDate": "2024-05-01 00:00:00",
"toDate": "2024-05-31 23:59:59"
}
```
### Response
#### Success Response (200)
- **status** (string) - Indicates the success or failure of the request.
- **data** (array) - An array of transaction objects, or an empty array if no transactions are found.
#### Response Example
```json
{
"status": "success",
"data": [
{
"transactionId": "12345",
"total": 50.00,
"fee": 1.50,
"timestamp": "2024-05-28 10:00:00"
}
]
}
```
```
--------------------------------
### Configure ATH Móvil Checkout and Callbacks
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/README.md
This script configures the payment details and defines callback functions for authorization, cancellation, and timeouts. Ensure the `publicToken` is valid for your business account.
```javascript
const ATHM_Checkout = {
env: 'production',
publicToken: 'a66ce73d04f2087615f6320b724defc5b4eedc55',
timeout: 600,
orderType: '',
theme: 'btn',
lang: 'en',
total: 1,
subtotal: 1,
tax: 1,
metadata1: 'Prueba1.1',
metadata2: 'Prueba2.2',
items: [
{
"name":"Nombre de arreglo",
"description":"Prueba de items",
"quantity":"3",
"price":"2",
"tax":"1",
"metadata":"prueba metadata"
}
],
phoneNumber: ""
}
async function authorizationATHM(){
const responseAuth = await authorization();
console.log(responseAuth);
}
async function cancelATHM(){
const responseCancel = await findPaymentATHM();
console.log(responseCancel);
}
async function expiredATHM(){
const responseExpired = await findPaymentATHM();
console.log(responseExpired);
}
```
--------------------------------
### Implement ATH Móvil Callbacks
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/integration-guide.md
Implement the success, cancellation, and timeout callbacks required for ATH Móvil payment processing. These functions handle the outcomes of a payment attempt.
```javascript
// Success callback
async function authorizationATHM() {
try {
const response = await authorization();
handlePaymentSuccess(response);
} catch (error) {
handlePaymentError(error);
}
}
```
```javascript
// Cancellation callback
async function cancelATHM() {
try {
const response = await findPaymentATHM();
if (response.data.ecommerceStatus === 'CANCEL') {
showNotification('Payment was cancelled');
}
} catch (error) {
console.error('Cancel error:', error);
}
}
```
```javascript
// Timeout callback
async function expiredATHM() {
try {
const response = await findPaymentATHM();
if (response.data.ecommerceStatus === 'CANCEL') {
showNotification('Payment request timed out');
}
} catch (error) {
console.error('Expiration error:', error);
}
}
```
--------------------------------
### TransactionReportRequest Type
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/types.md
Defines the structure for requesting a transaction report. Requires public and private tokens, along with start and end dates.
```typescript
type TransactionReportRequest = {
publicToken: string,
privateToken: string,
fromDate: string,
toDate: string
}
```
--------------------------------
### ATH Móvil Payment Button Configuration Object
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/README.md
Defines the structure and types for the ATHM_Checkout configuration object. Refer to configuration.md for a complete list of options.
```javascript
ATHM_Checkout = {
env: string, // "production"
publicToken: string, // Your business token
timeout: number, // 120-600 seconds (default: 600)
theme: string, // "btn", "btn-dark", "btn-light"
lang: string, // "en" or "es"
total: number, // 1.00-1500.00
subtotal: number, // Optional
tax: number, // Optional
metadata1: string, // Required, max 40 chars
metadata2: string, // Required, max 40 chars
items: array, // Optional item list
phoneNumber: string // Customer's ATH Móvil phone
}
```
--------------------------------
### Transaction Report Response Body
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/README.md
This is an example of the response when requesting a transaction report. The response is a list of transactions that occurred within the specified date range.
```json
[
{
"transactionType": "ECOMMERCE",
"status": "COMPLETED",
"date": "2021-07-08 00:36:39.0",
"referenceNumber": "402894d56b240610016b2e6c78a6003a",
"dailyTransactionID": 35,
"name": "Valeria Herrero",
"phoneNumber": "(787) 123-4567",
"email": "valher@gmail.com",
"message": "",
"total": 1.00,
"tax": 0.00,
"subtotal": 0.00,
"fee": 0.00,
"netAmount": 1.00,
"totalRefundAmount": 1.00,
"metadata1": "metadata1 test",
"metadata2": "metadata2 test",
"items": [
{
"name": "Item",
"description": "Description",
"quantity": 1,
"price": 1.00,
"tax": 0.00,
"metadata": "Metadata"
},
{
"name": "item",
"description": "desc",
"quantity": 1,
"price": 1.00,
"tax": 0.00,
"metadata": "Metadata"
}
]
},
{
"transactionType": "ECOMMERCE",
"status": "COMPLETED",
"date": "2021-07-08 00:35:43.0",
"referenceNumber": "402894d56b240610016b2e6c78a6003a ",
"dailyTransactionID": 33,
"name": "Valeria Herrero",
"phoneNumber": "(787) 123-4567",
"email": "valher@gmail.com",
"message": "",
"total": 5.00,
"tax": 1.00,
"subtotal": 2.00,
"fee": 0.00,
"netAmount": 5.00,
"totalRefundAmount": 5.00,
"metadata1": "metadata1 test",
"metadata2": "metadata1 test",
"items": [
{
"name": "Nombre de arreglo",
"description": "Prueba de items",
"quantity": 3,
"price": 2.00,
"tax": 1.00,
"metadata": "prueba metadata"
}
]
}
]
}
```
--------------------------------
### Find Payment Request
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/README.md
Use this cURL command to send a POST request to find the status of a payment. Ensure you replace '' with your actual token.
```bash
curl --location --request POST 'https://payments.athmovil.com/api/business-transaction/ecommerce/business/findPayment' \
--header 'Host: ozm9fx7yw5.execute-api.us-east-1.amazonaws.com' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data-raw '{
"ecommerceId": "177a50fd-39fb-11ed-8b3d-230262020527",
"publicToken": "a66ce73d04f2087615f6320b724defc5b4eedc55"
}'
```
--------------------------------
### InitialPaymentResponse
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/types.md
The response received from the initial `/payment` endpoint after a customer initiates a payment. It indicates the status of the payment creation and provides transaction details upon success.
```APIDOC
## InitialPaymentResponse
### Description
Response from the initial `/payment` endpoint when customer clicks the pay button.
### Fields
- **status** ("success" | "error") - Indicates success or failure of payment creation.
- **data.ecommerceId** (string) - Unique transaction ID for subsequent queries and operations. UUID format.
- **data.auth_token** (string) - JWT token for authenticating subsequent requests related to this transaction. Used internally by the client library.
- **message** (string) - Error message if status is "error".
- **errorcode** (string) - Error code if status is "error".
```
--------------------------------
### Get Transaction Report
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/api-reference/server-api.md
Retrieves a report of all transactions within a specified date range. Requires business public and private tokens, and valid from and to dates.
```APIDOC
## GET /transactionReport
### Description
Retrieve all transactions for a date range. Requires business public and private tokens, and valid from and to dates. The date range cannot exceed the maximum allowed days.
### Method
GET
### Endpoint
/transactionReport
### Parameters
#### Query Parameters
- **publicToken** (string) - Required - Business public token
- **privateToken** (string) - Required - Business private token
- **fromDate** (string) - Required - Start date `YYYY-MM-DD HH:mm:ss` (cannot be future)
- **toDate** (string) - Required - End date `YYYY-MM-DD HH:mm:ss` (must be after fromDate, cannot be future)
### Response
#### Success Response (200)
- **status** (string) - Indicates if the report generation was successful ('success' or 'error').
- **data** (PaymentData[]) - Array of `PaymentData` objects sorted chronologically. May be empty if no transactions are found.
- **message** (string) - A message describing the result of the operation.
- **errorcode** (string) - An error code if the status is 'error'.
#### Response Example
```json
{
"status": "success",
"data": [
{
"transactionId": "txn_12345",
"amount": 50.00,
"status": "completed",
"timestamp": "2023-10-27T10:00:00Z"
}
]
}
```
### Status Codes
- **200** - Report generated (may be empty)
- **400** - Invalid date format
- **403** - Invalid tokens
- **422** - Date range exceeds maximum days
- **500** - Internal server error
```
--------------------------------
### Callback Functions
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/api-reference/athm-checkout.md
Implement these global asynchronous functions to handle the outcomes of the ATH Móvil payment process: successful authorization, cancellation, or expiration.
```APIDOC
## Callback Functions
### authorizationATHM()
- **Description**: Called when customer successfully authorizes payment in ATH Móvil app.
- **Triggered When**: Customer confirms payment in ATH Móvil app and payment processes successfully.
```javascript
async function authorizationATHM() {
const responseAuth = await authorization();
// Handle completion
// responseAuth contains transaction details
}
```
### cancelATHM()
- **Description**: Called when customer cancels the payment or closes the modal before completing payment.
- **Triggered When**: User closes modal, cancels payment, or payment is cancelled by merchant.
```javascript
async function cancelATHM() {
const responseCancel = await findPaymentATHM();
// Handle cancellation
// responseCancel will have ecommerceStatus = "CANCEL"
}
```
### expiredATHM()
- **Description**: Called when payment request timeout is reached without customer authorization.
- **Triggered When**: Timeout duration (from `timeout` property) is exceeded without customer authorizing in ATH Móvil app.
```javascript
async function expiredATHM() {
const responseExpired = await findPaymentATHM();
// Handle timeout
// Notify customer to try again
}
```
```
--------------------------------
### Retrieve Transaction Authorization Details
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/_autodocs/endpoints.md
Call this function within the authorizationATHM callback to get the final details of a completed transaction. Ensure the response status is 'success' before processing.
```javascript
async function authorizationATHM() {
try {
const response = await authorization();
if (response.status === 'success') {
console.log('Transaction completed:', response.data);
// Update order status in your system
// response.data contains referenceNumber, ecommerceId, etc.
} else {
console.error('Authorization failed:', response.message);
}
} catch (error) {
console.error('Error retrieving authorization:', error);
}
}
```
--------------------------------
### Include ATH Móvil Javascript Library
Source: https://github.com/evertec/athmovil-javascript-api/blob/master/README.md
Include the ATH Móvil base Javascript library and set your public token. This is required to initialize the payment button functionality on your e-commerce platform.
```javascript
```