This guide is for payment providers that want to offer PSE (Pagos Seguros en Línea) as a payment method in VTEX stores. PSE is a Colombian online bank transfer method that uses the redirect purchase flow.

During the order transaction, the connector must know which bank the customer selected. The integration requires the following steps:

1. Send bank list endpoint and authentication information to VTEX.
2. Update the List Payment Provider Manifest to include PSE.
3. Handle the bankCode metadata in the Create Payment request.
4. Request the payment connector update through VTEX Support.

To integrate PSE, you must have a partnership agreement for financial services with VTEX. If you don't have one, contact VTEX Support.

VTEX needs access to your bank list endpoint to display available banks to buyers at checkout. Submit the following information through VTEX Support:

• GET Banks endpoint: The URL that returns a list of available banks. Include the expected response body format and any required parameters.
• Authentication credentials: Any keys or tokens required to call the endpoint.

Example request that VTEX makes to your endpoint:

If the auth-token requires additional steps to generate (for example, an OAuth flow), describe the process when submitting your information.

Expected response body:

Add PSE to the paymentMethods array in your List Payment Provider Manifest response:

When a buyer selects PSE and chooses a bank at checkout, VTEX sends the selected bank code in the metadata field of the Create Payment request:

Your connector must:

1. Read the bankCode from the metadata object.
2. Create the payment in PSE using the selected bank.
3. Return a response with:
   • status: "undefined" (since the payment requires redirect).
   • paymentUrl: The bank's authentication page URL where the buyer completes the payment.

The metadata field can be null if the bank selection app isn't properly configured. In this case, the connector must return an error with code PSE_CUSTOM_APP_NOT_FOUND.

After the buyer is redirected to the bank's authentication page:

1. The buyer completes authentication at the selected bank.
2. The bank processes the transfer and returns the result to the provider.
3. The provider calls the callbackUrl (included in the original Create Payment request) to notify VTEX of the final status: approved or denied.
4. VTEX redirects the buyer back to the store using the returnUrl:
   • Payment approved: The order confirmation page is displayed.
   • Payment denied: An error page with the specific failure reason is displayed.

For more details on the redirect flow and callback mechanism, see Purchase Flows.

After implementing the PSE integration, submit the connector for homologation to make it available to VTEX merchants.