For some payment methods, the result of the payment cannot be obtained immediately after the request, returning an undefined status. These methods are classified as asynchronous payments. To deal with these methods at VTEX we use callbacks, so the provider can tell our gateway later if the payment is approved or denied.

When making asynchronous payments through a payment integration, our gateway sends a URL in the callbackUrl field of the Create Payment request. This field contains the callback URL that the payment provider will have to call and deliver the final payment status to our gateway.

The callback URL now has an additional X-VTEX-signature parameter. This parameter contains a signature token to identify that the request has been generated from VTEX as a security measure. The signature token has at most 32 characters. You can check an example of callback URL with the signature token below:

In the Transactions page of the Admin, the signature token appears masked for security reasons, as in this example: X-VTEX-signature=Rj******tk.

When making the callback request, we recommend that payment providers use the callback URL exactly as received. The use of the X-VTEX-signature parameter will be mandatory from April 30, 2023 for security reasons. Callback requests made without this parameter will not work after the deadline.

For more information, see references below:

• Create Payment endpoint
• Payment Provider Protocol
• Purchase Flows