Versions Compared

Old Version 6

changes.mady.by.user PagBrasil

Saved on

compared with

New Version 7

changes.mady.by.user PagBrasil

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Field

Description

Required

Length

secret

Secret phrase as defined in the PagBrasil Dashboard

Yes

128

pbtoken

Token assigned to your merchant account. Your token is displayed at the PagBrasil Dashboard, menu Account > Settings.

Yes

32

order

Order number. See note "e"   

Yes

64

payment_method

X = PagBrasil Pix

Yes

1

product_name

Product name. See note "f"   

Yes

254

customer_name

Customer's full name if an individual, or "razão social" if the customer is a company. See note "g"   

Yes

128

customer_taxid

CPF if an individual, or CNPJ if the customer is a company. See note "h"   

Yes

14

customer_email

Customer's e-mail address

Yes

128

customer_phone

Customer's phone number (including the 2-digit area code)

Yes

40

address_street

Customer's street address

Yes

200

address_zip

Customer's postal code (in Brazil called CEP). Only digits, do not include the dash.

Yes

8

address_city

Customer's city

Yes

40

address_state

Customer's state. See note "i"   

Yes

2

amount_brl

Amount in Brazilian Real. See note "c"   

Yes

5.2

pix_expiration

Number of minutes the PagBrasil Pix is valid for. If you don't use this parameter, our system will use the default value set at the PagBrasil Dashboard, menu Account > Settings. You may extend the expiration of an already issued PagBrasil Pix using the API function "/api/order/extend" (see item 7).

No

5.0

param_url

A string that can be concatenated to the URL our server posts the response to. See note "j"   

No

254

Notes:

a) All fields are required except when noted otherwise.

...

b) If a parameter is sent with a size greater than the maximum allowed, process will not be aborted but the value will be truncated.

...

Anchor
PixNote41C
PixNote41C
c) Banks set daily limits that each customer is allowed to transfer to another account. Limits are set on a customer basis and may vary depending on each bank account.

...

d) The response for the "/api/order/add" call will be an XML with the order details, in exactly the same format as a "/api/order/get" response (see item 5.2). Elements "pix_image" and "pix_code" in the XML contain the URL of the Pix QR Code image and the alternative code for mobile users to copy and paste when they cannot scan the code. Please refer to item 5.2 for further information on the XML elements of the response.

...

Anchor
PixNoteEPixNote41EPixNoteE
PixNote41E
e) The order number must be unique for a specific customer. If you try to submit two different transactions with the same order number but a different customer_taxid, our server will respond with the message "Duplicated order.". Our server will also respond with "Duplicated order." if you try to re-submit an order that is already paid. If parameters order and customer_taxid are equal to a previously submitted unpaid order, the previous order will be updated with the new information provided and the response will be the URL that you will need to redirect the customer to (see note "d").
Characters allowed in the parameter order (regular expression): [a-zA-Z0-9\.\-\_\/]

...

Anchor
PixNote41F
PixNote41F
f) The parameter product_name must contain the name of the product or service purchased, and it is required for compliance purposes.

...

Anchor
PixNote41G
PixNote41G
g) You need to let the customer selects if they are a "pessoa física" (individual) or a "pessoa jurídica" (company). If they select "pessoa física", you need to ask for their full name and CPF (see note "h"). If they select "pessoa jurídica", you need to ask for the "razão social" (official company name registered at the local tax authority) and CNPJ (see note "h").

...

Anchor
PixNote41H
PixNote41H
h) There are two types of tax IDs in Brazil: CPF (used by individuals) and CNPJ (used by companies). You must validate the tax ID to prevent sending to PagBrasil invalid values. Please find below the format for each type of tax ID.

...

The last 2 digits of the CPF/CNPJ are check digits, and you will need to use them to validate the tax ID entered by the customer. You will find examples of CPF/CNPJ validation routines in different languages at the PagBrasil Dashboard, menu Resources. For testing purposes, please use CPF 91051605962 and CNPJ 78797547000157.

...

Anchor
PixNote41I
PixNote41I
i) The parameter address_state must be the official abbreviation used in Brazil. To prevent customer from entering an invalid state, please see table below to create a select object (drop-down list).

State

Abbreviation

Acre

AC

Alagoas

AL

Amapá

AP

Amazonas

AM

Bahia

BA

Ceará

CE

Distrito Federal

DF

Espírito Santo

ES

Goias

GO

Maranhão

MA

Mato Grosso

MT

Mato Grosso do Sul

MS

Minas Gerais

MG

Pará

PA

Paraíba

PB

Paraná

PR

Pernambuco

PE

Piauí

PI

Rio de Janeiro

RJ

Rio Grande do Norte

RN

Rio Grande do Sul

RS

Rondônia

RO

Roraima

RR

Santa Catarina

SC

São Paulo

SP

Sergipe

SE

Tocantins

TO

...

Anchor
PixNote41J
PixNote41J
j) The URL our server posts the response to for an "/api/order/add" call consists of a fixed and a dynamic part. The first part is defined at the PagBrasil Dashboard, menu Account > Settings. The second part is defined using param_url (optional).

...

Field

Description

Length

secret

Secret phrase as defined in the PagBrasil Dashboard

128

payment_method

X = PagBrasil Pix

1

order

Order number

64

amount_brl

Amount in Brazilian Real

5.2

payment_status

A = Authorized
F = Failed
R = Rejected See note "b"   
C = Chargeback (see item 6.2)
P = Refund Processed (see item 6.2)
J = Refund rejected (see item 6.2)

1

signature

HMAC-MD5 hash that authenticates the IPN. See note "c"   

32

Notes:

a) After processing our IPN your server needs to acknowledge it has successfully received it by writing "Received successfully [timestamp]". If your server responds to our IPN with an invalid acknowledgement, our system will e-mail your technical contact a warning notification (subject "Urgent: Error posting IPN - Not Compliant"). In this case, the IPN will not be resent and you may want to resend the IPN manually at the PagBrasil Dashboard, menu IPN History, after resolving the problem at your end.

...

Please note that any IPN can be resent manually at any time at the PagBrasil Dashboard, menu IPN History.

...

Anchor
#PixNote42B
#PixNote42B
b) The payment status is returned as "R" (Rejected) when our fraud screening denied the transaction for security reasons – without submitting it to the Pix system.

...

Anchor
#PixNote42C
#PixNote42C
c) To authenticate the legitimacy of the IPN, you may check the parameter secret and/or the parameter signature, which is a HMAC-MD5 hash based on three parameters and a key defined at the PagBrasil Dashboard, menu Account > Settings. The HMAC-MD5 source string is the concatenation of the values of the parameters order, amount_brl and payment_status and the total length for these three parameters. For example, if parameter order="1234567890", amount_brl="39.50" and payment_status="P", the parameter signature would be "3093a7dffa0c04e74e827d1b52ef514e".

...