PrimeiroPay
Search
⌃K

PIX

PIX is a server to server only payment method to increase conversion.
Payment Types
Meaning
Success return codes
PA
Successful generation of the PIX QR-Code. The shopper can go and pay for it online or at any supported POS
000.000.000
000.100.112 (on staging)
RC
Successful payment of PIX. The payment of the PIX is asynchronous and the payment confirmation depends on when the PIX was paid by the consumer
000.000.000

Initial Request

//send POST to https://test.oppwa.com/v1/payments
//Header -H "Authorization: Bearer OGE4Mjk0MTg0ZTczNjAxMjAxNGU3OGExN2E2YTE1YjB8ZjJGRUtacXRCUA=="
amount=10.00
currency=BRL
paymentBrand=PIX
paymentType=PA
//API credentials
entityId=8a8294174ae82ada014aedfd75aa1d79
//API credentials end
//Shopper details (all mandatory)
customer.givenName=Gustavo
customer.surname=Santos
customer.identificationDocType=TAXSTATEMENT // Type of the identification DOC. Needed as you need to send a CPF/CNPJ
customer.identificationDocId=70383053102 //CPF/CNPJ number of end customer
//end of shopper details
billing.country="BR"
customParameters[CUSTOM_due_time]=7200 //Due time of the PIX in seconds. 7200 seconds = 2hours. You can also use customParameters[CUSTOM_due_date]=DDMMYYYY. If no expiry date is sent, will be set to 3 days by default.
merchantTransactionId=1234
shopperResultUrl=http://www.primeiropay.com //Although there is no re-direct back from PIX to your shop, our API requires this parameter to be present
testMode=EXTERNAL // only required on staging. Please remove on production environment
The collection of the CPF (Tax Identification number) is mandatory for all payments in Brazil. It is also mandatory to verify the CPF via this Java Script:
https://gist.github.com/cauerego/873308 - Connect to preview

Successful Response

{
"id":"8a82944964ea186c0164ecbf445f7385",
"paymentType":"PA",
"paymentBrand":"PIX",
"amount":"10.00",
"currency":"BRL",
"descriptor":"Test Merchant 2460.0146.3970 Virtual Goods",
"merchantTransactionId":"1234",
"result":{
"code":"000.100.112",
"description":"Request successfully processed in 'Merchant in Connector Test Mode'"
},
"resultDetails":{
"ExtendedDescription":"Payment method ready to be captured",
"connectorId":"beb52023-ea89-4750-9a82-75525d189249",
"ConnectorTxID2":"1234",
"reconciliationId":"1234"
},
"customer":{
"givenName":"Gustavo",
"surname":"Santos",
"identificationDocType":"TAXSTATEMENT",
"identificationDocId":"70383053102"
},
"customParameters":{
"CUSTOM_due_time":"7200"
},
"redirect":{
"url":"https://pix.primeiropay.com/2313413241414",
"parameters":[
]
},
"buildNumber":"[email protected] 10:29:18 +0000",
"timestamp":"2018-07-30 19:51:58+0000",
"ndc":"8a8294174ae82ada014aedfd75aa1d79_dca6a0b62dc44d0e81195603af6f39a7"
}

Re-directing the shopper

From the success response you will be able to extract the URL to where you re-direct the shopper to in order to display the PIX QR-code itself. Please note that the staging environment of the bank may show an error from time to time instead of the actual PIX.

Retrieve notifications when the PIX is paid

Please refer to section webhooks
[
2018-07-30
][
19:57:13,
046
]Notification b8d00c6a-276b-4816-a423-a7996e376834 message:{
"type":"PAYMENT",
"payload":{
"id":"8a82944a64ea2a060164ecc41d671606",
"referencedId":"8a82944a64ea2a060164ecc06db70bce",
"paymentType":"RC",
"amount":"10.0",
"currency":"BRL",
"presentationAmount":"10.0",
"presentationCurrency":"BRL",
"descriptor":"Test Merchant 6086.5776.5026 Virtual Goods",
"merchantTransactionId":"****",
"result":{
"code":"000.100.112",
"description":"Request successfully processed in 'Merchant in Connector Test Mode'",
"randomField621972632":"Please allow for new unexpected fields to be added"
},
"customer":{
"givenName":"Gustavo",
"surname":"Santos",
"identificationDocType":"TAXSTATEMENT",
"identificationDocId":"70383053102"
},
"billing":{
"country":"BR"
},
"authentication":{
"entityId":"8a8294174ae82ada014aedfd75aa1d79"
},
"customParameters":{
"INFO_matchingAlgorithm":"MANUAL_MATCH"
},
"redirect":{
"parameters":[
]
},
"risk":{
"score":""
},
"timestamp":"2018-07-30 19:57:12+0000",
"ndc":"DFCAD1AC1C0E00977B5A9FFE0E85AB3D.sbg-vm-bip01_1234_rand3cd6e14412f83147"
}
}

Field specifications

Name
Description
Format
Example
Authorization Bearer (Header)
Authentication token used to identify the merchant.
AN [a-zA-Z0- 9_]
Bearer OGE4Mjk0MTg0ZTczNjAxMjAxNGU3OGExN2E2YTE1YjB8ZjJGRUtacXRCUA==
amount
Amount of the payment request. The dot is used as a decimal separator.
N13[0- 9]{1,10}\.[0 -9]{2}
1.00
currency
Currency Code according to ISO 4217 specifications of the payment request’s amount
A3 [a-zA-Z]{3}
BRL
paymentBrand
The brand specifies the method for the request
AN32 [a-zA-Z0- 9_] {1,32}
PIX
paymentType
The payment type for the request
A2
PA
entityId
The entity for the request. (e.g. channel)
AN32 [a-zA-Z0- 9]{32}
8a8294174ae82ada014 aedfd75aa1d79
customer.identificationDocId
CPF number of customer or CNPJ of the company
N11 or N14
50439917476
or 50966454000190
merchantTransactionID
Merchant-provided reference number
AN255 [\s\S]{1,25 5}
1234
customParameters[CUSTOM_due_time]
Optional. Due Time of the Pix in Seconds.
Will overwrite customParameters[CUSTOM_due_date] if both are sent.
N10
7200
customParameters[CUSTOM_due_date]
Optional. Due Date of PIX.
Will be set to the date you sent at 23:59:59 UTC
DDMMYYYY
{19|20}([0-9]{2})-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1])
21012022