Timeout for Refund Payment API

ikeno · August 1, 2023, 12:20am

We have developed a VTEX module in order to offer Pix as a payment method. However, we don’t know the best way to implement refunding.

Since Pix refunding can be asynchronous, what do we should to do considering that VTEX expects a synchronous response, as described on this link: Payment Provider Protocol

In my side, after receive VTEX request, I will send the request to PSP, and it can delays some minutes in order to answer if refunding was successfully.

Saito · August 1, 2023, 8:23am

Hi there!

Just to make sure I got it right.

Both the refund and the authorization can be asynchronous.
The authorization can be asynchronous using the callback. So, the PSP can return the undefined status and later callback VTEX to inform that the transaction has been paid (and approved).
The refund can happen any time after the settle, so it´s asynchronous too.

ikeno · August 1, 2023, 5:45pm

Hi! Thanks for your answer!!!

In my point of view, authorization can be asynchronous, because we can response the “undefined” status. If VTEX receives an “undefined”, it will wait for my callback, becoming this a asynchronous process.

However, on Refund service, there isn’t the option to response an “undefined” status.
I can response 200 (“Successfully refunded”), 500 (“Refund has failed due to an internal error”) and 501 (“This payment needs to be manually refunded”).

Considering only these 3 options, I cannot see how to implement an asynchronous refunding…

Saito · August 1, 2023, 6:29pm

Ahhhh I got it wrong.

Maybe you can try to return a 501 status code with something different from code: “refund-manually” to force VTEX to retry the operation later. Then return the correct information or return “refund-manually” after 2 or 3 tries.

ikeno · August 1, 2023, 6:39pm

It might be a good idea!
I just have two questions…

Are you sure that VTEX retries the operation if I return 501?
Do you know if I can return anything on “code”, instead of “refund-manually”? I can return “refund-in-process”, for example…

Saito · August 1, 2023, 7:36pm

Sorry again.

You should try the status code 500.

Actually, I got the idea from this mockup.

github.com

vtex/openapi-schemas/blob/master/VTEX - Payment Provider Protocol.json

{
    "openapi": "3.0.0",
    "info": {
        "title": "Payment Provider Protocol",
        "description": ">ℹ️ Check the new [Payments onboarding guide](https://developers.vtex.com/docs/guides/payments-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Payments and is organized by focusing on the developer's journey.\r\n\r\nThe Payment Provider Protocol is a set of definitions to help you integrate your payment processing API into the VTEX platform, including sub-acquirers, acquirers, gateways, and custom payment services. \r\n\r\nTo achieve this, you must implement a web API (REST) following the specifications described in this documentation.\r\n\r\nTo learn more about the Payment Provider Protocol, check our [Help Center article](https://help.vtex.com/en/tutorial/payment-provider-protocol--RdsT2spdq80MMwwOeEq0m).\r\n\r\n## Endpoint requirements\r\n\r\n  * Must use a standard subdomain/domain name, not an IP address.\r\n  * Must be served over HTTPS on port 443 with TLS 1.2 support.\r\n  * Must respond in less than 5 seconds when running the tests.\r\n  * Must respond in less than 20 seconds when in production.\r\n  * Must be [PCI-DSS compliant](https://developers.vtex.com/docs/guides/payments-integration-pci-dss-compliance) or use [Secure Proxy](https://developers.vtex.com/docs/guides/payments-integration-secure-proxy) to accept branded cards like Visa, Mastercard, Amex, etc.\r\n\r\n## Testing\r\n\r\nYou can perform tests on your payment using our [VTEX - Payment Provider Test Suite](https://apps.vtex.com/vtex-payment-provider-test-suite/p).\r\n\r\n>\u2139 An extra header `X-VTEX-API-Is-TestSuite` = `true` will be sent for every test suite request, to help you easily identify it and mock any required scenarios.\r\n\r\nFor more details about testing a Payment Provider, check our [Payment Provider Homologation](https://developers.vtex.com/docs/guides/payments-integration-payment-provider-homologation) article.\r\n\r\n## Common parameters in the documentation\r\n\r\n<table>\r\n  <tr>\r\n    <td><code>{{providerApiEndpoint}}</code></td>\r\n    <td>Provider's endpoint for the implementation</td>\r\n  </tr>\r\n  <tr>\r\n    <td><code>{{X-VTEX-API-AppKey}}</code></td>\r\n    <td>The AppKey from the provider's platform configured by the merchant</td>\r\n  </tr>\r\n  <tr>\r\n    <td><code>{{X-VTEX-API-AppToken}}</code></td>\r\n    <td>The AppToken from the provider's platform configured by the merchant</td>\r\n  </tr>\r\n</table>",
        "contact": {},
        "version": "1.0"
    },
    "servers": [
        {
            "url": "https://{providerApiEndpoint}",
            "description": "VTEX server url"
        }
    ],
    "paths": {
        "/manifest": {
            "get": {
                "tags": [
                    "Payment Flow"
                ],

This file has been truncated. show original

The VTEX APIs usually retries after sometime, but I am not 100% sure that will happen with the refund. Maybe you can open a ticket with VTEX and ask them.

ikeno · August 1, 2023, 7:57pm

Another solution is process asynchronously, but respond synchronous…
When VTEX requests a refunding, I can hold it and only responds when PSP has finished all refunding process… but it could last until 1 minute…
Do you know how long is VTEX timeout?

Saito · August 2, 2023, 3:05pm

Sorry, don´t know!

ikeno · August 2, 2023, 5:53pm

Thanks anyway!!!