Skip to main content

PrimeiroPay gateway integration


PrimeiroPay gateway integration

PrimeiroPay is a cross-border payment service provider for any merchant that wants to expand into Latin America without opening a local entity. The PrimeiroPay gateway offers local processing, local payment methods, legal support and regulated, transparent foreign exchange services.

PrimeiroPay is fully integrated with Zuora now, which enables you to immediately accept card payments in Brazil and Mexico.

Supported payment methods

The following payment methods are supported by the PrimeiroPay integration in Zuora:

  Brazil Mexico
Supported payment methods

Credit Cards, including:

  • Visa
  • Mastercard
  • Discover
  • American Express

Credit Cards, including:

  • Visa
  • Mastercard

Stored credential transactions

The PrimeiroPay gateway integration includes support for the Stored Credential Transactions framework of Visa.

Supported payment operations

The PrimeiroPay integration supports the following payment operations:

  • Validate
  • Capture payments
  • Refund
  • Cancel payments

Configure PrimeiroPay gateway

To set up PrimeiroPay as your gateway, navigate to the Payments Settings > Setup Payment Gateway page. When selecting a Gateway Type, select PrimeiroPay from the dropdown list.

Common fields for configuration

You must complete some common fields for every gateway configuration. Zuora recommends that you review the Setting Up Payment Gateways article for more information on these common fields: 

  • Name
  • Use Gateway Test Environment
  • Cards Accepted
  • Default Authorization Amount
  • Verify payment method (optional)
  • Verify updated payment method (optional)

Additional fields for configuration

In addition to the common fields, every gateway has unique requirements and information (such as credentials and certain rules) that you must provide to configure the gateway instance in Zuora. Complete the following fields in the PrimeiroPay gateway instance:

  • Channel ID: The identifier of the entity for requests. An entity can be a division, merchant, or channel. Channel is the default entity for sending payment transactions. 
  • Auth Token: The bearer token used to access the PrimeiroPay API.


  • Your customers will always see two bookings on their statements as a result of a refund.
  • Requires CPF (Cadastro de Pessoas Fisicas or Natural Persons Register), which is the individual taxpayer registry identification, to be passed in the request as the Merchant Customer ID.
  • Non-referenced refunds (credits) are not supported.
  • Pre-authorization transactions are not supported in Mexico.
  • The 0 auth amount is not supported in Mexico.
  • For the American Express and Discover credit cards in Brazil, you must specify a value greater than 0 for the Default Authorization Amount field.