Xsolla

Xsolla is a global video game commerce platform that provides payment processing, distribution, and marketing tools for game developers and publishers. Through its partnership with EBANX, Xsolla merchants can accept local payment methods and credit card payments in Latin America using EBANX as a payment gateway within Xsolla's Pay Station checkout interface.

This guide covers how to configure EBANX as a gateway in Xsolla, the supported payment methods and countries, testing procedures, and troubleshooting.

Features

• Credit and debit card processing - Accept Visa, Mastercard, and local card brands in Latin American countries through EBANX acquiring.
• Local payment methods - Offer Boleto Bancário, Pix, and other region-specific payment methods in Brazil and across Latin America via Xsolla Pay Station.
• Gateway-configured integration - EBANX is enabled as a payment gateway within the Xsolla Publisher Account; no direct EBANX API integration is required by the merchant.
• Pay Station checkout - Xsolla's customizable payment UI handles the entire checkout experience, including payment method selection and local payment rendering.
• Refunds - Full and partial refunds are supported for card transactions.

Requirements

Before starting the integration, ensure you have the following:

• Xsolla account - An active Xsolla Publisher Account. If you do not have one, sign up at Xsolla.
• Xsolla project - A project created in your Xsolla Publisher Account with Pay Station enabled.
• EBANX account - An active EBANX merchant account. Contact EBANX Sales to set up your account.
• EBANX credentials - Your EBANX Integration Key, provided by the EBANX integrations team during onboarding.

How it works

1. 1 The customer initiates a purchase on the merchant's website, game client, or web shop.

2. 2 The merchant creates a payment token using the Xsolla API or SDK, which contains the transaction details and user information.

3. 3 Xsolla opens the Pay Station checkout interface, displaying available payment methods for the customer's region.

4. 4 The customer selects a local payment method (such as Pix or Boleto) or enters card details and submits the payment.

5. 5 Xsolla routes the payment to EBANX for processing in the target Latin American market.

6. 6 EBANX processes the payment with the local acquirer or payment network and returns the result to Xsolla.

7. 7 Xsolla sends a webhook notification to the merchant with the final payment status.

8. 8 The merchant delivers the purchased content or virtual items to the customer.

Supported payment methods

Payment Method	Countries	Currencies	Description
Credit and debit cards	Brazil, Mexico, Colombia, Argentina, Chile, Peru	BRL, MXN, COP, ARS, CLP, PEN, USD	Visa, Mastercard, and local card brands processed through EBANX acquiring.
Pix	Brazil	BRL	Instant payment via QR code or copy-and-paste code. Settlement is near-instant.
Boleto Bancário	Brazil	BRL	Cash voucher payment. Non-instant; the customer pays at a bank branch, lottery house, or via online banking within the voucher expiration period.

Key details

• Integration type - Gateway-configured (via Xsolla Publisher Account)
• Supported operations - Purchase, Refund
• 3D Secure - Supported for card transactions where required
• Card on File - Not applicable (Xsolla manages tokenization)
• Recurring billing - Supported for cards via Xsolla's subscription engine
• Settlement currency - Configured during EBANX onboarding

Instructions

Follow the steps below.

1. Set up your EBANX account

   Contact the EBANX integrations team to establish your merchant account and obtain your EBANX Integration Key. During onboarding, EBANX will configure the supported countries, payment methods, and settlement parameters for your account.

   Provide your Xsolla Merchant ID to EBANX so the integration can be linked on both sides.

2. Connect EBANX as a gateway in Xsolla

   Log in to your Xsolla Publisher Account and navigate to Payments > Payments settings > Gateways. Locate the EBANX gateway in the list and click Connect.

   Fill in the required fields, including your EBANX Integration Key, and click Send request. Your request will be reviewed by Xsolla, and once validated, the gateway status will change to Activated.

   Caution

   The gateway validation process by Xsolla can take up to 5 working days. Contact your Xsolla account representative if the activation takes longer than expected.

3. Integrate Xsolla Pay Station

   Use the standard Xsolla integration to accept payments. No EBANX-specific code is needed on the merchant side. All payment routing to EBANX is handled automatically by Xsolla based on the customer's location and selected payment method.

   For detailed integration instructions, refer to the Xsolla documentation:

   • Get a token to open Pay Station - Generate a payment token on your server.
   • Open Pay Station - Display the checkout interface using the Xsolla SDK or iframe.
   • Mobile SDK - Mobile-specific integration guide for iOS and Android.

