Payment-method icon

Pix for API only

Accept Pix payments using our APIs, and build your own payment form.

Accept Pix payments using our APIs, and build your own payment form to have full control over the look and feel of your checkout page.

Before you begin

Before starting your Pix integration:

  1. Make sure that you have set up your back end implementation.
  2. Add Pix in your test Customer Area.

Build your payment form for Pix

Include Pix in the list of available payment methods. If you're using the /paymentMethods endpoint to show which payment methods are available to the shopper, specify in your request:

The response contains:

  • paymentMethod.type: pix

Collect additional parameters in your payment form

After the shopper selects Pix, collect the following optional details from the shopper:

Pass the collected data from the front end to your server because you will need to submit both Name and CPF/CNPJ in the /payments request. Show this information to the shopper together with the QR code to help identify the payment.

Make a payment

To make a Pix payment, pass the following data to your server:

  • Payment method type: pix.
  • Data collected from your shopper in the previous step, if any.

Then, from your server, make a /payments request with the following parameters:

Parameter Required Description
paymentMethod.type -white_check_mark- Set to pix.
amount -white_check_mark- The final price of the purchase.
shopperName The shopper's firstName and lastName. If you don't have the shopper's name, you can skip shopperName. Keep the length of each field under 200 characters, otherwise it will be truncated. This will be shown to the shopper in the payments form.
socialSecurityNumber The shopper's CPF or CNPJ number. If you don't have the shopper's CPF or CNPJ, you can skip socialSecurityNumber. This will be shown to the shopper in the payments form.
shopperStatement Free-text field that will be shown to the shopper. Maximum length: 140 characters.
sessionValidity The expiration date of the Pix payment. The default value is 24 hours, the maximum value is 5 days, in ISO 8601 format.
For example: 2020-07-18T15:42:40.428+01:00
lineItems Information about purchased items.
lineItems.id The name of the purchased item. Maximum 50 characters.
lineItems.amountIncludingTax The price of the purchased item including tax. Maximum 200 characters.

You need to send both shopperName and socialSecurityNumber because this information will be shown to the shopper to help identify the payment.

The response contains the following data:

  • resultCode: Pending
  • action: Contains the QR code url and qrCodeData.

Render the QR code or present QR code data

Use the information in the action object of the /payments response to render the QR code or present the QR code data to the shopper.

  • action.qrCodeData: Use this to render the QR Code on your checkout page or present as-is to the shopper to copy it.

The shopper can either scan the QR code, or copy the QR code data to paste to their banking or wallet app.

Payment result

After the shopper scans the QR code and completes the payment, you will receive the result of the payment asynchronously in a webhook.

Here's an example of a standard webhook you may receive.

For more information, see Webhooks.

You can include the following fields in your payment confirmation:
pix.payer.bankName
pix.payer.isbp
pix.payer.name
pix.payer.taxId

To add these fields to your notifications:

  1. Log in to your test Customer Area.
  2. Select Developers>Webhooks.
  3. Select the edit icon next to the name of the webhook.
  4. Under Additional settings>Payment, select Include Pix Payer info.

Refunds

You can refund a payment within 90 days after the payment in the Customer Area or via an API.

Test and go live

Pix is an asynchronous payment method. In the test environment, you can simulate a Pix payment by promoting the pending payment to a sale.

  1. Log in to your test Customer Area.
  2. Go to Transactions > Offers.
  3. Select the PSP reference of the pending Pix payment.
  4. Select the Promote this offer to a sale button.

Pix payments that have been paid (including test offers that you manually promoted to sale) are under Transactions > Payments.

Test the reconciliation process by promoting test payments from offer to sale in your test Customer Area.

Before you can accept live Pix payments, you need to submit a request for Pix in your live Customer Area.

See also