From d0e33d5371412235bb20de41d3e3fbd0b868202a Mon Sep 17 00:00:00 2001 From: Kwok He Chu <105217051+Kwok-he-Chu@users.noreply.github.com> Date: Wed, 15 May 2024 11:04:12 +0200 Subject: [PATCH] Updated README --- README.md | 74 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 45 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 71312cb..1aa8fc9 100644 --- a/README.md +++ b/README.md @@ -1,37 +1,50 @@ -> [!IMPORTANT] -> This mock application is currently in its alpha-release and is not supporting every request and response. This application **cannot** reject all invalid requests. -> **Always test** your own request and responses on a physical terminal beforehand. The following mock payloads were constructed using a V400M-terminal device (card inserted & pin entered, no tap). +> **[!IMPORTANT]** This mock application is currently in its alpha-release and is **not** supporting every terminal-api request and response. This application **cannot** reject all invalid requests. +> +> **Always test** your request and responses on your own physical terminal device first. -> We currently support the following [Terminal API requests/responses](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/) below. -- [PaymentRequest](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/terminal-api-reference/#comadyennexopaymentrequest) & [PaymentResponse](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/terminal-api-reference/#comadyennexopaymentresponse) -- [PaymentBusyResponse](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/terminal-api-reference/#comadyennexopaymentresponse) -- [ReversalRequest](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/terminal-api-reference/#comadyennexoreversalrequest) & [ReversalResponse](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/terminal-api-reference/#comadyennexoreversalresponse) -- [AbortRequest](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/terminal-api-reference/#comadyennexoabortrequest) -- [TransactionStatusRequest](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/terminal-api-reference/#comadyennexotransactionstatusrequest) & [TransactionStatusResponse](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/terminal-api-reference/#comadyennexotransactionstatusresponse) +# Adyen Mock Terminal-API Application +The Adyen Mock Terminal-API Application is a mock server that handles incoming requests and returns hard-coded responses. The application matches the request by looking at the `SaleToPOIRequest.MessageCategory`-field and returns the respective response, see `/public/payloads/...`-folder. -> We currently support the following [Payment Refusal Codes](https://docs.adyen.com/point-of-sale/testing-pos-payments/test-card-v1/#testing-declines) below. +This tool can be used by developers to quickly end-to-end test their application by sending having their application send requests to the Mock Terminal API Application (`http://localhost:3000/sync`) instead of the Adyen servers. You can do this by overriding the `CloudApiEndpoint` on the client (config) of your application. -| Amount ending in | Result | Error Condition | Refusal Reason | Message | -|-----------------:|--------------|-----------------|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------| -| 124 | Failure | Refusal | 210 Not enough balance | NOT_ENOUGH_BALANCE | -| 125 | Failure | Refusal | 199 Card blocked | BLOCK_CARD | -| 126 | Failure | Refusal | 228 Card expired | CARD_EXPIRED | -| 127 | Failure | Refusal | 214 Declined online | INVALID_AMOUNT | -| 128 | Failure | InvalidCard | 214 Declined online | INVALID_CARD | -| 134 | Failure | WrongPIN | 129 Invalid online PIN | INVALID_PIN - **Remark:** The terminal shows "Incorrect PIN" and then "Enter PIN". Cancel the payment on the terminal to get the failure response. | +Currently, we use the Mock Terminal-API Application to [end-to-end test](https://github.com/adyen-examples/adyen-testing-suite/tree/main/tests/in-person-payments) our in-person payments integration-examples in [**.NET**](https://github.com/adyen-examples/adyen-dotnet-online-payments/tree/main/in-person-payments-example), [**Java**](https://github.com/adyen-examples/adyen-java-spring-online-payments/tree/main/in-person-payments-example) or [**Node.js**](https://github.com/adyen-examples/adyen-node-online-payments/tree/main/in-person-payments-example). +![Demo Card Mock Terminal-API Application](public/images/demo-card-terminal-api-application.gif) +[![Run this application on Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/adyen-examples/adyen-mock-terminal-api) -# Adyen Mock Terminal-API Application -The Adyen Mock Terminal-API Application is a mock server that handles incoming requests and returns hard-coded responses. -Developers can use this to test their application quickly by sending their requests to the Mock Terminal-API Application (`localhost:3000`) instead of the Adyen servers. -This application is **not** able to reject all invalid requests. +## Supported Requests/Responses -Currently, the Mock terminal is used to [end-to-end test](https://github.com/adyen-examples/adyen-testing-suite/tree/main/tests/in-person-payments) our In-Person Payments Integration Examples in [**.NET**](https://github.com/adyen-examples/adyen-dotnet-online-payments/tree/main/in-person-payments-example), [**Java**](https://github.com/adyen-examples/adyen-java-spring-online-payments/tree/main/in-person-payments-example) or [**Node.js**](https://github.com/adyen-examples/adyen-node-online-payments/tree/main/in-person-payments-example). +### Basics +We currently support the following [Terminal API requests/responses](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/) below. -![Demo Card Mock Terminal-API Application](public/images/demo-card-terminal-api-application.gif) -[![Run this application on Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/adyen-examples/adyen-mock-terminal-api) +| Request | Response | Description | +|-------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------| +| [PaymentRequest](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/terminal-api-reference/#comadyennexopaymentrequest) | [PaymentResponse](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/terminal-api-reference/#comadyennexopaymentresponse) | A successful payment request. | +| [ReversalRequest](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/terminal-api-reference/#comadyennexoreversalrequest) | [ReversalResponse](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/terminal-api-reference/#comadyennexoreversalresponse) | A successful reversal request. | +| [TransactionStatusRequest](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/terminal-api-reference/#comadyennexotransactionstatusrequest) | [TransactionStatusResponse](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/terminal-api-reference/#comadyennexotransactionstatusresponse) | A successful transaction-status request. | +| | [PaymentBusyResponse](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/terminal-api-reference/#comadyennexopaymentresponse) | Returned when the payment terminal is waiting for pin. | +| [AbortRequest](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/terminal-api-reference/#comadyennexoabortrequest) | | Cancel an in-progress payment. **Note:** Only cancels the payment request. Parameters may slightly differ depending on the terminal. | + +### Declined payments +In general, test payments generate the result Approved. To simulate declined payments, you can change the last three digits of the `RequestedAmount` that you specify in the payment request. +- We constructed the mock payloads using a `V400M-` terminal device. +- We used the `Blue-green Adyen point-of-sale test card` (card inserted & pin entered, no tap) to retrieve the responses. + +We currently support the following [Payment Refusal Codes](https://docs.adyen.com/point-of-sale/testing-pos-payments/test-card-v1/#testing-declines), see below. + + +| Amount ending in | Result | Error Condition | Refusal Reason | Message | +|------------------:|--------------|-----------------|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------| +| **124** | Failure | Refusal | 210 Not enough balance | NOT_ENOUGH_BALANCE | +| **125** | Failure | Refusal | 199 Card blocked | BLOCK_CARD | +| **126** | Failure | Refusal | 228 Card expired | CARD_EXPIRED | +| **127** | Failure | Refusal | 214 Declined online | INVALID_AMOUNT | +| **128** | Failure | InvalidCard | 214 Declined online | INVALID_CARD | +| **134** | Failure | WrongPIN | 129 Invalid online PIN | INVALID_PIN - **Remark:** The terminal shows "Incorrect PIN" and then "Enter PIN". Cancel the payment on the terminal to get the failure response. | + +When an invalid JSON is provided, an `invalidJsonObjectNotificationResponse` is returned. ## Prerequisites @@ -92,19 +105,22 @@ We commit all our new features directly into our GitHub repository. Feel free to - Add your `Response` to `/public/payloads/**{payment}**/paymentResponse - **Note:** Every `*Request` should have a `*Response`, except for those that require some kind of state or logic (f.e: "paymentBusyResponse" triggers when a payment request is in-progress). - **Note 2:** Keep naming-conventions camelCased and prefixed with its root-folder. Example: if the root-folder is located in `/payloads/example`, we name the jsons accordingly: `exampleRequest.json`/`exampleResponse.json`. -3. In `/src/routes/defaultRoutes.js`, find the `/sync`-endpoint and add the logic needed to trigger your added request-and-response. +3. In `/src/routes/defaultRoutes.js`, find the `/sync`-endpoint and add the logic needed to map your requests-and-responses. ```js -if (req.body.SaleToPOIRequest.PaymentRequest) { +if (req.body.SaleToPOIRequest.Request) { sendOKResponse(res, "payment"); return; } + +if (req.body.SaleToPOIRequest.ExampleRequest) { + sendOKResponse(res, "example"); + return; +} ``` 3. Open a [Pull Request](https://github.com/adyen-examples/adyen-mock-terminal-api/compare) with your changes. - - ## License MIT license. For more information, see the **LICENSE** file.