PIX
Learn how to accept PIX, a common payment method in Brazil.
Pix is an instant payment method in Brazil. Customers receive a Pix string or QR code that contains the amount to pay for services or goods to complete transactions. Customers then pay the Pix, before its expiration date, using their bank apps or internet banking.
Payment type | Bank transfer |
Market | Brazil |
Customers currencies | BRL |
Processing currencies | BRL |
Settlement currencies | EUR |
Refunds | No |
CFT | Yes |
Recurring | No |
Step 1. Make a transaction request
From your server, make a POST /payment_preauthorize request.
https://sandbox.payabl.com/pay/backoffice/payment_preauthorize
Include in the request parameters below:
The below parameters are mandatory for PIX.
merchantid
: The merchant identification number.orderid
: The field orderid is optional and exclusively for the merchant's convenience.amount
: The amount field contains the transaction’s total amount. This is the amount that will be transmitted to the authorizing system.currency
: The currency field contains the alphanumeric currency code for the transaction, according to ISO 4217, e.g. BRL.payment_method
: The payment method id - 126.signature
: The signature field contains a 40-figure hexadecimal value. This signature value is a checksum designed to protect the merchant account from unauthorized access.country
: Customer country in ISO Alpha-2 format. Supported countries: BRA.email
: The customer's email address.custom2
: The name of payment method - pix.nationalid
: National ID is 13 number characters.
You can see a full list of parameters in Pre-Authorization.
Request example
merchantid=ala&amount=70¤cy=BRL&orderid=Inatec-Test&language=&lastname=Mann&street=Address+4&zip=&city=City&country=BRA&firstname=Muster&state=&email=test%40inatec.com&custom1=&custom2=&custom3=payment+reason&payment_method=126&phone=43543435435&bankname=341&accountnumber=0001&testmode=true&testmodecallbackstatus=FINISHED&nationalid=00183562658&accounttype=0001&accountagencynumber=8585&signature=249c85b8692404b20818dad506529738b1fcb338
Step 2. Handle the redirect
To complete the payment, you need to redirect the customer to the correct URL in the response.
Response
transactionid=215438979&transid=215438979&status=2000&errormessage=pending&errmsg=pending&amount=11.23&price=11.23¤cy=BRL&orderid=Payabl-Test&payment_method=126&redirect_url=https%3A%2F%2Fapi.gateway.payretailers.com%2Fv2%2Fpublic%2Ftransactions%2Fgateway%2F9eaafea3-bfff-49a0-9811-f37ca97c9f3d&user_id=289757
Step 3. Transaction states
If the customer successfully paid by using the Pix invoice, you will receive a notification with confirmation.
Notification example (successful transaction):
“errormessage=&national_id=13475444534&acquirer_id=1b928e7b-fc17-42b7-b675-ac1d28bb8a1b&payment_state=APPROVED&errorcode=0&payment_method=126&payretailers_method_name=PIX&type=capture&transactionid=215438984×tamp=1666096662&security=c4002d027ebfd99c2687aaf86d0d5631dc3212657fd05397e0afa70effff6293&psp_transaction_id=3283022&orderid=Payabl-Test" "https://www.notification_url"
Notification example with error:
payment_state=FAILED
“national_id=13475444534&transactionid=215438985&psp_transaction_id=3283028×tamp=1666096767&type=order&orderid=Payabl-Test&errormessage=Payment+failed&security=edb83f137da6b57d7566d0866c29484fed74ae79e3fd32325f32984e9d2c6a2a&acquirer_id=2fca2345-45f7-4f68-9b94-cf37a89d47f6&payment_state=FAILED&payment_method=126&errorcode=-5002&payretailers_method_name=PIX" "https://www.notification_url"
Field | Value Format | Accepted Values |
---|---|---|
merchantid | String | [A-Z][0-9] |
amount | Float | 0.00 |
currency | String | BRL |
orderid | String | [0-9] |
language | String | en |
lastname | String | [A-Z] |
street | String | * |
Address | String | * |
zip | String | [A-Z][0-9] |
city | String | [A-Z] |
country | String | Country Code |
firstname | String | [A-Z] |
state | String | [A-Z] |
String | [A-Z][0-9][-&_]@[A-Z][0-9].[A-Z] | |
custom1 ### optional ### | String | * |
custom2 | String | PIX |
custom3 ### optional payment reason ### | String | * |
payment_method | String | 126 Payment Method Id |
phone | String | [0-9] |
accounttype | String | Account Type |
accountagencynumber | String | Account Agency |
nationalid | String | [A-Z][0-9] |
bankname | String | Bank Name |
accountnumber | String | [A-Z][0-9] |
testmode ### only for testing ### | String | true |
testmodecallbackstatus ### only for testing ### | String | [PENDING-PROCESSED-ACCEPTED-FINISHED-ERROR] |
signature | String | * |
If the customer initiated the transaction but never completed it, you will receive a failed notification with payment_state=EXPIRED
“psp_transaction_id=3283037&security=5d143b5f1c5ac0d90dea3e55e5712069c94246be4900bad589eb83d2e40da5de×tamp=1666096902&national_id=13475444534&transactionid=215438986&payment_state=EXPIRED&payment_method=126&type=order&errorcode=-5003&payretailers_method_name=PIX&errormessage=Payment+aborted+by+customer&acquirer_id=84b293cf-43fe-4e28-ab89-12949ab4cb74&orderid=Payabl-Test" "https://www.notification_url"
Payouts
The method allows merchants to send funds to a bank account via wire transfer. In order for this to be done, the merchant needs to submit the bank details of the customer.
N.B.: Payouts can only be sent to the banks of this list: https://bank-codes.es/swift-code/brazil/
Include in request:
Request string:
POST https://pay4.powercash21.com/powercash21-3-2/backoffice/payment_cft
merchantid=ala&amount=70¤cy=BRL&orderid=Inatec-Test&language=en&lastname=Mann&street=Address+4&zip=60322&city=Sao+Pablo&country=BRA&firstname=Muster&state=HE&email=test%40inatec.com&custom1=&custom2=&custom3=payment+reason&payment_method=126&phone=43543435435&accounttype=0001&accountagencynumber=8585&nationalid=134.754.445-34&bankname=341&accountnumber=0001&testmode=true&testmodecallbackstatus=FINISHED&signature=3b7ef21563379421b18492ef27376588b2de82c2
- Response:
transactionid=215439104&transid=215439104&status=2000&errormessage=pending&errmsg=pending&amount=70&price=70¤cy=BRL&orderid=Inatec-Test&payment_method=126
1.1 Error
transactionid=215439105&transid=215439105&status=-6103&errormessage=Wrong%20currency&errmsg=Wrong%20currency&amount=70&price=70¤cy=USD&orderid=Inatec-Test&payment_method=126
1.2 Pending
"transactionid=215437556&transid=215437556&status=2000&errormessage=pending&errmsg=pending&amount=1230&price=1230¤cy=BRL&orderid=Inatec-Test&payment_method=126""
- Notification:
2.1 Notification example with Error:
Updated 17 days ago