PIX

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	Yes
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 - 130.
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-3 format. Supported countries: BRA.
email: The customer's email address.
custom2: The name of payment method - pix.
nationalid: Consumer’s national id, has to satisfy the following regular expression: 11 digits if CPF or 14 digits if CNPJ
nationaltype: User's identification type CPF or CNPJ

You can see a full list of parameters in Pre-Authorization.

Request example

/pay/backoffice/payment_preauthorize&merchantid=gateway_test&amount=23&currency=BRL&orderid=Payabl-Test
&language=en&gender=&lastname=Mann&street=Office+11A,+Swepco+Court,+Griva+Digeni+80&zip=60322&
city=Frankfurt&country=DEU&customerid=&salutation=&title=&firstname=Muster&company=&birthday=&house=
&postbox=&state=&email=&phone=&fax=&mobile=&customerip=&custom1=&custom2=pix&custom3=&
url_return=http://dev-sim-ng.inatec.local/~simdad/InatecResponse/redirect_response.php&url_success=h
ttp://dev-sim-ng.inatec.local/~simdad/InatecResponse/success.php&url_failed=http://dev-sim-ng.inatec
.local/~simdad/InatecResponse/failed.php&notification_url=https://api.powercash.de/simulation/
billing_response.php&payment_method=130&nationaltype=CPF&nationalid=50284414727&subject=test+subject
&content=test+content&signature=eea6ad75c2f63c77da0cfb466eb3ead4cc60a0bb

Step 2. Handle the redirect

To complete the payment, you need to redirect the customer to the correct URL in the response.

Response

transactionid=105352698&transid=105352698&status=2000&errormessage=pending&errmsg=pending&amount=23&
price=23&currency=BRL&orderid=Payabl-Test&user_id=787387&redirect_url=https://checkout-test.pagsmile.
com/checkout?prepay_id=VnpaMnhFbTVHM01PcSt0Q3ZBbkFuQjRsM2Nzai8xWlp4QlRZS1AyaWN2az0=-85

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):

security=271d20459db680e460160e8a95cf7517175c186f5734a3c2ad1a8122ba9e1004&type=capture&
errorcode=0&transactionid=215458647&acquirer_id=2023072807224800084&payment_state=credited&
payment_method=130&timestamp=1690370281&errormessage=&orderid=Payabl-Test"

Notification example with error:

payment_state=FAILED

errormessage=Payment+failed&orderid=Payabl-Test&payment_method=130&type=order&
acquirer_id=XXXXXXXXXXXXXXX0367&timestamp=1693225306&payment_state=not_credited&errorcode=-5002&
security=a87974c4ec8bdb8f6e0dd6e44f7f1caac74317d2ec330405685ada64204ff606&transactionid=105352719"
"https://api.powercash.de/simulation/billing_response.php

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]
email	String	[A-Z][0-9][-&_]@[A-Z][0-9].[A-Z]
custom1 ### optional ###	String	*
custom2 ### optional ###	String	*
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	*

Refunds

The method allows merchants to refund full or partial amount of initial transaction via wire transfer. In order for this to be done, the merchant needs to initiate refund request, and customer will receive email with link where he should specify payment information to receive refund. Merchant needs to specify email of the customer, that he could receive email.

Refund will be processed after

Request example

backoffice/payment_refund&merchantid=andrei&transactionid=215458995&amount=1¤cy=BRL&language=en&
external_id=en&signature=8b5d75824db2a85be4d9f98f68bfe900a527b8ee

Response example

transactionid=215458995&transid=215458995&status=0&errormessage=&errmsg=&amount=1.00&price=1.00&
currency=BRL&orderid=Payabl-Test

When

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.

Include in a request:

currency: "BRL"
account: Customer's PIX account
document_id: Customer's id
document_type: Customer's identification type, CPF or CNPJ
bankcountry:BRA
method: PIX
account_type: Customer's PIX account type, ex: CPF, CNPJ, EVP, PHONE, EMAIL

Request string:

POST  https://sandbox.payabl.com/pay/backoffice/payment_cft

merchantid=test_merchant&amount=1.23&currency=COP&orderid=Inatec-Test&language=en&lastname=Mann&
street=An+der+Welle+4&zip=60322&city=Frankfurt&country=DEU&firstname=Muster&state=HE&
email=test%40inatec.com&custom1=&custom2=&custom3=&payment_method=130&document_id=50284414727&document_
type=CC&method=TRANSFIYA&bankcountry=COL&additional_remark=transfer+money&account_type=PHONE&account=
57012345678910&signature=ff09cfa3b2e01e746ddbf19fbab08b30e31ab313

Response:

transactionid=215456949&transid=215456949&status=2000&errormessage=pending&errmsg=pending&amount=100&
price=100&currency=BRL&orderid=Payabl-Test&payment_method=130

1.1 Error

transactionid=215457170&transid=215457170&status=4001103&errormessage=method%20or%20channel%20is%20i
nactive&errmsg=method%20or%20channel%20is%20inactive&amount=2&price=2&currency=COP&orderid=Payabl-Test&
payment_method=130

Notification:

2.1 Notification example with Error:

errorcode=-5002&method=BANKTRANSFER&account_holder=Muster+Mann&security=389ff24d11207156c43bfc7e9ebc8
93e12726dda4f5a0aaa27544a8c4c986e7c&payment_method=130&bank_country=BRA&errormessage=rejected+by+bank&
orderid=Payabl-Test&type=cft&timestamp=1689154433&bank_code=001&transactionid=215456961

2Notification example with Success :

errormessage=&bank_code=001&method=BANKTRANSFER&account_holder=Muster+Mann&orderid=Payabl-Test&
errorcode=0&transactionid=215456949&timestamp=1689150492&bank_country=BRA&security=b67f198da9d310b9564
05ff879d098a2e0f8a1728a5ddad6b0e9c4ce3edc9dae&payment_method=130&type=cft

Example of PIX account

Account Type	Account	Description
CPF	22***99	11 digits
CPNJ	23******31	14 digits
Phone	+5511987654321 or 11987654321	country code (+55) is optional
Email	[email protected]
EVP	A UUID-like string: a1073db4-a3a0-11ed-a8fc-0242ac120002	alphanumeric string of 32 digits that is sent from the central bank to the institution