├── README.md └── paymentux.png /README.md: -------------------------------------------------------------------------------- 1 | # ATH Móvil Payment Button - Javascript Integration and Services 2 | # Change Log 3 | 4 | 5 | |Date|Changes|Comments| 6 | | - | - | - | 7 | |08/17/2023|Initial version 1.0| 8 | | 07/17/2024 | Version 1.2 | General information related to ATH Business & ATH Móvil with instructions on how to open an account. | 9 | | 10/30/2024 | Version 1.2.1 | General information related to the Javascript configuration. | 10 | | 1/16/2025 | Version 1.2.2 | Updated headers for Refund service. | 11 | | 2/27/2025 | Version 1.2.3 | WooCommerce plug in now available. | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | # **Table of Contents** 37 | [Introduction 3****](#_toc143170424)** 38 | 39 | [**Prerequisites 3****](#_toc143170425) 40 | 41 | [**Support 4****](#_toc143170426) 42 | 43 | [**Customer Experience 4****](#_toc143170427) 44 | 45 | [**Installation 5****](#_toc143170428) 46 | 47 | [**Usage 8****](#_toc143170429) 48 | 49 | [**Callback Functions 11****](#_toc143170430) 50 | 51 | [**Find Payment Service 14****](#_toc143170431) 52 | 53 | [**Transaction Expired or Canceled Response: Status CANCEL 17****](#_toc143170432) 54 | 55 | [**Refund Payment 17****](#_toc143170433) 56 | 57 | [**Cancel Payment 19****](#_toc143170434) 58 | 59 | [**Error Messages 20****](#_toc143170435) 60 | 61 | [**User Flow 27****](#_toc143170436) 62 | 63 | [**Legal 28****](#_toc143170437) 64 | 65 | [**Reporting 28****](#_toc143170438) 66 | 67 | [**Other information 28****](#_toc143170439) 68 | 69 | # Introduction 70 | 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. 71 | 72 | The API called for this JavaScript code is build based on JWT protocol to securely authenticate the communication between our services. 73 | 74 | New plug in now available for WooCommerce: https://wordpress.org/plugins/ath-movil-pay-button-payment-gateway 75 | 76 | Disclaimer: The Payment Button ATH Móvil is not compatible with any major Ecommerce platform. This includes Shopify, Wix, or Stripe. 77 | 78 | 79 | Disclaimer: We currently **do not** have a **Testing environment**. You need to have an active ATH Business account and a active ATH Móvil account. 80 | 81 | ## Prerequisites 82 | Before using the ATH Móvil’s payment you need to have: 83 | 84 | ### ATH Business 85 | 86 | 1\. An active ATH Business account. 87 | 88 | 2\. A card registered in your ATH Business profile. 89 | 90 | 3\. The public and private key assigned to your business. 91 | 92 | For instructions on how to open a ATH Business account please refer to: [ATHB flyer eng letter 1.pdf](https://github.com/user-attachments/files/16267504/ATHB.flyer.eng.letter.1.pdf) 93 | 94 | For more information related to ATH Business and how it works please refer to:[ATH BUSINESS_Apr2024.pptx](https://github.com/user-attachments/files/16267585/ATH.BUSINESS_Apr2024.pptx) 95 | 96 | ### ATH Móvil 97 | 98 | To complete the payment for testing purposes you need to have: 99 | 100 | 1\. An active ATH Móvil account. 101 | 102 | 2\. A card registered in your ATH Móvil profile. It can not be the same card that is registered in ATH Business. 103 | 104 | For more information related to ATH Móvil and how it works please refer to:[ATH Móvil_Apr2024.pptx](https://github.com/user-attachments/files/16267592/ATH.Movil_Apr2024.pptx) 105 | 106 | 107 | To start working with the Javascript for ATH Móvils Payment Button with all its services, it is mandatory to have a Public Token per each business. This Public Token is found in the settings section of the ATH Business app and is assigned one unique token per ATH Business account. 108 | 109 | Additionally have the link for athmovil\_base.js to add it in your ecommerce platform with a tag. 110 | 111 | Production link: https://payments.athmovil.com/api/js/athmovil_base.js 112 | 113 | ```javascript 114 | 117 | 118 | ``` 119 | ATH Business Settings: 120 | 121 | image 122 | 123 | image 124 | 125 | 126 | ## Support 127 | If you need help signing up, adding a card or have any other question please refer to https://ath.business.com/preguntas. For technical support please complete the following form: https://ath.business/botondepago. 128 | 129 | ## Customer Experience 130 | The new version of the payment button will introduce more security and synchronization with both the merchant and the customer. Here you can see a brief diagram on the high-level flow of the transaction: 131 | 132 | image 133 | 134 | ## Installation 135 | From your ecommerce website identify the checkout page where you will display the payment button, for example: "my\_cart.html". 136 | 137 | Next add in your tag two scripts using 142 | ``` 143 | The second script should have a JSON object called "ATHM\_Checkout" where you should put your public token as the value for the property publicToken from ATHM\_Checkout object. 144 | 145 | Also, this second script should have three callback functions: 146 | 147 | - **authorizationATHM()** 148 | - **cancelATHM()** 149 | - **expiredATHM()** 150 | 151 | Finally, you should add in your body html a
tag with value "ATHMovil\_Checkout\_Button\_payment" in **id** property. 152 | 153 | *Example:* 154 | ```html 155 | 156 |
157 | 158 | 196 | 197 | ``` 198 | **Detail:** 199 | 200 | | **Variable** | **Data type** | **Required** | **Values** | **Description** | 201 | | --- | --- | --- | --- | --- | 202 | | env | String | YES | Production | Determines the environment to be used for the payment. | 203 | | publicToken | String | YES | Business account public token | Determines the business account that the payment will be sent to. | 204 | | timeout | Number | No | Number between 120 and 600. | Time limit before the service responds with timeout error. Default value is set to 600 seconds (10 mins). | 205 | | 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. | 206 | | 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. | 207 | | total | Number | Yes | From 1.00 to 1500.00 | Total amount to be paid by the end user. | 208 | | tax | Number | No || Optional variable to display the payment tax (if applicable). | 209 | | subtotal | Number | No || Optional variable to display the payment tax (if applicable). | 210 | | metadata1 | String | Yes || variable that can be filled with additional transaction information. For example store ID, location,etc. Max length 40 characters.| 211 | | metadata2 | String | Yes || variable that can be filled with additional transaction information. For example store ID, location,etc. Max length 40 characters. | 212 | | 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._ | 213 | | phoneNumber | Number | Yes || The phone number registered to the ATH Móvil account where the payment is going to be sent to. | 214 | ## Usage 215 | The correct implementation of div and scripts, should show the payment button like this example: 216 | 217 | image 218 | 219 | After clicking the Javascript consumes the first service "/payment", this service could response a success or an error status. 220 | 221 | If you receive a success status, you will also get a ecommerceId and auth\_token in the data response property and open a modal that shows you a message for waiting. 222 | 223 | ```javascript 224 | { 225 | "status": "success", 226 | "data": { 227 | "ecommerceId": "ad42df37-f989-11ed-8935-cd14e3558bc7", 228 | "auth_token": "eyJraWQiOiJNeUtVRXZvb2NSMWptbnZocHZXVEI0WmZvcU1wbEx6TWF5VzdjUWd1ck5FIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiI0MjdmOTZiMTExMmYyZGZlNTk4NjM0YWVkNmYyOTA4NmJmNWU5OTdlYjYyYTVjMDJlOTI0YTdmNTIzZDI3ZDliMzI2OGE1N2RmYWQ4ZWE3NGY1M2JhNWQzMjMyNTRkYTEiLCJmaUlkIjoiIiwibmJmIjoxNjg0ODYwNTIzLCJhenAiOltdLCJwZXJtaXNzaW9ucyI6WyJjdXN0b21lci5idXNpbmVzcy5lY29tbWVyY2UuYXV0aG9yaXphdGlvbjp3cml0ZSJdLCJpc3MiOiJQcm9jZXNzIFBheW1lbnQiLCJzY29wZXMiOlsiY3VzdG9tZXIuYnVzaW5lc3MuZWNvbW1lcmNlLmF1dGhvcml6YXRpb246d3JpdGUiXSwiZXhwIjoxNjg0ODYxNDIzLCJpYXQiOjE2ODQ4NjA1MjN9.HFPQncPDvIIqU4DeORiirntetxoU-KaRLWBK_bIAqJdR2cOWyhTTjVhVtbnCMN6qjsWB3knhp9N0aaVXPOi9DhYoWRlGVWLhSByp4K7c1fJwKFLhJoasQCew8SlXwQlalbYHt1F5s1hQgGmStGATIwnXRrE-4doBKpNedQn9CKo3qX08QGk78eAPnejzJKMlYOr__kFDR1c-L7P2btOvlx5vYDXhqmq_gljqp8f5a28pBFVh6DMx12IUu_FiQrI4ofinjiij3CWfXOVcqzBbE0UJudlS43Jb7JlZPflDrD6TM3PR4a8_KtM89Solm-r4__aIw02Gqf5ROsan_YT7FA" 229 | } 230 | } 231 | ``` 232 | image 233 | 234 | 235 | Immediately the modal should open the phoneNumberATHM.html screen, here the customer has to enter the phone number that will receive the transaction and press continue. This screen consumes “/updatePhoneNumber” service, then closes the phoneNumberATHM.html and opens the waitingPaymentATHM.html screen. Simultanously the customer will receive a push notification on the ATHMovil app stating that a payment is waiting to be completed. 236 | 237 | image 238 | 239 | 240 | image 241 | 242 | 243 | After receiving the push notification, the customer must open the ATHMovil app and confirm the transaction. After the customer confirms the transaction the Javascript will then consume the ”authorization” service automatically and should close waitingPaymentATHM.html with a success message on the main screen where you have a payment button. 244 | 245 | image 246 | 247 | 248 | ## Callback functions 249 | 250 | `authorizationATHM`. This function returns a JSON object with the details of the transaction after it has been completed and processed. 251 | 252 | ```json 253 | { 254 | "status": "success", 255 | "data": { 256 | "ecommerceStatus": "COMPLETED", 257 | "ecommerceId": "870633c9-f994-11ed-8935-c155d7fc6afe", 258 | "referenceNumber": "215070440-8a36d420882a293a018849cae9f500a8", 259 | "businessCustomerId": "402894d56e713892016e7f2963de0010", 260 | "transactionDate": "2023-05-23 14:06:54", 261 | "dailyTransactionId": "0001", 262 | "businessName": "I Love Puerto Rico", 263 | "businessPath": "ilovepr", 264 | "industry": "COMPUTERS", 265 | "subTotal": 1.33, 266 | "tax": 1.00, 267 | "total": 2.33, 268 | "fee": 0.06, 269 | "netAmount": 2.28, 270 | "totalRefundedAmount": 0, 271 | "metadata1": "Metadata 1", 272 | "metadata2": "Metada 2", 273 | "items": [ 274 | { 275 | "name": "Diego MO", 276 | "description": "Diego", 277 | "quantity": 1, 278 | "price": 1.33, 279 | "tax": 1, 280 | "metadata": "ATH Movil es lo mejor", 281 | "formattedPrice": "", 282 | "sku": "" 283 | } 284 | ], 285 | "isNonProfit": false 286 | } 287 | } 288 | ``` 289 | 290 | `cancelATHM`. This function consumes “/findPayment” service to retrieve the status of the transaction in the event that it gets cancelled and returns a JSON object with the details of the transaction. 291 | 292 | ```json 293 | { 294 | "status": "success", 295 | "data": { 296 | "ecommerceStatus": "CANCEL", 297 | "ecommerceId": "a5f8143a-f997-11ed-8935-a9b922a1efbc", 298 | "referenceNumber": "", 299 | "businessCustomerId": "402894d56e713892016e7f2963de0010", 300 | "transactionDate": "", 301 | "dailyTransactionId": "", 302 | "businessName": "I Love Puerto Rico", 303 | "businessPath": "ilovepr", 304 | "industry": "COMPUTERS", 305 | "subTotal": 1.33, 306 | "tax": 1.00, 307 | "total": 2.33, 308 | "fee": 0.00, 309 | "netAmount": 0, 310 | "totalRefundedAmount": 0, 311 | "metadata1": "Metadata 1", 312 | "metadata2": "Metada 2", 313 | "items": [ 314 | { 315 | "name": "Diego MO", 316 | "description": "Diego", 317 | "quantity": 1, 318 | "price": 1.33, 319 | "tax": 1, 320 | "metadata": "ATH Movil es lo mejor", 321 | "formattedPrice": "", 322 | "sku": "" 323 | } 324 | ], 325 | "isNonProfit": false 326 | } 327 | } 328 | ``` 329 | 330 | `expiredATHM`. This function consumes “/findPayment” service to retrieve the status of the transaction in the event that it expires and returns a JSON object with the details of the transaction. 331 | 332 | ```json 333 | { 334 | "status": "success", 335 | "data": { 336 | "ecommerceStatus": "CANCEL", 337 | "ecommerceId": "a5f8143a-f997-11ed-8935-a9b922a1efbc", 338 | "referenceNumber": "", 339 | "businessCustomerId": "402894d56e713892016e7f2963de0010", 340 | "transactionDate": "", 341 | "dailyTransactionId": "", 342 | "businessName": "I Love Puerto Rico", 343 | "businessPath": "ilovepr", 344 | "industry": "COMPUTERS", 345 | "subTotal": 1.33, 346 | "tax": 1.00, 347 | "total": 2.33, 348 | "fee": 0.00, 349 | "netAmount": 0, 350 | "totalRefundedAmount": 0, 351 | "metadata1": "Metadata 1", 352 | "metadata2": "Metada 2", 353 | "items": [ 354 | { 355 | "name": "Diego MO", 356 | "description": "Diego", 357 | "quantity": 1, 358 | "price": 1.33, 359 | "tax": 1, 360 | "metadata": "ATH Movil es lo mejor", 361 | "formattedPrice": "", 362 | "sku": "" 363 | } 364 | ], 365 | "isNonProfit": false 366 | } 367 | } 368 | ``` 369 | 370 | ## Find Payment 371 | This service can be used to find the status of a transaction. This service “/business/findPayment” requires a payload with two mandatory attributes "ecommerceId" and “publicToken”, which will be validated by the same service. 372 | 373 | 374 | `**Endpoint:**` https://payments.athmovil.com/api/business-transaction/ecommerce/business/findPayment 375 | 376 | `**Headers:**` Content-type – application/json 377 | 378 | **Request** 379 | 380 | - `**ecommerceId**`: This ID represent the ticket of the transaction to be paid with the information provided in the request. 381 | - `**publicToken**`: Determines the business account that the payment will be sent to. 382 | 383 | ```bash 384 | curl --location --request POST 'https://payments.athmovil.com/api/business-transaction/ecommerce/business/findPayment' \ 385 | --header 'Host: ozm9fx7yw5.execute-api.us-east-1.amazonaws.com' \ 386 | --header 'Accept: application/json' \ 387 | --header 'Authorization: Bearer ' \ 388 | --header 'Content-Type: application/json' \ 389 | --data-raw '{ 390 | "ecommerceId": "177a50fd-39fb-11ed-8b3d-230262020527", 391 | "publicToken": "a66ce73d04f2087615f6320b724defc5b4eedc55" 392 | }' 393 | ``` 394 | 395 | 396 | **Response** 397 | 398 | - `**status**`: Confirm status of the service response. 399 | - `**ecommerceStatus**`: represents the status of the ecommerce transaction. 400 | - `**transactionDate**`: Authorization date 401 | - `**referenceNumber**`: Unique transaction identifier 402 | - `**dailyTransactionID**`: ID count for the transaction in the day. 403 | - `**businessName**`: Buiness Name for the ATH Business account 404 | - `**businessPath**`: Business Path for the ATH Business account 405 | - `**industry**`: Industry of the business 406 | - `**total**`: Total amount of the transaction 407 | - `**tax**`: Tax to be charged in the transaction. 408 | - `**subtotal**`: Subtotal amount of the transaction. 409 | - `**fee**`: Fee to be charged in the transaction. 410 | - `**netAmount**`: Net amount of the transaction 411 | - `**totalRefundedAmount**`: amount to be refunded from the original transaction. 412 | - `**metadata1**`: variable that can be filled with additional transaction information. For example store ID, location,etc. Max length 40 characters. 413 | - `**metadata2**`: variable that can be filled with additional transaction information. For example store ID, location,etc. Max length 40 characters. 414 | - `**items**`: Items paid in the transaction. 415 | 416 | 417 | 418 | Completed transaction (/Payment +/Confirmed & /Authorize) Response: Status `COMPLETED` 419 | 420 | 421 | 422 | ```json 423 | { 424 | "status": "success", 425 | "data": { 426 | "ecommerceStatus": "COMPLETED", 427 | "ecommerceId": "730e2c49-9387-11ed-8f43-c31784ccfc6c", 428 | "referenceNumber": "215070443-402894c185ab1be40185acfe61c2000b", 429 | "businessCustomerId": "402894d56e713892016e7f2963de0010", 430 | "transactionDate": "2023-01-13 16:17:06", 431 | "dailyTransactionId": "0006", 432 | "businessName": "I Love Puerto Rico", 433 | "businessPath": "ilovepr", 434 | "industry": "ENTERTAINMENT", 435 | "subTotal": 0, 436 | "tax": 0.00, 437 | "total": 1, 438 | "fee": 0.6000000238418579, 439 | "netAmount": 0.40, 440 | "totalRefundedAmount": 0, 441 | "metadata1": "Metadata 1", 442 | "metadata2": "Metada 2", 443 | "items": [ 444 | { 445 | "name": "Diego MO", 446 | "description": "Diego", 447 | "quantity": 1, 448 | "price": 10, 449 | "tax": 0, 450 | "metadata": "ATH Movil es lo mejor" 451 | } 452 | ], 453 | "isNonProfit": false 454 | } 455 | } 456 | 457 | ``` 458 | 459 | 460 | 461 | Transaction Pending to be confirmed by the ATH Móvil customer (/payment) Response: Status `OPEN` 462 | ```json 463 | { 464 | 465 | "status": "success", 466 | 467 | "data": { 468 | 469 | "ecommerceStatus": "OPEN", 470 | 471 | "ecommerceId": "39906664-e44e-11ed-b127-a519df48811e", 472 | 473 | "referenceNumber": "", 474 | 475 | "businessCustomerId": "402894d56e713892016e7f2963de0010", 476 | 477 | "transactionDate": "", 478 | 479 | "dailyTransactionId": "", 480 | 481 | "businessName": "I Love Puerto Rico", 482 | 483 | "businessPath": "ilovepr", 484 | 485 | "industry": "COMPUTERS", 486 | 487 | "subTotal": 1.33, 488 | 489 | "tax": 1.00, 490 | 491 | "total": 2.33, 492 | 493 | "fee": 0.00, 494 | 495 | "netAmount": 0, 496 | 497 | "totalRefundedAmount": 0, 498 | 499 | "metadata1": "Metadata 1", 500 | 501 | "metadata2": "Metada 2", 502 | 503 | "items": [ 504 | 505 | { 506 | 507 | "name": "Diego MO", 508 | 509 | "description": "Diego", 510 | 511 | "quantity": 1, 512 | 513 | "price": 1.33, 514 | 515 | "tax": 1, 516 | 517 | "metadata": "ATH Movil es lo mejor", 518 | 519 | "formattedPrice": "", 520 | 521 | "sku": "" 522 | 523 | } 524 | 525 | ], 526 | 527 | "isNonProfit": false 528 | 529 | } 530 | ``` 531 | 532 | 533 | Transaction confirmed by the ATH Móvil customer but pending to be processed by the merchant (/payment+/confirm) Response: Status `CONFIRM` 534 | 535 | ```json 536 | { 537 | "status": "success", 538 | "data": { 539 | "ecommerceStatus": "CONFIRM", 540 | "ecommerceId": "39906664-e44e-11ed-b127-a519df48811e", 541 | "referenceNumber": "", 542 | "businessCustomerId": "402894d56e713892016e7f2963de0010", 543 | "transactionDate": "", 544 | "dailyTransactionId": "", 545 | "businessName": "I Love Puerto Rico", 546 | "businessPath": "ilovepr", 547 | "industry": "COMPUTERS", 548 | "subTotal": 1.33, 549 | "tax": 1.00, 550 | "total": 2.33, 551 | "fee": 0.00, 552 | "netAmount": 0, 553 | "totalRefundedAmount": 0, 554 | "metadata1": "Metadata 1", 555 | "metadata2": "Metada 2", 556 | "items": [ 557 | { 558 | "name": "Diego MO", 559 | "description": "Diego", 560 | "quantity": 1, 561 | "price": 1.33, 562 | "tax": 1, 563 | "metadata": "ATH Movil es lo mejor", 564 | "formattedPrice": "", 565 | "sku": "" 566 | } 567 | ], 568 | "isNonProfit": false 569 | } 570 | } 571 | ``` 572 | 573 | 574 | Transaction Expired or Canceled Response: Status`CANCEL` 575 | 576 | ```json 577 | { 578 | "status": "success", 579 | "data": { 580 | "ecommerceStatus": "CANCEL", 581 | "ecommerceId": "29bc7846-e44f-11ed-b127-839ef0792c17", 582 | "referenceNumber": "", 583 | "businessCustomerId": "402894d56e713892016e7f2963de0010", 584 | "transactionDate": "", 585 | "dailyTransactionId": "", 586 | "businessName": "I Love Puerto Rico", 587 | "businessPath": "ilovepr", 588 | "industry": "COMPUTERS", 589 | "subTotal": 1.33, 590 | "tax": 1.00, 591 | "total": 2.33, 592 | "fee": 0.00, 593 | "netAmount": 0, 594 | "totalRefundedAmount": 0, 595 | "metadata1": "Metadata 1", 596 | "metadata2": "Metada 2", 597 | "items": [ 598 | { 599 | "name": "Diego MO", 600 | "description": "Diego", 601 | "quantity": 1, 602 | "price": 1.33, 603 | "tax": 1, 604 | "metadata": "ATH Movil es lo mejor", 605 | "formattedPrice": "", 606 | "sku": "" 607 | } 608 | ], 609 | "isNonProfit": false 610 | } 611 | } 612 | ``` 613 | ## Refund Payment 614 | This is a Web Service that allows to refund a completed ecommerce transaction. 615 | 616 | - Business Transaction 617 | - Endpoint: “https://payments.athmovil.com/api/business-transaction/ecommerce/refund” 618 | - Object Request: {"amount": 0, "message": "string", "privateToken": "string", "publicToken": "string", "referenceNumber": "string"} 619 | - Type: REST 620 | - Format: application/json 621 | - Method: POST 622 | - Header: 623 | - Accept: application/json 624 | - Content-Type: application/json 625 | - Host 626 | 627 | **Request:** 628 | ```json 629 | { 630 | "publicToken": "hdb932832klnasKJGDW90291", 631 | "privateToken": "JHEFEWP2048FNDFLKJWB2", 632 | "referenceNumber": "fdew98ffw9fbfewkjb", // transactionId 633 | "amount": "1.00", 634 | "message": "MSG Test" // Optional 635 | } 636 | 637 | ``` 638 | 639 | **Response** 640 | ```json 641 | { 642 | "status": "success", 643 | "data": { 644 | "refund": { 645 | "transactionType": "REFUND", 646 | "status": "COMPLETED", 647 | "refundedAmount": 1.00, 648 | "date": "123412341234", // timestamp 649 | "referenceNumber": "402894d56b240610016b2e6c78a6003a", // Refund transactionId 650 | "dailyTransactionID": "0107", 651 | "name": "Valeria Herrero", 652 | "phoneNumber": "(787) 123-4567", 653 | "email": "valher@gmail.com" 654 | }, 655 | "originalTransaction": { 656 | "transactionType": "PAYMENT", 657 | "status": "COMPLETED", 658 | "date": "123412341234", // timestamp 659 | "referenceNumber": "402894d56b240610016b2e6c78a6003a", // Original Payment transactionId 660 | "dailyTransactionID": "0106", 661 | "name": "Valeria Herrero", 662 | "phoneNumber": "(787) 123-4567", 663 | "email": "valher@gmail.com", 664 | "message": "", 665 | "total": 1.00, 666 | "tax": 0.00, 667 | "subtotal": 0.00, 668 | "fee": 0.00, 669 | "netAmount": 0.00, 670 | "totalRefundedAmount": 1.00, 671 | "metadata1": "metadata1 test", 672 | "metadata2": "metadata2 test", 673 | "items": [] 674 | } 675 | } 676 | } 677 | 678 | ``` 679 | 680 | ## Cancel Payment 681 | 682 | This is a Web Service to cancel the ecommerce transaction. 683 | 684 | - Business Transaction 685 | - Endpoint: https://payments.athmovil.com/api/business-transaction/ecommerce/business/cancel” 686 | - Object Request: {“ecommerceId”, “publicToken “ 687 | - Type: REST 688 | - Format: application/json 689 | - Method: POST 690 | - Header: 691 | - Accept: application/json 692 | - Content-Type: application/json 693 | - Host 694 | 695 | **Request:** 696 | 697 | ```json 698 | { 699 | "ecommerceId": "177a50fd-39fb-11ed-8b3d-230262020527", 700 | "publicToken": "3adc528b182e50b41acff658136bd974c89604c3" 701 | } 702 | ``` 703 | 704 | **Response:** 705 | 706 | ```json 707 | { 708 | "status": "success", 709 | "data": "Payment Cancelled." 710 | } 711 | ``` 712 | 713 | ## Error Messages 714 | 715 | The error messages for the PB will follow a standard response structure of status, message, error code and data. Below are some examples of the responses and a list of all available error scenarios. 716 | 717 | - Request without a token authentication. 718 | 719 | 720 | ```json 721 | 722 | { 723 | "status": "error", 724 | "message": "No authorization header present.", 725 | "errorcode": "token.invalid.header", 726 | "data": null 727 | } 728 | ``` 729 | 730 | - Request with an expired token. 731 | 732 | ```json 733 | { 734 | "status": "error", 735 | "message": "The Token has expired on Fri Oct 28 15:21:00 AST 2022.", 736 | "errorcode": "token.expired", 737 | "data": null 738 | } 739 | ``` 740 | - When the Object request it’s empty. 741 | ```json 742 | { 743 | 744 | "status": "error", 745 | 746 | "message": "Required request body is missing", 747 | 748 | "errorcode": 'BTRA\_0006', 749 | 750 | "data": null 751 | 752 | } 753 | ``` 754 | ## Errors on the modal 755 | 756 | If the user closes the phonePaymentATHM.html or waitingPaymentATHM.html screen the modal will display an error message on the main payment button screen. 757 | 758 | image 759 | 760 | 761 | If you try to make another payment from another website or mobile app using ATHM's payment button (with the same ATH card as the business), you should see a error message on the main payment button screen. 762 | 763 | image 764 | 765 | 766 | When you press ATHM's payment button and the isn’t any problem, this transaction is created with an expiration time (timeout property in ATHM\_Checkout object). 767 | 768 | If the customer takes too much time in confirming the transaction from the ATH Móvil’s app then the user will see this error message on the main payment button screen. 769 | 770 | image 771 | 772 | 773 | **Additional Error Codes**: 774 | 775 | |Error code|Description| 776 | | :- | :- | 777 | |error.code.es.BTRA\_9998|=Communication Error| 778 | |error.code.en.BTRA\_9998|=Communication Error| 779 | |error.code.es.BTRA\_9999|=Internal Error| 780 | |error.code.en.BTRA\_9999|=Internal Error| 781 | |error.code.es.BTRA\_0401|=Invalid authorization token| 782 | |error.code.en.BTRA\_0401|=Invalid authorization token| 783 | |error.code.es.BTRA\_0402|=Authorization token expired| 784 | |error.code.en.BTRA\_0402|=Authorization token expired| 785 | |error.code.es.BTRA\_0403|=Invalid authorization token| 786 | |error.code.en.BTRA\_0403|=Invalid authorization token| 787 | |error.code.es.BTRA\_0001|=El monto de la transferencia está por debajo del mínimo permitido| 788 | |error.code.en.BTRA\_0001|=The transfer amount is under Minimum allowed| 789 | |error.code.es.BTRA\_0002|=Estatus del cliente es Pendiente Recuperar Verificación de Acceso| 790 | |error.code.en.BTRA\_0002|=Customer status is Pending Regain Access Verification| 791 | |error.code.es.BTRA\_0003|=Número de tarjeta del cliente es el mismo que el del negocio| 792 | |error.code.en.BTRA\_0003|=Card number from the customer is the same than the business| 793 | |error.code.es.BTRA\_0004|=El monto está por encima de los límites| 794 | |error.code.en.BTRA\_0004|=Amount is Over the limits| 795 | |error.code.es.BTRA\_0005|=Transacción fallida. Estatus de error| 796 | |error.code.en.BTRA\_0005|=Transaction failed. Status error| 797 | |error.code.es.BTRA\_0006|=Formato inválido| 798 | |error.code.en.BTRA\_0006|=Invalid format| 799 | |error.code.es.BTRA\_0007|=TransactionId no existe| 800 | |error.code.en.BTRA\_0007|=TransactionId does not exist| 801 | |error.code.es.BTRA\_0008|=TransactionId no pertenece al negocio| 802 | |error.code.en.BTRA\_0008|=TransactionId does not belong to the business| 803 | |error.code.es.BTRA\_0009|=El negocio no está activo| 804 | |error.code.en.BTRA\_0009|=Business is not active| 805 | |error.code.es.BTRA\_0010|=El negocio no está activo| 806 | |error.code.en.BTRA\_0010|=Business status is not Active| 807 | |error.code.es.BTRA\_0011|=Número de la tarjeta no pertenece al negocio| 808 | |error.code.en.BTRA\_0011|=Card number does not belong to the business| 809 | |error.code.es.BTRA\_0012|=Números de tarjetas origen y destino son los mismos| 810 | |error.code.en.BTRA\_0012|=Source and Target card numbers are the same| 811 | |error.code.es.BTRA\_0013|=El monto es cero| 812 | |error.code.en.BTRA\_0013|=Amount is Zero| 813 | |error.code.es.BTRA\_0014|=TransactionId no existe para el negocio actual| 814 | |error.code.en.BTRA\_0014|=TransactionId does not exist for the current business| 815 | |error.code.es.BTRA\_0015|=Communication Error| 816 | |error.code.en.BTRA\_0015|=Communication Error| 817 | |error.code.es.BTRA\_0016|=Communication Error| 818 | |error.code.en.BTRA\_0016|=Communication Error| 819 | |error.code.es.BTRA\_0017|=Invalid authorization token| 820 | |error.code.en.BTRA\_0017|=Invalid authorization token| 821 | |error.code.es.BTRA\_0018|=no debe estar vacío| 822 | |error.code.en.BTRA\_0018|=must not be blank| 823 | |error.code.es.BTRA\_0019|=no debe ser nulo| 824 | |error.code.en.BTRA\_0019|=must not be null| 825 | |error.code.es.BTRA\_0020|=valor numérico fuera de los límites (<4 dígitos>. <2 dígitos> esperados)| 826 | |error.code.en.BTRA\_0020|=numeric value out of bounds (<4 digits>.<2 digits> expected)| 827 | |error.code.es.BTRA\_0021|=TransactionType no es válido| 828 | |error.code.en.BTRA\_0021|=TransactionType is not valid| 829 | |error.code.es.BTRA\_0022|=Reporte sin transacciones| 830 | |error.code.en.BTRA\_0022|=Not record for report| 831 | |error.code.es.BTRA\_0023|=Error con la fecha Desde| 832 | |error.code.en.BTRA\_0023|=Error with the From date| 833 | |error.code.es.BTRA\_0024|=Error con la fecha Hasta| 834 | |error.code.en.BTRA\_0024|=Error with the To date| 835 | |error.code.es.BTRA\_0025|=La fecha Desde debe ser anterior a la fecha Hasta| 836 | |error.code.en.BTRA\_0025|=The From date must be before the To date| 837 | |error.code.es.BTRA\_0026|=La diferencia entre fechas debe ser inferior a %s días| 838 | |error.code.en.BTRA\_0026|=The difference between dates must be lower than %s days| 839 | |error.code.es.BTRA\_0027|=La organización no es una organización sin fines de lucro| 840 | |error.code.en.BTRA\_0027|=The organization is not a Non Profit organization| 841 | |error.code.es.BTRA\_0028|=es menor de 0.01| 842 | |error.code.en.BTRA\_0028|=is less than 0.01| 843 | |error.code.es.BTRA\_0029|=El parámetro requerido '%s' no está presente| 844 | |error.code.en.BTRA\_0029|=Required String parameter '%s' is not present| 845 | |error.code.es.BTRA\_0030|=El refund fallo con un estatus de error| 846 | |error.code.en.BTRA\_0030|=The refund failed with a status error| 847 | |error.code.es.BTRA\_0031|=El ecommerceId no existe| 848 | |error.code.en.BTRA\_0031|=EcommerceId does not exist| 849 | |error.code.es.BTRA\_0032|=El estatus del e-commerce no esta confirmado| 850 | |error.code.en.BTRA\_0032|=The status of the e-commerce is not confirm| 851 | |error.code.es.BTRA\_0033|=Error al crear el registro del BusinessEcommerce| 852 | |error.code.en.BTRA\_0033|=Error creating BusinessEcommerce recordb| 853 | |error.code.es.BTRA\_0034|=El BusinessEcommerce ya existe en dynamoDB| 854 | |error.code.en.BTRA\_0034|=BusinessEcommerce exists in the dynamoDB| 855 | |error.code.es.BTRA\_0035|=El estatus del registro de Transacción e-commerce no es el espereado| 856 | |error.code.en.BTRA\_0035|=The e-commerce transaction has not the expected status| 857 | |error.code.es.BTRA\_0036|=El e-commerce que tratas de confirmar, ya esta asignado a otro customer| 858 | |error.code.en.BTRA\_0036|=The e-commerce you are trying to confirm is already assigned to another customer| 859 | |error.code.es.BTRA\_0037|=No se puede confirmar una transacción con status Cancelado o Fallido| 860 | |error.code.en.BTRA\_0037|=Cannot confirm a transaction with status Canceled or Failed| 861 | |error.code.es.BTRA\_0038|=El campo metadata excede el maximo de caracteres soportado (40)| 862 | |error.code.en.BTRA\_0038|=The metadata field exceeds the maximum supported characters (40)| 863 | |error.code.es.BTRA\_0039|=Tiempo valido para ejecutar la transacción ha expirado| 864 | |error.code.en.BTRA\_0039|=Valid time to execute the transaction has expired| 865 | |error.code.es.BTRA\_0040|=El mensaje no puede superar los 50 caracteres| 866 | |error.code.en.BTRA\_0040|=The message can not exceed 50 characters| 867 | |error.code.es.BTRA\_0041|=La transaccion e-commerce ya tiene asignado un numero telefonico| 868 | |error.code.en.BTRA\_0041|=The e-commerce transaction already has a phone number assigned| 869 | |error.code.es.BTRA\_0042|=El monto de la propina está por encima de los límites| 870 | |error.code.en.BTRA\_0042|=Tip amount is over limits| 871 | |error.code.es.BTRA\_0043|=El comercio no es dueño del pago| 872 | |error.code.en.BTRA\_0043|=The business ins't owner of payment| 873 | |error.code.es.BTRA\_0044|=El monto está por encima de los límites del Institución Financiera| 874 | |error.code.en.BTRA\_0044|=Amount is Over limits of the Financial Institution| 875 | |error.code.es.BTRA\_0045|=El monto está por encima de los límites de la tarjeta| 876 | |error.code.en.BTRA\_0045|=Amount is Over the limits of the card| 877 | |error.code.es.BTRA\_0046|=No hay transacciones para el rango de fechas indicado| 878 | |error.code.en.BTRA\_0046|=There are no transactions for the indicated date range| 879 | |error.code.es.BTRA\_0047|=La fecha desde no puede ser futura| 880 | |error.code.en.BTRA\_0047|=Date from cannot be future| 881 | |error.code.es.BTRA\_0048|=La fecha hasta no puede ser futura| 882 | |error.code.en.BTRA\_0048|=Date to cannot be future| 883 | |error.code.es.BTRA\_0049|=El customerId no existe| 884 | |error.code.en.BTRA\_0049|=customerId does not exist| 885 | |error.code.es.BTRA\_0050|=La configuracion para recibir propinas esta deshabilitada para el negocio| 886 | |error.code.en.BTRA\_0050|=Tip configuration is disabled for the business| 887 | |error.code.es.BTRA\_0051|=El monto de la propina no debe exceder el valor del monto de la transaccion| 888 | |error.code.en.BTRA\_0051|=The amount of the tip must not exceed the value of the amount of the transaction| 889 | |error.code.es.BTRA\_0052|=No puede llenar ambos campos (tipAmount y percentage), solo use uno| 890 | |error.code.en.BTRA\_0052|=Cannot fill both fields (tipAmount and percentage), just fill one| 891 | |error.code.es.BTRA\_0053|=El ReferenceNumber no existe| 892 | |error.code.en.BTRA\_0053|=ReferenceNumber not found| 893 | 894 | 895 | 896 | ## User Flow 897 | 898 | image 899 | 900 | 901 | 902 | 903 | 904 | 905 | 906 | 907 | 908 | 909 | 910 | 911 | 912 | 913 | 914 | 915 | 916 | 917 | 918 | ## Services 919 | The following services can be used to search for transactions, perform refunds and request information of multiple payments received in a given time frame. 920 | 921 | ### Search 922 | * Method:` POST` 923 | * Headers: `Content-Type` - `application/json` 924 | * Endpoint: `https://www.athmovil.com/api/v4/searchTransaction` 925 | * Body Example: 926 | ```json 927 | { 928 | "publicToken": "hdb932832klnasKJGDW90291", 929 | "privateToken": "JHEFEWP2048FNDFLKJWB2", 930 | "referenceNumber": "a387643827-fdew98ffw9fbfewkjb", 931 | "dailyTransactionID": "1234", 932 | "name": "Valeria Herrero", 933 | "phoneNumber": "(787) 123-4567", 934 | "email": "valher@gmail.com", 935 | "total": "1.00", 936 | "metadata1": "metadata1 test", 937 | "metadata2": "metadata2 test" 938 | } 939 | ``` 940 | * *Only `publicToken`, `privateToken`any other field is required to search for a transaction.* 941 | * *The value of phoneNumber needs to be formatted as in the provided example.* 942 | * *To find results the provided field value must be an exact match with the field value of at least one transaction.* 943 | * *Multiple fields can be used simultaneously on the request.* 944 | 945 | * Reponse Example: 946 | ```json 947 | { 948 | "transactionType": "ECOMMERCE", 949 | "status": "COMPLETED", 950 | "date": "2019-06-06 16:12:02.0", 951 | "referenceNumber": "402894d56b240610016b2e6c78a6003a", 952 | "dailyTransactionID": 1, 953 | "name": "Valeria Herrero", 954 | "phoneNumber": "(787) 123-4567", 955 | "email": "valher@gmail.com", 956 | "message": "", 957 | "total": 1.00, 958 | "tax": 1.00, 959 | "subtotal": 1.00, 960 | "fee": 0.06, 961 | "netAmount": 0.94, 962 | "totalRefundedAmount": 0.00, 963 | "metadata1": "metadata1 test", 964 | "metadata2": "metadata2 test", 965 | "items": [ 966 | { 967 | "name": "First Item", 968 | "description": "This is a description.", 969 | "quantity": 1, 970 | "price": 1.00, 971 | "tax": 1.00, 972 | "metadata": "metadata test" 973 | }, 974 | { 975 | "name": "Second Item", 976 | "description": "This is another description.", 977 | "quantity": 1, 978 | "price": 1.00, 979 | "tax": 1.00, 980 | "metadata":"metadata test" 981 | } 982 | ] 983 | } 984 | ``` 985 | * *If more than one transaction matches the provided fields all matching payments will be sent on the response as a list.* 986 | 987 | ---- 988 | 989 | ### Refund 990 | * Method:` POST` 991 | * Headers: `Content-Type` - `application/json` 992 | * Endpoint: `https://www.athmovil.com/api/v4/refundTransaction` 993 | * Body Example: 994 | ```json 995 | { 996 | "publicToken": "hdb932832klnasKJGDW90291", 997 | "privateToken": "JHEFEWP2048FNDFLKJWB2", 998 | "referenceNumber": "fdew98ffw9fbfewkjb" 999 | "amount":"1.00" 1000 | } 1001 | ``` 1002 | 1003 | ---- 1004 | 1005 | ### Transaction Report 1006 | * Method:` GET` 1007 | * Headers: `Content-Type` - `application/json` 1008 | * Endpoint: `https://www.athmovil.com/transactions/v4/transactionReport` 1009 | * Body Example: 1010 | ```json 1011 | { 1012 | "publicToken": "hdb932832klnasKJGDW90291", 1013 | "privateToken": "JHEFEWP2048FNDFLKJWB2", 1014 | "fromDate": "2019-01-01 16:12:02", 1015 | "toDate":"2019-06-06 16:12:02" 1016 | } 1017 | ``` 1018 | * Response Example: 1019 | ```json 1020 | [ 1021 | { 1022 | "transactionType": "ECOMMERCE", 1023 | "status": "COMPLETED", 1024 | "date": "2021-07-08 00:36:39.0", 1025 | "referenceNumber": "402894d56b240610016b2e6c78a6003a", 1026 | "dailyTransactionID": 35, 1027 | "name": "Valeria Herrero", 1028 | "phoneNumber": "(787) 123-4567", 1029 | "email": "valher@gmail.com", 1030 | "message": "", 1031 | "total": 1.00, 1032 | "tax": 0.00, 1033 | "subtotal": 0.00, 1034 | "fee": 0.00, 1035 | "netAmount": 1.00, 1036 | "totalRefundAmount": 1.00, 1037 | "metadata1": "metadata1 test", 1038 | "metadata2": "metadata2 test", 1039 | "items": [ 1040 | { 1041 | "name": "Item", 1042 | "description": "Description", 1043 | "quantity": 1, 1044 | "price": 1.00, 1045 | "tax": 0.00, 1046 | "metadata": "Metadata" 1047 | }, 1048 | { 1049 | "name": "item", 1050 | "description": "desc", 1051 | "quantity": 1, 1052 | "price": 1.00, 1053 | "tax": 0.00, 1054 | "metadata": "Metadata" 1055 | } 1056 | ] 1057 | }, 1058 | { 1059 | "transactionType": "ECOMMERCE", 1060 | "status": "COMPLETED", 1061 | "date": "2021-07-08 00:35:43.0", 1062 | "referenceNumber": "402894d56b240610016b2e6c78a6003a ", 1063 | "dailyTransactionID": 33, 1064 | "name": "Valeria Herrero", 1065 | "phoneNumber": "(787) 123-4567", 1066 | "email": "valher@gmail.com", 1067 | "message": "", 1068 | "total": 5.00, 1069 | "tax": 1.00, 1070 | "subtotal": 2.00, 1071 | "fee": 0.00, 1072 | "netAmount": 5.00, 1073 | "totalRefundAmount": 5.00, 1074 | "metadata1": "metadata1 test", 1075 | "metadata2": "metadata1 test", 1076 | "items": [ 1077 | { 1078 | "name": "Nombre de arreglo", 1079 | "description": "Prueba de items", 1080 | "quantity": 3, 1081 | "price": 2.00, 1082 | "tax": 1.00, 1083 | "metadata": "prueba metadata" 1084 | } 1085 | ] 1086 | } 1087 | ] 1088 | ``` 1089 | ---- 1090 | ## Legal 1091 | 1092 | 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: . 1093 | 1094 | ## Reporting 1095 | 1096 | Withing the reports of ATH Business this transaction will be registered as an ECOMMERCE type transaction. Transactions performed through the “Pay a Business” functionality within the ATHM app will register as PAYMENT type transactions. 1097 | 1098 | 1099 | 1100 | 1101 | Reporting example 1102 | 1103 | image 1104 | 1105 | 1106 | 1107 | ## Other information** 1108 | 1109 | Additionally, if you only want to receive payments through the payment button, we recommend disabling the business from the list of business available in the ATH Móvil’s app. 1110 | 1111 | This way you guarantee you are receiving payments only through the payment button. 1112 | 1113 | This change can be performed within the app via the settings. 1114 | 1115 | image 1116 | 1117 | 1118 | CONFIDENTIAL INFORMATION 1119 | 1120 | COPYRIGHT © 2021 EVERTEC GROUP, LLC. ALL RIGHTS RESERVED. 1121 | 1122 | -------------------------------------------------------------------------------- /paymentux.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evertec/athmovil-javascript-api/53cc399e38bef76f43f0820b2f81775c0b4f27e8/paymentux.png --------------------------------------------------------------------------------