PIX

Brazilian Instant Payment System

Introduction

The Brazilian Instant Payment System (PIX) is a new payment method created by the Central Bank of Brazil. It is a fast, secure and convenient way to make payments and transfer money. PIX is available 24/7, including weekends and holidays, and it is free for individuals and small businesses. Currently is the most popular payment method in Brazil.

Getting Started

• Generate Order
• Get QR code and Image
• Reverse Order

Generate Order

To generate a PIX order, you need to send a POST request to the following endpoint:

POST /api/v1/order
Host: payin.sulpayments.ch
Content-Type: "application/json"
ACCOUNT_TOKEN: "<token>"

{
  "customer": {
    "name": "Customer’s full name",
    "document": "111.222.333-44",
    "email": "[email protected]",
    "phone": "11999999999",
    "birth": "1996-03-09"
  },
  "order": {
    "code": "123",
    "notification_url": "your_payback_notification_url.com",
    "value": 50.00,
    "additional_info": "Some description of your order as String",
    "payment_method": "pix"
  }
}

Params descriptions

Field	Description	Value Type	Requirement
customer.name	Customer's full name	String	Required
customer.document	Customer's document	String	Required (see notes below)
customer.email	Customer's email address	String	Required
customer.phone	Customer's phone number	String	Required
customer.birth	Customer's date of birth	String	Required
order.code	Order reference in your system	String	Required
order.notification_url	URL to notify when status changes	String	Required
order.value	Total order value	Number (decimal)	Required
order.additional_info	Additional description of the order	String	Required
order.payment_method	Payment method	String	Required

Note 1: The document can be a valid CPF or CNPJ. If CNPJ is used, the company name must be passed in the name parameter.

Note 2: CPF and CNPJ are the Brazilian individual and company identification numbers, respectively.

On a successful request HTTP 200 status code, the response will include the following parameters:

{
  "latam_id": "7c0b8129-f556-4357-bb6e-8189c2943024",
  "code": "order_id_in_your_system",
  "confirmation_url": "https://sulpayments.ch/7c0b8129-f556-4357-bb6e-8189c2943024", # Redirect customer to see and pay the boleto.
  "qrcode_link": "https://sulpayments.ch/qrcode/7c0b8129-f556-4357-bb6e-8189c2943024" # Link to the qrcode
}

Business errors due to incorrect or missing parameters are returned with an HTTP 400 status code. The response will indicate which parameter is invalid or missing.

{
     "message": "Invalid document"
}

Compliance validation errors, including KYC-related issues, are returned with an HTTP 403 status code. The response will contain the following parameters:

{
  "latam_id": "7c0b8129-f556-4357-bb6e-8189c2943024",
  "message": "message table below",
  "code": "code table below"
}

Cancellation Scenarios

Scenario	code	message
Month's limit reached	AML-01	AML-01: Customer has reached month’s purchase limit
Semester's limit reached	AML-02	AML-02: Customer has reached semester’s purchase limit
RFI	BL-01	BL-01: RFI - Customer under investigation by Gowd Compliance team
Dispute	BL-02	BL-02: Dispute - Customer or issuing bank disputed a transaction payment
Multiple disputes	BL-03	BL-03: Disputes - Multiple disputes opened by the Customer or their issuing bank
Antifraud	BL-04	BL-04: Antifraud - Customer blocked by the Gowd antifraud engine
Internal decision	BL-05	BL-05: Customer blocked by Gowd Compliance team decision
Judicial decision	BL-06	BL-06: Customer blocked by judicial decision
Judicial/administrative processes	BL-07	BL-07: Customer blocked due to judicial or administrative processes
BL - Other reason	BL-08	BL-08: Customer blocked by Gowd Compliance team for a custom reason. Contact Gowd Compliance for details
MED	BL-09	BL-09: MED - Customer blocked due to a MED dispute
Payer blocked	BL-10	BL-10: Payer blocked by LG Compliance team decision
Partner restriction	CR-01	CR-01: Customer blocked by partner request
Payment Method restriction	CR-02	CR-02: Customer blocked from transacting with this payment method
Unregistered CPF	KYC110	CPF document not found.
Deceased holder	KYC110	CPF document belongs to a deceased holder. Year of death: 2024.
CPF Document suspended	KYC110	CPF document is suspended.
Invalid CNPJ	KYC111	Invalid CNPJ, please verify your CNPJ number.
Different name in Receita Federal	KYC112	Different name from the federal revenue register of natural persons.

Get QR code and Image

To get QR Code info and image after generating the order:

GET /api/v1/qrcode/{latam_id}
Host: payin.sulpayments.ch
Content-Type: "application/json"
ACCOUNT_TOKEN: "<token>"

The response will contain the following parameters:

{
  "qrcode_data": "string with all pix transaction info needed to be copy and paste into bank app",
  "qrcode_image": "base64 of the image"
}

Reverse Order

To reverse an order:

POST /api/v1/order/{order_id}/reverse
Host: payin.sulpayments.ch
Content-Type: "application/json"
ACCOUNT_TOKEN: "<token>"

If your request is successful, you will receive a response to the following

{
  "message": "message": "Refund requested. Waiting for confirmation from the bank."
}