4. Configure webhooks

   Set up Xsolla webhooks to receive asynchronous notifications about payment status changes. This is important for all payment methods, and particularly for non-instant methods like Boleto where the customer pays after the transaction is created.

   Follow the Xsolla Webhooks documentation to configure your webhook endpoint. Key events to listen for include:

   • payment - A payment has been completed successfully.
   • refund - A refund has been processed.
   • cancel_subscription - A subscription has been cancelled.

5. Congratulations!

   Your Xsolla integration is now configured to process payments in Latin America through EBANX. Use the testing section below to validate your setup before going live.

Limitations

General limitations

• No direct EBANX API access - Merchants interact exclusively with the Xsolla API and Pay Station. EBANX-specific features not exposed through Xsolla (such as EBANX Payment Page or EBANX.js) are not available.
• Payment methods - Only the payment methods listed in the supported payment methods table above are available through the Xsolla channel. Other EBANX-supported methods may not be available depending on your Xsolla and EBANX configuration.
• Gateway activation - Connecting the EBANX gateway in Xsolla requires a validation step by Xsolla that can take up to 5 working days.

Local payment methods limitations

• Non-instant settlement - Boleto is a non-instant payment method. The customer must complete payment after the transaction is created, and settlement occurs asynchronously.
• Transaction limits - Boleto transactions have a maximum of 35,000 BRL.

Required fields

Credit and debit cards

• Cardholder name
• Card number
• Expiration date
• CVV
• Customer billing address (country)

Pix

• Customer name
• Customer email address
• Customer CPF (tax ID)

Boleto Bancário

• Customer name
• Customer email address
• Customer CPF (tax ID)
• Customer billing address (street address, city, state, postal code)

Testing

Sandbox testing

Xsolla provides a sandbox environment for testing payment flows without processing real transactions. Use your EBANX sandbox credentials when configuring the gateway for testing.

To test in sandbox mode:

1. Configure the EBANX gateway in Xsolla using your EBANX Sandbox Integration Key.
2. Create a test payment token with sandbox mode enabled.
3. Complete the checkout flow in Pay Station using test card numbers provided by Xsolla.
4. Verify that webhook notifications are received correctly for successful and failed transactions.

For local payment methods, the sandbox environment simulates the customer approval and payment steps.

Going live

Before going live, verify the following:

• EBANX has confirmed your merchant account is active for production.
• The EBANX gateway is activated in your Xsolla Publisher Account with production credentials.
• You have successfully processed test transactions in the Xsolla sandbox for all payment methods you intend to offer.
• Webhook endpoints are configured and responding correctly to payment status events.
• Error handling is implemented for declined transactions, timeouts, and expired vouchers.

Troubleshooting

Transactions are being declined

Verify that the card's issuing country is in a supported EBANX region. Check the Xsolla transaction details in Publisher Account for the specific decline reason and refer to the EBANX error codes for details.

Local payment methods are not appearing in Pay Station

Confirm that the EBANX gateway is activated in your Xsolla Publisher Account. Ensure the payment method is enabled for the customer's country and that the transaction currency matches the supported currency for that method.

Gateway activation is pending

After submitting your EBANX gateway configuration in Xsolla, the validation process can take up to 5 working days. Contact your Xsolla account representative if the activation takes longer than expected.

Boleto payments not completing

Boleto is a non-instant payment method that requires the customer to complete payment separately. Ensure your webhook endpoint is configured to receive payment completion events and that your system updates the order status accordingly.

Caution

Boleto vouchers expire if not paid within the configured period. Make sure your system handles expired vouchers and updates the order status accordingly.

Pix payments timing out

Pix QR codes have a limited validity period. By default, Pix payments expire after 30 minutes, but this can be customized using the expiration_time_in_seconds request parameter. If the customer does not complete the payment within this window, the transaction will expire.

Caution

Ensure your system handles expired Pix transactions gracefully and provides the customer with an option to retry.

Resources

Sample Cards

Click here to view mock card data to validate your payment integration.

Click to explorechevron_right

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.