Payments API - Brazil
The Payments API for Brazil allows you to efficiently integrate PayU’s payment processing features into your online shopping platform. Through this API, businesses can offer their customers a wide variety of payment methods, including mobile applications, electronic transfers, cash, bank transfers, and credit cards.
This guide shows you how to leverage these services to enhance your customers’ payment experience by providing flexible and secure payment options tailored to the local market.
Note
To integrate the Payments API, direct your requests to the following URLs according to the corresponding environment:
- Testing:
https://sandbox.api.payulatam.com/payments-api/4.0/service.cgi - Production:
https://api.payulatam.com/payments-api/4.0/service.cgi
Available Methods
Payments API includes the following methods:
- Submit Transactions Using Credit Cards
- Submit Transactions Using Google Pay
- Submit Transactions Using PIX
- Submit Transactions Using Cash
- Submit Transactions Using Bank Transfer
- Available Payment Methods Query
- Ping
Note
To confirm the status of a transaction, you can use one of the following options:
- Navigate to the the URL set in the
transaction.notifyUrlvariable or the Confirmation URL option located in the PayU Module in Settings > Technical configuration. - Use the Queries API or SDK.
Submit Transactions Using Credit Cards
This method lets you process the payments performed by your customers using credit cards. For Brazil, you can perform the two-step flows (Authorization, Capture), and one-step flows (Charge). For more information, refer to Payment flows.
Adding Payment Facilitators
Merchants can be considered as Payment Processor by franchises and the Central Bank. A payment processor is a legal entity that has money from sub-merchants. In the case of merchant bankruptcy and tax management, the Brazilian Central Bank wants to know the business’s beneficiary.
To include the information of the sub-merchant, you need to include it in the request of the Authorization, and Charge flows using the submerchant object.
What is a Payment Facilitator?
A payment facilitator is a company that offers an alternative to contracting with a traditional payment organization by assuming responsibility for the flow of funds in a buyer-seller relationship.
Many merchants are choosing to work with payment facilitators because the payment facilitator possesses and manages the master account, thus assuming a risk. Merchants also choose a payment facilitator due the simplicity of setting up an account, typically occurring through a short application and underwriting evaluation.
What Information is Required?
You need to send the following information:
- Sub-merchant’s internal identification (optional)
- Sub-merchant’s Name (optional)
- Sub-merchant’s ID Number (mandatory) *Individuals or Legal Entities
- Sub-merchant’s Address (optional)
- Sub-merchant’s State (mandatory)
- Sub-merchant’s Postal Code (mandatory)
- Sub-merchant’s Country (mandatory)
Find the description of these fields in the Parameters section.
Using Tokenized Cards
PayU supports payments with your tokenized card, enabling you to make regular payments with a card stored in a token. A credit card token replaces the sensitive information of a credit card, allowing you to store it safely in compliance with PCI DSS (Payment Card Industry Data Security Standard) security standards.
PayU can process payments using the following services:
-
PayU Tokenization.
We offer our own service to tokenize your credit cards upon request. This service allows you to tokenize your customers’ credit card information (regardless of their franchise) using our API or SDK integration.
For more information, refer to PayU Tokenization. -
MasterCard Digital Enablement Service - MDES.
A tokenization service provided by Mastercard. This service enables you to tokenize the Primary Account Number of MasterCard credit cards, allowing you to use them for regular payments or to build one-click payment features.
For more information, refer to MasterCard Digital Enablement Service (MDES). -
Visa Token Service - VTS.
A tokenization service provided by Visa. This service allows you to store the sensitive information of Visa credit cards in a token, enabling you to use them for regular payments or to build one-click payment features.
For more information, refer to Visa Token Service (VTS).
Pay with PayU Tokens
To make payments using PayU credit card tokens, include the parameter transaction.creditCardTokenId in place of the credit card information.
The following example demonstrates the body of the request at a high level for a one-step flow. It doesn’t include request parameters.
Note
To process a payment without the CVV, you must set the parametercreditCard.processWithoutCvv2 to true in the payment request and omit the parameter creditCard.securityCode.By default, processing credit cards without a security code is not enabled. To enable this feature, please contact your sales representative.
Request Example:
{
"language": "es",
"command": "SUBMIT_TRANSACTION",
"merchant": {
"apiKey": "4Vj8eK4rloUd272L48hsrarnUA",
"apiLogin": "pRRXKOl8ikMmt9u"
},
"transaction": {
"order": {
"Information of the order":""
},
"payer": {
"Information of the payer":""
},
"creditCardTokenId": "46b7f03e-1b3b-4ce8-ad90-fe1a482f76c3",
"creditCard": {
"securityCode": "123"
},
"extraParameters": {
"Extra parameters of the request":""
},
"type": "AUTHORIZATION_AND_CAPTURE",
"paymentMethod": "Card franchise",
"paymentCountry": "Processing country",
"deviceSessionId": "vghs6tvkcle931686k1900o6e1",
"ipAddress": "127.0.0.1",
"cookie": "pt1t38347bs6jc9ruv2ecpv7o2",
"userAgent": "Mozilla/5.0 (Windows NT 5.1; rv:18.0) Gecko/20100101 Firefox/18.0"
},
"test": true
}
Request Example:
<request>
<language>es</language>
<command>SUBMIT_TRANSACTION</command>
<merchant>
<apiKey>4Vj8eK4rloUd272L48hsrarnUA</apiKey>
<apiLogin>pRRXKOl8ikMmt9u</apiLogin>
</merchant>
<transaction>
<order>
<!-- Information of the order -->
</order>
<payer>
<!-- Information of the payer -->
</payer>
<creditCardTokenId>46b7f03e-1b3b-4ce8-ad90-fe1a482f76c3</creditCardTokenId>
<creditCard>
<securityCode>321</securityCode>
</creditCard>
<extraParameters>
<!-- Extra parameters of the request -->
</extraParameters>
<type>AUTHORIZATION_AND_CAPTURE</type>
<paymentMethod>{Card franchise}</paymentMethod>
<paymentCountry>{Processing country}</paymentCountry>
<deviceSessionId>vghs6tvkcle931686k1900o6e1</deviceSessionId>
<ipAddress>127.0.0.1</ipAddress>
<cookie>pt1t38347bs6jc9ruv2ecpv7o2</cookie>
<userAgent>Mozilla/5.0 (Windows NT 5.1; rv:18.0) Gecko/20100101 Firefox/18.0</userAgent>
</transaction>
<isTest>false</isTest>
</request>
Pay with MDES or VTS Tokens
If you are tokenizing your customer’s credit cards using MDES or VTS, you can configure the token information in the parameter transaction.networkToken, replacing the credit card information, and set the parameter creditCard.processWithoutCvv2 to true.
By default, processing credit cards without a security code is not enabled. Please contact your sales representative to enable this feature.
The following example demonstrates the body of the request at a high level for a one-step flow. Detailed request parameters are not provided.
Request Example:
{
"language": "es",
"command": "SUBMIT_TRANSACTION",
"merchant": {
"apiKey": "4Vj8eK4rloUd272L48hsrarnUA",
"apiLogin": "pRRXKOl8ikMmt9u"
},
"transaction": {
"order": {
"Information of the order":""
},
"payer": {
"Information of the payer":""
},
"networkToken": {
"tokenPan": "4097440000000004",
"cryptogram": "11223344556677889900112233445566778899",
"expiry": "2028/01"
},
"extraParameters": {
"Extra parameters of the request":""
},
"type": "AUTHORIZATION_AND_CAPTURE",
"paymentMethod": "Card franchise",
"paymentCountry": "Processing country",
"deviceSessionId": "vghs6tvkcle931686k1900o6e1",
"ipAddress": "127.0.0.1",
"cookie": "pt1t38347bs6jc9ruv2ecpv7o2",
"userAgent": "Mozilla/5.0 (Windows NT 5.1; rv:18.0) Gecko/20100101 Firefox/18.0"
},
"test": true
}
Request Example:
<request>
<language>es</language>
<command>SUBMIT_TRANSACTION</command>
<merchant>
<apiKey>4Vj8eK4rloUd272L48hsrarnUA</apiKey>
<apiLogin>pRRXKOl8ikMmt9u</apiLogin>
</merchant>
<transaction>
<order>
<!-- Information of the order -->
</order>
<payer>
<!-- Information of the payer -->
</payer>
<networkToken>
<tokenPan>4097440000000004</tokenPan>
<cryptogram>11223344556677889900112233445566778899</cryptogram>
<expiry>2028/01</expiry>
</networkToken>
<extraParameters>
<!-- Extra parameters of the request -->
</extraParameters>
<type>AUTHORIZATION_AND_CAPTURE</type>
<paymentMethod>{Card franchise}</paymentMethod>
<paymentCountry>{Processing country}</paymentCountry>
<deviceSessionId>vghs6tvkcle931686k1900o6e1</deviceSessionId>
<ipAddress>127.0.0.1</ipAddress>
<cookie>pt1t38347bs6jc9ruv2ecpv7o2</cookie>
<userAgent>Mozilla/5.0 (Windows NT 5.1; rv:18.0) Gecko/20100101 Firefox/18.0</userAgent>
</transaction>
<isTest>false</isTest>
</request>
Find the description of the object transaction.networkToken and its parameters in the Variables section.
Parameters for Request and Response
Request
| Field Name | Format | Size | Description | Mandatory |
|---|---|---|---|---|
| language | Alphanumeric | 2 | Language used in the request, this language is used to display the error messages generated. See supported languages. | Yes |
| command | Alphanumeric | Max:32 | Set SUBMIT_TRANSACTION. |
Yes |
| test (JSON) isTest (XML) |
Boolean | Set true if the request is in test mode. Otherwise, set false. |
Yes | |
| merchant | Object | This object has the authentication data. | Yes | |
| merchant > apiLogin | Alphanumeric | Min:12 Max:32 | User or login provided by PayU. How do I get my API Login | Yes |
| merchant > apiKey | Alphanumeric | Min:6 Max:32 | Password provided by PayU. How do I get my API Key | Yes |
| transaction | Object | This object has the transaction data. | Yes | |
| transaction > order | Object | This object has the order data. | Yes | |
| transaction > order > accountId | Number | Identifier of your account. | Yes | |
| transaction > order > referenceCode | Alphanumeric | Min:1 Max:255 | Represents the identifier of the order in your system. | Yes |
| transaction > order > description | Alphanumeric | Min:1 Max:255 | Description of the order. | Yes |
| transaction > order > language | Alphanumeric | 2 | Language used in emails sent to the buyer and the seller. | Yes |
| transaction > order > notifyUrl | Alphanumeric | Max:2048 | Confirmation URL of the order. | No |
| transaction > order > partnerId | Alphanumeric | Max:255 | Partner ID in PayU. | No |
| transaction > order > signature | Alphanumeric | Max:255 | The signature associated to the form. For more information refer Authentication signature. | Yes |
| transaction > order > shippingAddress | Object | Shipping address. | No | |
| transaction > order > shippingAddress > street1 | Alphanumeric | Max:100 | Address Line 1. | No |
| transaction > order > shippingAddress > street2 | Alphanumeric | Max:100 | Address Line 2. | No |
| transaction > order > shippingAddress > city | Alphanumeric | Max:50 | Address city. | No |
| transaction > order > shippingAddress > state | Alphanumeric | Max:40 | Address State. For Brazil, only send two characters, For example, set SP for São Paulo. |
No |
| transaction > order > shippingAddress > country | Alphanumeric | 2 | Address country. | No |
| transaction > order > shippingAddress > postalCode | Alphanumeric | Max:8 | Address Zip code. For Brazil, use the format XXXXX-XXX or XXXXXXXX. Example: 09210-710 or 09210710. |
No |
| transaction > order > shippingAddress > phone | Alphanumeric | Max:11 | Phone number associated to the address. For Brazil, use the format ddd(2)+number(7-9). Example: (11)756312633. |
No |
| transaction > order > buyer | Object | Buyer information. | Yes | |
| transaction > order > buyer > merchantBuyerId | Alphanumeric | Max:100 | Buyer ID in your system. | No |
| transaction > order > buyer > fullName | Alphanumeric | Max:150 | Full name of the buyer. | Yes |
| transaction > order > buyer > emailAddress | Alphanumeric | Max:255 | E-mail of the buyer. | Yes |
| transaction > order > buyer > contactPhone | Alphanumeric | Max:20 | Phone number of the buyer. | Yes |
| transaction > order > buyer > dniNumber | Alphanumeric | Max:20 | Identification number of the buyer. You must use an algorithm to validate the CPF and must be set using the format XXX.XXX.XXX-XX. Example: 811.807.405-64. |
Yes |
| transaction > order > buyer > cnpj | Alphanumeric | Max:14 | Identification number of the buyer (For Legal person in Brazil). You must use an algorithm to validate the CNPJ and must be set using the format XXXXXXXXXXXXXX. Example: 32593371000110. |
Yes |
| transaction > order > buyer > shippingAddress | Alphanumeric | Shipping address of the buyer. | Yes | |
| transaction > order > buyer > shippingAddress > street1 | Alphanumeric | Max:150 | Buyer’s shipping address Line 1. | Yes |
| transaction > order > buyer > shippingAddress > city | Alphanumeric | Max:50 | Buyer’s shipping address city. | Yes |
| transaction > order > buyer > shippingAddress > state | Alphanumeric | Max:40 | Buyer’s shipping address state. For Brazil, only send two characters, For example, set SP for São Paulo. |
Yes |
| transaction > order > buyer > shippingAddress > country | Alphanumeric | 2 | Buyer’s shipping address country in format ISO 3166 alpha-2. | Yes |
| transaction > order > buyer > shippingAddress > postalCode | Number | Max:20 | Buyer’s shipping address zip code. For Brazil, use the format XXXXX-XXX or XXXXXXXX. Example: 09210-710 or 09210710. |
Yes |
| transaction > order > buyer > shippingAddress > phone | Number | Max:20 | Buyer’s shipping address phone number. For Brazil, use the format ddd(2)+number(7-9). Example: (11)756312633. |
Yes |
| transaction > order > additionalValues > | Object | 64 | Amount of the order or its associated values. | Yes |
| transaction > order > additionalValues > TX_VALUE | Alphanumeric | 64 | Amount of the transaction. | Yes |
| transaction > order > additionalValues > TX_VALUE > value | Number | 12, 2 | Specifies the amount of the transaction, this value may have two decimal digits (Ex. 10000.00 or 10000). |
Yes |
| transaction > order > additionalValues > TX_VALUE > currency | Alphanumeric | 3 | ISO code of the currency. See accepted currencies. | Yes |
| transaction > order > additionalValues > TX_TAX | Alphanumeric | 64 | Amount of the Value Added Tax (VAT). | Yes |
| transaction > order > additionalValues > TX_TAX > value | Number | 12, 2 | Specifies the amount of the VAT. | No |
| transaction > order > additionalValues > TX_TAX > currency | Alphanumeric | 3 | ISO code of the currency. See accepted currencies. | No |
| transaction > order > additionalValues > TX_TAX_RETURN_BASE | Alphanumeric | 64 | Base value to calculate the VAT. If the amount does not have IVA, send 0. This value may have two decimal digits. |
No |
| transaction > order > additionalValues > TX_TAX_RETURN_BASE > value | Number | 12, 2 | Specifies the base amount of the transaction. | No |
| transaction > order > additionalValues > TX_TAX_RETURN_BASE > currency | Alphanumeric | 3 | ISO code of the currency. See accepted currencies. | No |
| transaction > order > submerchant | Object | Information of the sub-merchant. If you don’t send this parameter, PayU configures your merchant as sub-merchant. | No | |
| transaction > order > submerchant > id | Alphanumeric | Max:15 | Internal ID of the sub-merchant if you use one to identify it. | No |
| transaction > order > submerchant > fullName | Alphanumeric | Max:150 | Full name of the sub-merchant. | No |
| transaction > order > submerchant > address | Object | Sub-merchant address. The fields state, country, and postalCodeare mandatory when sending this object. |
No | |
| transaction > order > submerchant > address > street1 | Alphanumeric | Max:100 | Address Line 1. | No |
| transaction > order > submerchant > address > street2 | Alphanumeric | Max:100 | Address Line 2. | No |
| transaction > order > submerchant > address > street3 | Alphanumeric | Max:100 | Address Line 3. | No |
| transaction > order > submerchant > address > city | Alphanumeric | Max:50 | Address city. | No |
| transaction > order > submerchant > address > state | Alphanumeric | Max:40 | Address State. For Brazil, only send two characters, For example, set SP for São Paulo. |
Yes |
| transaction > order > submerchant > address > country | Alphanumeric | 2 | Address country. | Yes |
| transaction > order > submerchant > address > postalCode | Alphanumeric | Max:8 | Address Zip code. For Brazil, use the format XXXXX-XXX or XXXXXXXX. Example: 09210-710 or 09210710. |
Yes |
| transaction > order > submerchant > address > phone | Alphanumeric | Max:11 | Phone number associated to the address. For Brazil, use the format ddd(2)+number(7-9). Example: (11)756312633. |
No |
| transaction > order > submerchant > identification | Alphanumeric | Max:14 | Identification number of the buyer (For Legal person in Brazil). You must use an algorithm to validate the CNPJ and must be set using the format XXXXXXXXXXXXXX. Example: 32593371000110. |
No |
| transaction > order > submerchant > identificationType | Alphanumeric | Max:4 | Identification type of the sub-merchant. The possible values are cnpj or cpf. |
No |
| transaction > creditCardTokenId | Alphanumeric | Include this parameter when the transaction is done using a tokenized card using the PayU Tokenization; moreover, it is mandatory to also send the parameter transaction.creditCard.expirationDate.For more information, refer to Tokenization API. |
No | |
| transaction > creditCard | Object | Credit card information. This object and its parameters are mandatory when the payment is performed using not tokenized credit card. | No | |
| transaction > creditCard > number | Alphanumeric | Min:13 Max:20 | Credit card number. | No |
| transaction > creditCard > securityCode | Alphanumeric | Min:1 Max:4 | Credit card security code (CVC2, CVV2, CID). | No |
| transaction > creditCard > expirationDate | Alphanumeric | 7 | Credit card expiration date. Format YYYY/MM. This parameter is mandatory when the payment is performed using a tokenized credit card. |
No |
| transaction > creditCard > name | Alphanumeric | Min:1 Max:255 | Holder’s name displayed in the credit card. *Mandatory just for Google Pay transactions. | No* |
| transaction > creditCard > processWithoutCvv2 | Boolean | Max:255 | Allows you to process transactions without including the credit card security code. Your commerce requires PayU’s authorization before using this feature. | No |
| transaction > payer | Object | Payer information. | No | |
| transaction > payer > emailAddress | Alphanumeric | Max:255 | Payer e-mail address. | No |
| transaction > payer > merchantPayerId | Alphanumeric | Max:100 | Identifier of the payer in your system. | No |
| transaction > payer > fullName | Alphanumeric | Max:150 | Name of the payer which must meet the name sent in the parameter transaction.creditCard.name for credit card payments. |
No |
| transaction > payer > billingAddress | Object | Billing address. | No | |
| transaction > payer > billingAddress > street1 | Alphanumeric | Max:100 | Billing Address Line 1. | No |
| transaction > payer > billingAddress > street2 | Alphanumeric | Max:100 | Billing Address Line 2. | No |
| transaction > payer > billingAddress > city | Alphanumeric | Max:50 | Billing address city. | No |
| transaction > payer > billingAddress > state | Alphanumeric | Max:40 | Billing address state. For Brazil, only send two characters, For example, set SP for São Paulo. |
No |
| transaction > payer > billingAddress > country | Alphanumeric | 2 | Billing address country in format ISO 3166 Alpha-2. | No |
| transaction > payer > billingAddress > postalCode | Alphanumeric | Max:20 | Billing address zip code. For Brazil, use the format XXXXX-XXX or ´. Example: 09210-710 or 09210710. |
No |
| transaction > payer > billingAddress > phone | Alphanumeric | Max:20 | Billing address phone number. For Brazil, use the format ddd(2)+number(7-9). Example: (11)756312633. |
No |
| transaction > payer > birthdate | Alphanumeric | Max:10 | Payer’s date of birth. | No |
| transaction > payer > contactPhone | Alphanumeric | Max:20 | Payer’s phone number. For Brazil, use the format ddd(2)+number(7-9). Example: (11)756312633. |
No |
| transaction > payer > dniNumber | Alphanumeric | Max:20 | Identification number of the buyer. You must use an algorithm to validate the CPF and must be set using the format XXX.XXX.XXX-XX. Example: 811.807.405-64. |
No |
| transaction > payer > cnpj | Alphanumeric | Max:14 | Identification number of the buyer (For Legal person in Brazil). You must use an algorithm to validate the CNPJ and must be set using the format XXXXXXXXXXXXXX. Example: 32593371000110. |
No |
| transaction > payer > dniType | Alphanumeric | 2 | Identification type of the buyer. See Document types. | No |
| transaction > networkToken | Object | Information of the token. Include this parameter when the transaction is done using a tokenized card using the VTS or MDES Tokenization. For more information, refer to Pay with MDES or VTS tokens. *When sending this object, all its parameters are mandatory. |
No | |
| transaction > networkToken > tokenPan | Alphanumeric | Max:32 | Token number generated either by MDES or VTS. | Yes* |
| transaction > networkToken > cryptogram | Alphanumeric | Max:28 | Unique key generated by MDES or VTS to decrypt the information of the credit card. | Yes* |
| transaction > networkToken > expiry | Alphanumeric | 7 | Expiration date of the token. Format YYYY/MM. |
Yes* |
| transaction > digitalWallet | Object | Include this parameter when the transaction is done using a Digital Wallet. *When sending this object, all its parameters are mandatory. | No | |
| transaction > digitalWallet > type | Alphanumeric | —- | Set this value according to the digital wallet that you are processing: GOOGLE_PAY | Yes* |
| transaction > digitalWallet > message | Alphanumeric | —- | Include the information of the Google Pay Token that Google will return to you for each transaction. For more information consult here. | Yes* |
| transaction > type | Alphanumeric | 32 | Set this value according to the transaction you want:
|
Yes |
| transaction > paymentMethod | Alphanumeric | 32 | Select a valid Credit card Payment Method. See the available Payment Methods for Brazil. | Yes |
| transaction > paymentCountry | Alphanumeric | 2 | Set BR for Brazil. |
Yes |
| transaction > deviceSessionId | Alphanumeric | Max:255 | Session identifier of the device where the customer performs the transaction. For more information, refer to this topic. | Yes |
| transaction > ipAddress | Alphanumeric | Max:39 | IP address of the device where the customer performs the transaction. | Yes |
| transaction > cookie | Alphanumeric | Max:255 | Cookie stored by the device where the customer performs the transaction. | Yes |
| transaction > userAgent | Alphanumeric | Max:1024 | The User agent of the browser where the customer performs the transaction. | Yes |
| transaction > extraParameters | Object | Additional parameters or data associated with the request. The maximum size of each extraParameters name is 64 characters. In JSON, the extraParameters parameter follows this structure: "extraParameters": {"INSTALLMENTS_NUMBER": 1}In XML, the extraParameters parameter follows this structure: <extraParameters><entry><string>INSTALLMENTS_NUMBER</string><string>1</string></entry></extraParameters> |
No | |
| transaction > termsAndConditionsAcepted | Boolean | PayU terms and conditions that the payers must accept. *This parameter is only mandatory if your Brazilian PayU account is associated to a foreign bank account. | No* | |
| transaction > threeDomainSecure | Object | This object contains the information of 3DS 2.0. | No | |
| transaction > threeDomainSecure > embedded | Boolean | Set true if you want to use and embedded MPI for the Authorization process. By default, this value is set as false. |
No | |
| transaction > threeDomainSecure > eci | Number | Max:2 | Electronic Commerce Indicator. Value returned by the directory servers showing the authentication attempt. This parameter is mandatory when transaction.threeDomainSecure.embedded is false and transaction.threeDomainSecure.xid has been set. |
No |
| transaction > threeDomainSecure > cavv | Alphanumeric | Max:28 | Cardholder Authentication Verification Value. Code of the cryptogram used in the transaction authentication in Base64. Depending on the specific ECI codes established by the process network, this value may be optional. |
No |
| transaction > threeDomainSecure > xid | Alphanumeric | Max:28 | Transaction ID sent by the MPI in Base64. This parameter is mandatory when transaction.threeDomainSecure.embedded is false and transaction.threeDomainSecure.eci has been set. |
No |
| transaction > threeDomainSecure > directoryServerTransactionId | Alphanumeric | Max:36 | Transaction ID generated by the Directory Server during the Authentication. | No |
Response
| Field Name | Format | Size | Description |
|---|---|---|---|
| code | Alphanumeric | The response code of the transaction. Possible values are ERROR and SUCCESS. |
|
| error | Alphanumeric | Max:2048 | The error message associated when the response code is ERROR. |
| transactionResponse | Object | The response data. | |
| transactionResponse > orderId | Number | The generated or existing order Id in PayU. | |
| transactionResponse > transactionId | Alphanumeric | 36 | The identifier of the transaction in PayU. |
| transactionResponse > state | Alphanumeric | Max:32 | The status of the transaction. |
| transactionResponse > responseCode | Alphanumeric | Max:64 | The response code associated with the status. |
| transactionResponse > paymentNetworkResponseCode | Alphanumeric | Max:255 | The response code returned by the financial network. |
| transactionResponse > paymentNetworkResponseErrorMessage | Alphanumeric | Max:255 | The error message returned by the financial network. |
| transactionResponse > trazabilityCode | Alphanumeric | Max:32 | The traceability code returned by the financial network. |
| transactionResponse > authorizationCode | Alphanumeric | Max:12 | The authorization code returned by the financial network. |
| transactionResponse > responseMessage | Alphanumeric | Max:2048 | Message associated with the response code. |
| transactionResponse > operationDate | Date | Creation date of the response in the PayU´s system. | |
| transactionResponse > extraParameters | Object | Additional parameters or data associated with the response. In JSON, the extraParameters parameter follows this structure: "extraParameters": {"BANK_REFERENCED_CODE": "CREDIT"}In XML, the extraParameters parameter follows this structure: <extraParameters><entry><string>BANK_REFERENCED_CODE</string><string>CREDIT</string></entry></extraParameters> |
Considerations
- If your commerce does not have a local entity, it is mandatory to send either the CPF (parameter
transaction.[payer|buyer].dniNumber) or the CNPJ (parametertransaction.[payer|buyer].cnpj) when using Authorization or Charge. - If you don’t send any information for the sub-merchants, PayU configures your merchant as sub-merchant.
- For payments with credit card tokens generated by PayU, include the parameters
transaction.creditCardTokenIdandtransaction.creditCard.securityCode(if you process with security code) replacing the information of the credit card. For more information, refer to Tokenization API. - For payments with credit card tokens generated using MDES or VTS, include the object
transaction.networkTokenand its parameters. - By default, processing credit cards without security code is not enabled. If you want to enable this feature, contact your Sales representative. After this feature is enabled for you, send in the request the variable
creditCard.processWithoutCvv2as true and remove the variablecreditCard.securityCode.
Having this feature enable is mandatory when using credit card tokens generated using MDES or VTS. - The extra parameter
CIELO_TIDidentifies the transaction, this parameter is needed when you want to process voids. - The variable
transaction.threeDomainSecuredoes not replace the card information nor any of the mandatory fields of the transaction. This object is additional and not mandatory. - The variable
transaction.threeDomainSecurecorresponds to a passthrough scenario where the commerce performs the authentication by their own.
Authorization
Use this method to perform the Authorization step of a two-step flow. In this step, you authorize the payment but the amount is not debited until you capture the funds.
The following are the request and response bodies for this transaction type.
Request Example:
{
"language": "es",
"command": "SUBMIT_TRANSACTION",
"merchant": {
"apiKey": "4Vj8eK4rloUd272L48hsrarnUA",
"apiLogin": "pRRXKOl8ikMmt9u"
},
"transaction": {
"order": {
"accountId": "512327",
"referenceCode": "PRODUCT_TEST_2021-06-17T19:11:57.179Z",
"description": "Payment test description",
"language": "es",
"signature": "fbc089272288edc52c332395d9566f4c",
"notifyUrl": "http://www.payu.com/notify",
"additionalValues": {
"TX_VALUE": {
"value": 1000,
"currency": "BRL"
}
},
"submerchant": {
"fullName": "ROBSON BATISTA DE OLIVEIRA",
"address": {
"street1": "Rua Alsácia",
"street2": null,
"street3": null,
"city": "São Paulo",
"state": "SP",
"country": "BR",
"postalCode": "04630010",
"phone": null
},
"identification": "17126661851",
"identificationType": "CNPJ"
},
"buyer": {
"merchantBuyerId": "1",
"fullName": "First name and second buyer name",
"emailAddress": "buyer_test@test.com",
"contactPhone": "7563126",
"dniNumber": "811.807.405-64",
"cnpj": "32593371000110",
"shippingAddress": {
"street1": "Quadra QNP 34 Conjunto G 780",
"street2": "5555487",
"city": "Manaos",
"state": "SP",
"country": "BR",
"postalCode": "10012545",
"phone": "(11)756312633"
}
},
"shippingAddress": {
"street1": "Quadra QNP 34 Conjunto G 780",
"street2": "5555487",
"city": "Manaos",
"state": "SP",
"country": "BR",
"postalCode": "10012545",
"phone": "(11)756312633"
}
},
"creditCard": {
"number": "5253203387684619",
"securityCode": "777",
"expirationDate": "2022/12",
"name": "APPROVED"
},
"extraParameters": {
"INSTALLMENTS_NUMBER": 1
},
"type": "AUTHORIZATION",
"paymentMethod": "MASTERCARD",
"paymentCountry": "BR",
"deviceSessionId": "vghs6tvkcle931686k1900o6e1",
"ipAddress": "127.0.0.1",
"cookie": "pt1t38347bs6jc9ruv2ecpv7o2",
"userAgent": "Mozilla/5.0 (Windows NT 5.1; rv:18.0) Gecko/20100101 Firefox/18.0",
"threeDomainSecure": {
"embedded": false,
"eci": "01",
"cavv": "AOvG5rV058/iAAWhssPUAAADFA==",
"xid": "Nmp3VFdWMlEwZ05pWGN3SGo4TDA=",
"directoryServerTransactionId": "00000-70000b-5cc9-0000-000000000cb"
}
},
"test": false
}
Response Example:
{
"code": "SUCCESS",
"error": null,
"transactionResponse": {
"orderId": 1400434770,
"transactionId": "79de715b-fe77-401e-8b18-241820afb375",
"state": "APPROVED",
"paymentNetworkResponseCode": "00",
"paymentNetworkResponseErrorMessage": null,
"trazabilityCode": "282856",
"authorizationCode": "MOCK-CIELO-1623957118463",
"pendingReason": null,
"responseCode": "APPROVED",
"errorCode": null,
"responseMessage": null,
"transactionDate": null,
"transactionTime": null,
"operationDate": 1623939118784,
"referenceQuestionnaire": null,
"extraParameters": {
"BANK_REFERENCED_CODE": "CREDIT",
"CIELO_TID": "1006993069000509C28A"
},
"additionalInfo": null
}
}
Request Example:
<request>
<language>es</language>
<command>SUBMIT_TRANSACTION</command>
<merchant>
<apiKey>4Vj8eK4rloUd272L48hsrarnUA</apiKey>
<apiLogin>pRRXKOl8ikMmt9u</apiLogin>
</merchant>
<transaction>
<order>
<accountId>512327</accountId>
<referenceCode>PRODUCT_TEST_2021-06-17T19:11:57.179Z</referenceCode>
<description>Payment test description</description>
<language>es</language>
<signature>fbc089272288edc52c332395d9566f4c</signature>
<notifyUrl>http://www.payu.com/notify</notifyUrl>
<additionalValues>
<entry>
<string>TX_VALUE</string>
<additionalValue>
<value>1000</value>
<currency>BRL</currency>
</additionalValue>
</entry>
</additionalValues>
<submerchant>
<address>
<city>São Paulo</city>
<country>BR</country>
<postalCode>04630010</postalCode>
<state>SP</state>
<street1>Rua Alsácia</street1>
</address>
<fullName>ROBSON BATISTA DE OLIVEIRA</fullName>
<identification>17126661851</identification>
<identificationType>cnpj</identificationType>
</submerchant>
<buyer>
<merchantBuyerId>1</merchantBuyerId>
<fullName>First name and second buyer name</fullName>
<emailAddress>buyer_test@test.com</emailAddress>
<contactPhone>7563126</contactPhone>
<dniNumber>811.807.405-64</dniNumber>
<cnpj>32593371000110</cnpj>
<shippingAddress>
<street1>Quadra QNP 34 Conjunto G 780</street1>
<street2>5555487</street2>
<city>Manaos</city>
<state>SP</state>
<country>BR</country>
<postalCode>10012545</postalCode>
<phone>(11)756312633</phone>
</shippingAddress>
</buyer>
<shippingAddress>
<street1>Quadra QNP 34 Conjunto G 780</street1>
<street2>5555487</street2>
<city>Manaos</city>
<state>SP</state>
<country>BR</country>
<postalCode>0000000</postalCode>
<phone>(11)756312633</phone>
</shippingAddress>
</order>
<creditCard>
<number>5253203387684619</number>
<securityCode>777</securityCode>
<expirationDate>2022/12</expirationDate>
<name>APPROVED</name>
</creditCard>
<extraParameters>
<entry>
<string>INSTALLMENTS_NUMBER</string>
<string>1</string>
</entry>
</extraParameters>
<type>AUTHORIZATION</type>
<paymentMethod>MASTERCARD</paymentMethod>
<paymentCountry>BR</paymentCountry>
<deviceSessionId>vghs6tvkcle931686k1900o6e1</deviceSessionId>
<ipAddress>127.0.0.1</ipAddress>
<cookie>pt1t38347bs6jc9ruv2ecpv7o2</cookie>
<userAgent>Mozilla/5.0 (Windows NT 5.1; rv:18.0) Gecko/20100101 Firefox/18.0</userAgent>
<threeDomainSecure>
<embedded>false</embedded>
<eci>01</eci>
<cavv>AOvG5rV058/iAAWhssPUAAADFA==</cavv>
<xid>Nmp3VFdWMlEwZ05pWGN3SGo4TDA=</xid>
<directoryServerTransactionId>00000-70000b-5cc9-0000-000000000cb</directoryServerTransactionId>
</threeDomainSecure>
</transaction>
<isTest>false</isTest>
</request>
Response Example:
<paymentResponse>
<code>SUCCESS</code>
<transactionResponse>
<orderId>1400434942</orderId>
<transactionId>1af49d5d-464a-4efb-98db-f7875e3c580b</transactionId>
<state>APPROVED</state>
<paymentNetworkResponseCode>00</paymentNetworkResponseCode>
<trazabilityCode>282856</trazabilityCode>
<authorizationCode>MOCK-CIELO-1623962788239</authorizationCode>
<responseCode>APPROVED</responseCode>
<operationDate>2021-06-17T10:46:28</operationDate>
<extraParameters>
<entry>
<string>BANK_REFERENCED_CODE</string>
<string>CREDIT</string>
</entry>
<entry>
<string>CIELO_TID</string>
<string>1006993069000509C28A</string>
</entry>
</extraParameters>
</transactionResponse>
</paymentResponse>
Capture
Use this method to perform the Capture step of a two-step flow. In this step, you capture the funds previously Authorized to transfer them to your PayU account.
Considerations
Take into account the following considerations for capture:
- The maximum time to capture an approved transaction is 7 days. After this time, the transaction is cancelled.
- Only the parameters displayed in the request body are mandatory to invoke a Capture transaction. Recall that the order and transaction ids must meet with a currently authorized transaction.
- You can perform partial captures on an authorized amount. For more information, see the Partial Capture section.
The following are the request and response bodies for this transaction type.
Request Example:
{
"language": "es",
"command": "SUBMIT_TRANSACTION",
"merchant": {
"apiLogin": "pRRXKOl8ikMmt9u",
"apiKey": "4Vj8eK4rloUd272L48hsrarnUA"
},
"transaction": {
"order": {
"id": "1400434770"
},
"type": "CAPTURE",
"parentTransactionId": "79de715b-fe77-401e-8b18-241820afb375"
},
"test": false
}
Response Example:
{
"code": "SUCCESS",
"error": null,
"transactionResponse": {
"orderId": 1400434770,
"transactionId": "2e753a5e-0eba-4a4c-9778-6880b5f16605",
"state": "APPROVED",
"paymentNetworkResponseCode": "6",
"paymentNetworkResponseErrorMessage": null,
"trazabilityCode": "282856",
"authorizationCode": "BR-456",
"pendingReason": null,
"responseCode": "APPROVED",
"errorCode": null,
"responseMessage": null,
"transactionDate": null,
"transactionTime": null,
"operationDate": 1624029247864,
"referenceQuestionnaire": null,
"extraParameters": {
"CIELO_TID": "1006993069000509C28A"
},
"additionalInfo": null
}
}
Request Example:
<request>
<language>es</language>
<command>SUBMIT_TRANSACTION</command>
<merchant>
<apiKey>4Vj8eK4rloUd272L48hsrarnUA</apiKey>
<apiLogin>pRRXKOl8ikMmt9u</apiLogin>
</merchant>
<transaction>
<order>
<id>1400436982</id>
</order>
<type>CAPTURE</type>
<parentTransactionId>2cb57976-31d1-4563-b014-8047bd1b2b2a</parentTransactionId>
</transaction>
<isTest>false</isTest>
</request>
Response Example:
<paymentResponse>
<code>SUCCESS</code>
<transactionResponse>
<orderId>1400436982</orderId>
<transactionId>78d4c328-7157-4b50-9fa9-12e019e7df58</transactionId>
<state>APPROVED</state>
<paymentNetworkResponseCode>6</paymentNetworkResponseCode>
<trazabilityCode>282856</trazabilityCode>
<authorizationCode>BR-456</authorizationCode>
<responseCode>APPROVED</responseCode>
<operationDate>2021-06-18T10:19:01</operationDate>
<extraParameters>
<entry>
<string>BANK_REFERENCED_CODE</string>
<string>CREDIT</string>
</entry>
<entry>
<string>CIELO_TID</string>
<string>1006993069000509C28A</string>
</entry>
</extraParameters>
</transactionResponse>
</paymentResponse>
Partial Capture
A partial capture is an operation that allows you to request the disbursement of an amount less than what was previously authorized in a transaction.
This means that if your integration initially authorized a payment of $100, you can perform a partial capture for $60, and release the remaining $40, which the integration will not be able to capture later.
Considerations
- The total amount captured cannot exceed the originally authorized amount.
- Each payment processor and each country may have rules or restrictions regarding the amount you can capture partially.
- You must specify the value you wish to partially capture in the
valuefield, within theTX_VALUEparameter, as shown in the example below.
The following are examples of the request and response bodies for this type of transaction.
Request Example:
{
"language": "es",
"command": "SUBMIT_TRANSACTION",
"merchant": {
"apiLogin": "pRRXKOl8ikMmt9u",
"apiKey": "4Vj8eK4rloUd272L48hsrarnUA"
},
"transaction": {
"order": {
"id": "2152525133"
},
"additionalValues": {
"TX_VALUE": {
"value": 60,
"currency": "BRL"
}
},
"type": "CAPTURE",
"parentTransactionId": "4b6adba7-e43b-45f8-88a6-d290755d6c04"
},
"test": false
}
Response Example:
{
"code": "SUCCESS",
"error": null,
"transactionResponse": {
"orderId": 2152543423,
"transactionId": "6f523681-1587-4a2d-8a15-605d27f89c26",
"state": "APPROVED",
"paymentNetworkResponseCode": "0",
"paymentNetworkResponseErrorMessage": null,
"trazabilityCode": "6f523681-1587-4a2d-8a15-605d27f89c26",
"authorizationCode": "NPS-011111",
"pendingReason": null,
"responseCode": "APPROVED",
"errorCode": null,
"responseMessage": "APROBADA - Autorizada",
"transactionDate": null,
"transactionTime": null,
"operationDate": 1723724052207,
"referenceQuestionnaire": null,
"extraParameters": null,
"additionalInfo": {
"paymentNetwork": "NPS_AR",
"rejectionType": "NONE",
"responseNetworkMessage": null,
"travelAgencyAuthorizationCode": null,
"cardType": null,
"transactionType": "CAPTURE"
}
}
}
Request Example:
<request>
<language>es</language>
<command>SUBMIT_TRANSACTION</command>
<merchant>
<apiLogin>pRRXKOl8ikMmt9u</apiLogin>
<apiKey>4Vj8eK4rloUd272L48hsrarnUA</apiKey>
</merchant>
<transaction>
<order>
<id>2152525133</id>
</order>
<additionalValues>
<TX_VALUE>
<value>60</value>
<currency>BRL</currency>
</TX_VALUE>
</additionalValues>
<type>CAPTURE</type>
<parentTransactionId>4b6adba7-e43b-45f8-88a6-d290755d6c04</parentTransactionId>
</transaction>
<test>false</test>
</request>
Response Example:
<response>
<code>SUCCESS</code>
<error />
<transactionResponse>
<orderId>2152543423</orderId>
<transactionId>6f523681-1587-4a2d-8a15-605d27f89c26</transactionId>
<state>APPROVED</state>
<paymentNetworkResponseCode>0</paymentNetworkResponseCode>
<paymentNetworkResponseErrorMessage />
<trazabilityCode>6f523681-1587-4a2d-8a15-605d27f89c26</trazabilityCode>
<authorizationCode>NPS-011111</authorizationCode>
<pendingReason />
<responseCode>APPROVED</responseCode>
<errorCode />
<responseMessage>APROBADA - Autorizada</responseMessage>
<transactionDate />
<transactionTime />
<operationDate>1723724052207</operationDate>
<referenceQuestionnaire />
<extraParameters />
<additionalInfo>
<paymentNetwork>NPS_AR</paymentNetwork>
<rejectionType>NONE</rejectionType>
<responseNetworkMessage />
<travelAgencyAuthorizationCode />
<cardType />
<transactionType>CAPTURE</transactionType>
</additionalInfo>
</transactionResponse>
</response>
Charge
Use this method to perform a one-step flow, namely a charge. In this step, both steps of the two-step flow are combined in a single transaction and the funds are transferred from the customers account to your PayU account once they have been approved:
The following are the request and response bodies for this transaction type.
Request Example:
{
"language": "es",
"command": "SUBMIT_TRANSACTION",
"merchant": {
"apiKey": "4Vj8eK4rloUd272L48hsrarnUA",
"apiLogin": "pRRXKOl8ikMmt9u"
},
"transaction": {
"order": {
"accountId": "512327",
"referenceCode": "PRODUCT_TEST_2021-06-17T19:11:57.179Z",
"description": "Payment test description",
"language": "es",
"signature": "fbc089272288edc52c332395d9566f4c",
"notifyUrl": "http://www.payu.com/notify",
"additionalValues": {
"TX_VALUE": {
"value": 1000,
"currency": "BRL"
}
},
"submerchant": {
"fullName": "ROBSON BATISTA DE OLIVEIRA",
"address": {
"street1": "Rua Alsácia",
"street2": null,
"street3": null,
"city": "São Paulo",
"state": "SP",
"country": "BR",
"postalCode": "04630010",
"phone": null
},
"identification": "17126661851",
"identificationType": "CNPJ"
},
"buyer": {
"merchantBuyerId": "1",
"fullName": "First name and second buyer name",
"emailAddress": "buyer_test@test.com",
"contactPhone": "7563126",
"dniNumber": "811.807.405-64",
"cnpj": "32593371000110",
"shippingAddress": {
"street1": "Quadra QNP 34 Conjunto G 780",
"street2": "5555487",
"city": "Manaos",
"state": "SP",
"country": "BR",
"postalCode": "10012545",
"phone": "(11)756312633"
}
},
"shippingAddress": {
"street1": "Quadra QNP 34 Conjunto G 780",
"street2": "5555487",
"city": "Manaos",
"state": "SP",
"country": "BR",
"postalCode": "10012545",
"phone": "(11)756312633"
}
},
"creditCard": {
"number": "5178151142107990",
"securityCode": "777",
"expirationDate": "2022/12",
"name": "APPROVED"
},
"extraParameters": {
"INSTALLMENTS_NUMBER": 1
},
"type": "AUTHORIZATION_AND_CAPTURE",
"paymentMethod": "MASTERCARD",
"paymentCountry": "BR",
"deviceSessionId": "vghs6tvkcle931686k1900o6e1",
"ipAddress": "127.0.0.1",
"cookie": "pt1t38347bs6jc9ruv2ecpv7o2",
"userAgent": "Mozilla/5.0 (Windows NT 5.1; rv:18.0) Gecko/20100101 Firefox/18.0",
"threeDomainSecure": {
"embedded": false,
"eci": "01",
"cavv": "AOvG5rV058/iAAWhssPUAAADFA==",
"xid": "Nmp3VFdWMlEwZ05pWGN3SGo4TDA=",
"directoryServerTransactionId": "00000-70000b-5cc9-0000-000000000cb"
}
},
"test": false
}
Response Example:
{
"code": "SUCCESS",
"error": null,
"transactionResponse": {
"orderId": 1400437001,
"transactionId": "f0f8c441-43e8-490a-b4f2-c14d2c403175",
"state": "APPROVED",
"paymentNetworkResponseCode": "6",
"paymentNetworkResponseErrorMessage": null,
"trazabilityCode": "282856",
"authorizationCode": "MOCK-CIELO-1624047897817",
"pendingReason": null,
"responseCode": "APPROVED",
"errorCode": null,
"responseMessage": null,
"transactionDate": null,
"transactionTime": null,
"operationDate": 1624029898077,
"referenceQuestionnaire": null,
"extraParameters": {
"BANK_REFERENCED_CODE": "CREDIT",
"CIELO_TID": "1006993069000509C28A"
},
"additionalInfo": null
}
}
Request Example:
<request>
<language>es</language>
<command>SUBMIT_TRANSACTION</command>
<merchant>
<apiKey>4Vj8eK4rloUd272L48hsrarnUA</apiKey>
<apiLogin>pRRXKOl8ikMmt9u</apiLogin>
</merchant>
<transaction>
<order>
<accountId>512327</accountId>
<referenceCode>PRODUCT_TEST_2021-06-17T19:11:57.179Z</referenceCode>
<description>Payment test description</description>
<language>es</language>
<signature>fbc089272288edc52c332395d9566f4c</signature>
<notifyUrl>http://www.payu.com/notify</notifyUrl>
<additionalValues>
<entry>
<string>TX_VALUE</string>
<additionalValue>
<value>1000</value>
<currency>BRL</currency>
</additionalValue>
</entry>
</additionalValues>
<submerchant>
<address>
<city>São Paulo</city>
<country>BR</country>
<postalCode>04630010</postalCode>
<state>SP</state>
<street1>Rua Alsácia</street1>
</address>
<fullName>ROBSON BATISTA DE OLIVEIRA</fullName>
<identification>17126661851</identification>
<identificationType>cnpj</identificationType>
</submerchant>
<buyer>
<merchantBuyerId>1</merchantBuyerId>
<fullName>First name and second buyer name</fullName>
<emailAddress>buyer_test@test.com</emailAddress>
<contactPhone>7563126</contactPhone>
<dniNumber>811.807.405-64</dniNumber>
<cnpj>32593371000110</cnpj>
<shippingAddress>
<street1>Quadra QNP 34 Conjunto G 780</street1>
<street2>5555487</street2>
<city>Manaos</city>
<state>SP</state>
<country>BR</country>
<postalCode>10012545</postalCode>
<phone>(11)756312633</phone>
</shippingAddress>
</buyer>
<shippingAddress>
<street1>Quadra QNP 34 Conjunto G 780</street1>
<street2>5555487</street2>
<city>Manaos</city>
<state>SP</state>
<country>BR</country>
<postalCode>0000000</postalCode>
<phone>(11)756312633</phone>
</shippingAddress>
</order>
<creditCard>
<number>5178151142107990</number>
<securityCode>777</securityCode>
<expirationDate>2022/12</expirationDate>
<name>APPROVED</name>
</creditCard>
<extraParameters>
<entry>
<string>INSTALLMENTS_NUMBER</string>
<string>1</string>
</entry>
</extraParameters>
<type>AUTHORIZATION_AND_CAPTURE</type>
<paymentMethod>MASTERCARD</paymentMethod>
<paymentCountry>BR</paymentCountry>
<deviceSessionId>vghs6tvkcle931686k1900o6e1</deviceSessionId>
<ipAddress>127.0.0.1</ipAddress>
<cookie>pt1t38347bs6jc9ruv2ecpv7o2</cookie>
<userAgent>Mozilla/5.0 (Windows NT 5.1; rv:18.0) Gecko/20100101 Firefox/18.0</userAgent>
<threeDomainSecure>
<embedded>false</embedded>
<eci>01</eci>
<cavv>AOvG5rV058/iAAWhssPUAAADFA==</cavv>
<xid>Nmp3VFdWMlEwZ05pWGN3SGo4TDA=</xid>
<directoryServerTransactionId>00000-70000b-5cc9-0000-000000000cb</directoryServerTransactionId>
</threeDomainSecure>
</transaction>
<isTest>false</isTest>
</request>
Response Example:
<paymentResponse>
<code>SUCCESS</code>
<transactionResponse>
<orderId>1400437005</orderId>
<transactionId>5d3cea31-c5e5-4105-9359-984edcaede37</transactionId>
<state>APPROVED</state>
<paymentNetworkResponseCode>6</paymentNetworkResponseCode>
<trazabilityCode>282856</trazabilityCode>
<authorizationCode>MOCK-CIELO-1624047952405</authorizationCode>
<responseCode>APPROVED</responseCode>
<operationDate>2021-06-18T10:25:52</operationDate>
<extraParameters>
<entry>
<string>BANK_REFERENCED_CODE</string>
<string>CREDIT</string>
</entry>
<entry>
<string>CIELO_TID</string>
<string>1006993069000509C28A</string>
</entry>
</extraParameters>
</transactionResponse>
</paymentResponse>
Submit Transactions Using Google Pay
Google Pay is a digital wallet that enables simple and fast card payments, without the need of entering the card data for each payment. The card data is safely stored by Google. This payment method is available for all devices (mobile phones and computers), no matter the operating system and in almost all web browsers.
In case of using Google Pay, the merchants must adhere to the Google Pay APIs Acceptable Use Policy and accept the terms that Google Pay API Terms of Service defines.
Note
The description below applies to provision of this service directly by displaying the Google Pay lightbox at the website of the payment recipient (e-store).If you wish to offer this method via PayU Web-Checkout, no additional integration effort is required. Contact your Key Account Manager to make the activation request. If you wish to test the payment method prior to activation, you can follow the instructions here.
Please note that if your integration with PayU is API, you must change the settings described in this section to process Google Pay transactions:
API Integration of the Payment Method
To integrate the website with the Google Pay wallet, proceed according to the instructions placed at these websites:
PayU Definitions for the API Integration of the Payment Method
Below you will find relevant information that you must consider for your payments to be processed by PayU once the payment method is integrated:
-
Request a Payment Token for PayU
Google encrypts the information of the card selected by the payer for secure processing, this is carried out by a payment provider. The gateway parameter in the script should have the constant value of payulatam, and the gatewayMerchantId should include your PayU account number according to the example below:
const tokenizationSpecification = {
type: 'PAYMENT_GATEWAY',
parameters: {
'gateway': 'payulatam',
'gatewayMerchantId': 'YOUR_ACCOUNT_ID '
}
};
-
Supported Payment Networks
PayU processes Google Pay payments for Mastercard and Visa cards. To configure your Google script, use these settings:
const allowedCardNetworks = ["MASTERCARD", "VISA", "ELECTRON", "MAESTRO"];
const allowedCardAuthMethods = ["PAN_ONLY"];
Note
The availability of payment methods depends on your PayU settings.Google will return a PaymentData object, and the paymentMethodData.tokenizationData.token field will contain a securely encrypted Google Pay Token (a string).
Below, a sample of a Google Pay Token:
{
"protocolVersion":"ECv2",
"signature":"MEUCIG39tbaQPwJe28U+UMsJmxUBUWSkwlOv9Ibohacer+CoAiEA8Wuq3lLUCwLQ06D2kErxaMg3b/oLDFbd2gcFze1zDqU\u003d",
"intermediateSigningKey":{
"signedKey": "{\"keyExpiration\":\"1542394027316\",\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE/1+3HBVSbdv+j7NaArdgMyoSAM43yRydzqdg1TxodSzA96Dj4Mc1EiKroxxunavVIvdxGnJeFViTzFvzFRxyCw\\u003d\\u003d\"}",
"signatures": ["MEYCIQDcXCoB4fYJF3EolxrE2zB+7THZCfKA7cWxSztKceXTCgIhAN/d5eBgx/1A6qKBdH0IS7/aQ7dO4MuEt26OrLCUxZnl"]
},
"signedMessage":"{\"tag\":\"TjkIKzIOvCrFvjf7/aeeL8/FZJ3tigaNnerag68hIaw\\u003d\",\"ephemeralPublicKey\":\"BLJoTmxP2z7M2N6JmaN786aJcT/L/OJfuJKQdIXcceuBBZ00sf5nm2+snxAJxeJ4HYFTdNH4MOJrH58GNDJ9lJw\\u003d\",\"encryptedMessage\":\"mleAf23XkKjj\"}"
}
Process Google Pay Transactions in PayU
The primary function of Google Pay as a digital wallet is to store credit cards to facilitate payment processing. With that in mind, for PayU, the transactions processed by Google Pay will have the same credit card logic except for the following particularities:
- If you are processing transactions of your customers with Google Pay, you should configure the information of the wallet in the parameter
transaction.digitalWallet. - Inside the parameter
transaction.digitalWalletuseGOOGLE_PAYin the fieldtransaction.digitalWallet.typeand send the Google Pay Token in the fieldtransaction.digitalWallet.message. - Take into account that for Google Pay transactions inside the parameter
transaction.creditcard, you should always send a value fortransaction.creditcard.name. Other fields of this parameter are not necessary since Google Pay delivers them inside the token. - Contact your account manager to make the necessary activations to process without cvv as this payment method requires it.
Test the Payment Method
This section is designed to guide users through the testing process and familiarization with the Google Pay payment method in PayU.
Prerequisites (for API and Web Checkout integrations):
- Make sure you are logged in your browser with the Gmail account with which you will be testing.
- Join the Google group in which the test cards for PayU will be available. The group can be found in the following Google documentation.
Testing for Merchants with API Integration:
- Once the changes indicated in the previous sections have been made, use the Token Simulator File to simulate a transaction and obtain a sample of a Google Pay Token. The simulator can be visualized here.
Note
To ensure correct processing, use cards whose name do NOT start with “Test”.- Use the information on the sample of the Google Pay Token to fill out the PayU Request. Send it to PayU to get proof of an approved transaction. If you have results that are not approved, please review the documentation from the steps above.
Testing for Merchants with Web Checkout Integration:
Access PayU Latam Web Checkout in a test environment and simulate a transaction.
Note
- To ensure correct processing, use cards whose name do NOT start with “Test”.
- Use the Brazil test credentials for this test. Consult them here.
API Call
The following are the bodies of the request and response of this payment method.
Request Example:
{
"language": "es",
"command": "SUBMIT_TRANSACTION",
"merchant": {
"apiKey": "012345678901",
"apiLogin": "012345678901"
},
"transaction": {
"order": {
"accountId": "9",
"language": "es",
"description" : "test",
"signature": "{{payu_signature}}",
"referenceCode": "{{payu_ref_code}}",
"additionalValues": {
"TX_VALUE": {
"value": 100,
"currency": "ARS"
}
}
},
"payer": {
"merchantPayerId": "1",
"fullName": "First name and second payer name",
"emailAddress": "payer.name@payu.com",
"contactPhone": "7563126",
"dniNumber": "5415668464654",
"dniType": null
},
"creditCard": {
"name": "Kevin Pelaez"
},
"digitalWallet": {
"type" : "GOOGLE_PAY",
"message" : "{\"signature\":\"MEUCIQCSsfd63AcUEjNRnpgqEm/B6cm8Fna1ty+HatD4Hqp/bgIgHCtrwKhvO1e5K3vDfE6FxqSaRkP9PHuY63aQ35gV5lk\\u003d\",\"intermediateSigningKey\":{\"signedKey\":\"{\\\"keyValue\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAExtzNORa//EJphgvdpUTsDElAg26mYXxNqs8/UX7DDSDCojJ/2+GCf8CVmClyRM+bukNsYM82pwkjZqOe5AOxUg\\\\u003d\\\\u003d\\\",\\\"keyExpiration\\\":\\\"1695147545256\\\"}\",\"signatures\":[\"MEQCIAxxj2BnQzTyTXLzjJ08JG+s1qdmX1XlOxzFmq1THTJ4AiAe7anOO7l+KZ1nkbGBufXBuQGInFMGR70+I33EyCL5GQ\\u003d\\u003d\"]},\"protocolVersion\":\"ECv2\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"GNKqqZ7bx6btPTkZPjpvi1IHKS79JrdtOI3bRZA6G5936ofXqD/m3f/YpuF4mlADkHIhmBYVq6hzyA0B4M1cjht7BFsQhE5fqA+6PgbPY6eAqaH4PPQGt/3VM9uVxmtcJK6k2JL8N7CCF85vx6s+LASH4wwO3Sk2NIlPB0B2QHdfdrOpwo5r6T3xYJAq6wHqFNrdOLq5NTodDqEaXP3y/kB1eIMrwcz5cPGJAPSmL2RebBofsl5QFJdVUmeXXSS7nQ4aeQpuqCcoI/NqLb5r3bEaq33pbglfv2YyyHK1ERlET3TsTR+rGBcJXv9JLh2ZhdoUJYDkDqP+f+65Fn3/xRppfXbwNCrCnO+DvVsgZTFp7cj69WA6uWBeYM4HejKa1BUpt8TfP132FjaUSnwSlykkJhHK5svQFxf2rpJGFdmz4d06iLREy/N+27pyE9eJeJohO2JJXaVTQgICmVNvGefR4KaNELpxeNAzuhKQsTZBYQY179zveNg4EQqai3CxKIr09G/MwpMufTWEBm2rsk6HqTh1Qz+d72aph3U3bRQVhFj3ZE2ZsIXIc7dwCLGV\\\",\\\"ephemeralPublicKey\\\":\\\"BNgz4XETGJgixJYrYHLXjQrRaZ9i2q2Z2uGTOFNuVY5ZiCFiSJeiP0l+dt+Y0r8I29l5F2Lwd+e8torE3vSMm9g\\\\u003d\\\",\\\"tag\\\":\\\"NUJPbcTwbfWBC3ByHzcwQz/bEsbt80vh1ahXoRY4xAQ\\\\u003d\\\"}\"}"
},
"extraParameters": {
"INSTALLMENTS_NUMBER": 1
},
"type": "AUTHORIZATION_AND_CAPTURE",
"paymentMethod": "MASTERCARD",
"paymentCountry": "BR"
},
"test": false
}
Response Example:
{
"code": "SUCCESS",
"error": null,
"transactionResponse": {
"orderId": 1400437001,
"transactionId": "f0f8c441-43e8-490a-b4f2-c14d2c403175",
"state": "APPROVED",
"paymentNetworkResponseCode": "6",
"paymentNetworkResponseErrorMessage": null,
"trazabilityCode": "282856",
"authorizationCode": "MOCK-CIELO-1624047897817",
"pendingReason": null,
"responseCode": "APPROVED",
"errorCode": null,
"responseMessage": null,
"transactionDate": null,
"transactionTime": null,
"operationDate": 1624029898077,
"referenceQuestionnaire": null,
"extraParameters": {
"BANK_REFERENCED_CODE": "CREDIT",
"CIELO_TID": "1006993069000509C28A"
},
"additionalInfo": null
}
}
Request Example:
<request>
<language>es</language>
<command>SUBMIT_TRANSACTION</command>
<merchant>
<apiKey>012345678901</apiKey>
<apiLogin>012345678901</apiLogin>
</merchant>
<transaction>
<order>
<accountId>9</accountId>
<language>es</language>
<description>test</description>
<signature>{{payu_signature}}</signature>
<referenceCode>{{payu_ref_code}}</referenceCode>
<additionalValues>
<TX_VALUE>
<value>100</value>
<currency>ARS</currency>
</TX_VALUE>
</additionalValues>
</order>
<payer>
<merchantPayerId>1</merchantPayerId>
<fullName>First name and second payer name</fullName>
<emailAddress>payer.name@payu.com</emailAddress>
<contactPhone>7563126</contactPhone>
<dniNumber>5415668464654</dniNumber>
<dniType></dniType>
</payer>
<creditCard>
<name>Kevin Pelaez</name>
</creditCard>
<digitalWallet>
<type>GOOGLE_PAY</type>
<message>{"signature":"MEUCIQCSsfd63AcUEjNRnpgqEm/B6cm8Fna1ty+HatD4Hqp/bgIgHCtrwKhvO1e5K3vDfE6FxqSaRkP9PHuY63aQ35gV5lk\u003d","intermediateSigningKey":{"signedKey":"{\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAExtzNORa//EJphgvdpUTsDElAg26mYXxNqs8/UX7DDSDCojJ/2+GCf8CVmClyRM+bukNsYM82pwkjZqOe5AOxUg\\u003d\\u003d\",\"keyExpiration\":\"1695147545256\"}","signatures":["MEQCIAxxj2BnQzTyTXLzjJ08JG+s1qdmX1XlOxzFmq1THTJ4AiAe7anOO7l+KZ1nkbGBufXBuQGInFMGR70+I33EyCL5GQ\u003d\u003d"]},"protocolVersion":"ECv2","signedMessage":"{\"encryptedMessage\":\"GNKqqZ7bx6btPTkZPjpvi1IHKS79JrdtOI3bRZA6G5936ofXqD/m3f/YpuF4mlADkHIhmBYVq6hzyA0B4M1cjht7BFsQhE5fqA+6PgbPY6eAqaH4PPQGt/3VM9uVxmtcJK6k2JL8N7CCF85vx6s+LASH4wwO3Sk2NIlPB0B2QHdfdrOpwo5r6T3xYJAq6wHqFNrdOLq5NTodDqEaXP3y/kB1eIMrwcz5cPGJAPSmL2RebBofsl5QFJdVUmeXXSS7nQ4aeQpuqCcoI/NqLb5r3bEaq33pbglfv2YyyHK1ERlET3TsTR+rGBcJXv9JLh2ZhdoUJYDkDqP+f+65Fn3/xRppfXbwNCrCnO+DvVsgZTFp7cj69WA6uWBeYM4HejKa1BUpt8TfP132FjaUSnwSlykkJhHK5svQFxf2rpJGFdmz4d06iLREy/N+27pyE9eJeJohO2JJXaVTQgICmVNvGefR4KaNELpxeNAzuhKQsTZBYQY179zveNg4EQqai3CxKIr09G/MwpMufTWEBm2rsk6HqTh1Qz+d72aph3U3bRQVhFj3ZE2ZsIXIc7dwCLGV\",\"ephemeralPublicKey\":\"BNgz4XETGJgixJYrYHLXjQrRaZ9i2q2Z2uGTOFNuVY5ZiCFiSJeiP0l+dt+Y0r8I29l5F2Lwd+e8torE3vSMm9g\\u003d\",\"tag\":\"NUJPbcTwbfWBC3ByHzcwQz/bEsbt80vh1ahXoRY4xAQ\\u003d\"}"}</message>
</digitalWallet>
<extraParameters>
<INSTALLMENTS_NUMBER>1</INSTALLMENTS_NUMBER>
</extraParameters>
<type>AUTHORIZATION_AND_CAPTURE</type>
<paymentMethod>MASTERCARD</paymentMethod>
<paymentCountry>BR</paymentCountry>
</transaction>
<test>false</test>
</request>
Response Example:
<paymentResponse>
<code>SUCCESS</code>
<error></error>
<transactionResponse>
<orderId>1400437001</orderId>
<transactionId>f0f8c441-43e8-490a-b4f2-c14d2c403175</transactionId>
<state>APPROVED</state>
<paymentNetworkResponseCode>6</paymentNetworkResponseCode>
<paymentNetworkResponseErrorMessage></paymentNetworkResponseErrorMessage>
<trazabilityCode>282856</trazabilityCode>
<authorizationCode>MOCK-CIELO-1624047897817</authorizationCode>
<pendingReason></pendingReason>
<responseCode>APPROVED</responseCode>
<errorCode></errorCode>
<responseMessage></responseMessage>
<transactionDate></transactionDate>
<transactionTime></transactionTime>
<operationDate>1624029898077</operationDate>
<referenceQuestionnaire></referenceQuestionnaire>
<extraParameters>
<BANK_REFERENCED_CODE>CREDIT</BANK_REFERENCED_CODE>
<CIELO_TID>1006993069000509C28A</CIELO_TID>
</extraParameters>
<additionalInfo></additionalInfo>
</transactionResponse>
</paymentResponse>
You will find the description of the transaction.digitalWallet object and its fields in the section Parameters.
Submit Transactions Using PIX
This method lets you process payments using PIX. To integrate with PIX you need to show in your checkout page a QR code so your customer can read it using their smartphone to perform the payment.
In the end, your customer sees a checkout page like this.
How Does PIX Work?
PIX is an online transfer method released in November, 2020 by the Brazilian Central Bank (Banco Central do Brasil - BACEN) which allows you make and receive transfers easily regardless of the bank who issued your account.
Unlike other cash and bank transfer methods, PIX allows you to receive transfers immediately without sharing your account number; at any time, on any day. The funds received using this payment method will appear in your PayU account in a matter of seconds.
Pix has two parts:
-
PIX key: unique identifier of a banking or payment account in the Brazilian Banking System. Your key can be generated using any of the following values:
- Tax ID (CPF or CNPJ).
- Phone number
- Random key
-
QR code: this code is read by your customer using their phone and performs the payment.
Parameters for Request and Response
Request
| Field Name | Format | Size | Description | Mandatory |
|---|---|---|---|---|
| language | Alphanumeric | 2 | Language used in the request, this language is used to display the error messages generated. See supported languages. | Yes |
| command | Alphanumeric | Max:32 | Set SUBMIT_TRANSACTION. |
Yes |
| test (JSON) isTest (XML) |
Boolean | Set true if the request is in test mode. Otherwise, set false. |
Yes | |
| merchant | Object | This object has the authentication data. | Yes | |
| merchant > apiLogin | Alphanumeric | Min:12 Max:32 | User or login provided by PayU. How do I get my API Login | Yes |
| merchant > apiKey | Alphanumeric | Min:6 Max:32 | Password provided by PayU. How do I get my API Key | Yes |
| transaction | Object | This object has the transaction data. | Yes | |
| transaction > order | Object | This object has the order data. | Yes | |
| transaction > order > accountId | Number | Identifier of your account. | Yes | |
| transaction > order > referenceCode | Alphanumeric | Min:1 Max:255 | Represents the identifier of the order in your system. | Yes |
| transaction > order > description | Alphanumeric | Min:1 Max:255 | Description of the order. | Yes |
| transaction > order > language | Alphanumeric | 2 | Language used in emails sent to the buyer and the seller. | Yes |
| transaction > order > notifyUrl | Alphanumeric | Max:2048 | Confirmation URL of the order. | Yes |
| transaction > order > partnerId | Alphanumeric | Max:255 | Partner ID in PayU. | No |
| transaction > order > signature | Alphanumeric | Max:255 | The signature associated to the form. For more information refer Authentication signature. | Yes |
| transaction > order > shippingAddress | Object | Shipping address. | No | |
| transaction > order > shippingAddress > street1 | Alphanumeric | Max:100 | Address Line 1. | No |
| transaction > order > shippingAddress > street2 | Alphanumeric | Max:100 | Address Line 2. | No |
| transaction > order > shippingAddress > city | Alphanumeric | Max:50 | Address city. | No |
| transaction > order > shippingAddress > state | Alphanumeric | Max:40 | Address State. For Brazil, only send two characters, For example, set SP for São Paulo. |
No |
| transaction > order > shippingAddress > country | Alphanumeric | 2 | Address country. | No |
| transaction > order > shippingAddress > postalCode | Alphanumeric | Max:8 | Address Zip code. For Brazil, use the format XXXXX-XXX or XXXXXXXX. Example: 09210-710 or 09210710. |
No |
| transaction > order > shippingAddress > phone | Alphanumeric | Max:11 | Phone number associated to the address. For Brazil, use the format ddd(2)+number(7-9). Example: (11)756312633. |
No |
| transaction > order > buyer | Object | Buyer information. | Yes | |
| transaction > order > buyer > merchantBuyerId | Alphanumeric | Max:100 | Buyer ID in your system. | No |
| transaction > order > buyer > fullName | Alphanumeric | Max:150 | Full name of the buyer. | Yes |
| transaction > order > buyer > emailAddress | Alphanumeric | Max:255 | E-mail of the buyer. | Yes |
| transaction > order > buyer > contactPhone | Alphanumeric | Max:20 | Phone number of the buyer. | Yes |
| transaction > order > buyer > dniType | Alphanumeric | Max:20 | Identification type of the buyer. See Document types. | Yes |
| transaction > order > buyer > dniNumber | Alphanumeric | Max:20 | Identification number of the buyer. You must use an algorithm to validate the CPF and must be set using the format XXX.XXX.XXX-XX. Example: 811.807.405-64. |
Yes |
| transaction > order > buyer > cnpj | Alphanumeric | Max:14 | Identification number of the buyer (For Legal person in Brazil). You must use an algorithm to validate the CNPJ and must be set using the format XXXXXXXXXXXXXX. Example: 32593371000110. |
Yes |
| transaction > order > buyer > shippingAddress | Alphanumeric | Shipping address of the buyer. | No | |
| transaction > order > buyer > shippingAddress > street1 | Alphanumeric | Max:150 | Buyer’s shipping address Line 1. | No |
| transaction > order > buyer > shippingAddress > city | Alphanumeric | Max:50 | Buyer’s shipping address city. | No |
| transaction > order > buyer > shippingAddress > state | Alphanumeric | Max:40 | Buyer’s shipping address state. For Brazil, only send two characters, For example, set SP for São Paulo. |
No |
| transaction > order > buyer > shippingAddress > country | Alphanumeric | 2 | Buyer’s shipping address country in format ISO 3166 alpha-2. | No |
| transaction > order > buyer > shippingAddress > postalCode | Number | Max:20 | Buyer’s shipping address zip code. For Brazil, use the format XXXXX-XXX or XXXXXXXX. Example: 09210-710 or 09210710. |
No |
| transaction > order > buyer > shippingAddress > phone | Number | Max:20 | Buyer’s shipping address phone number. For Brazil, use the format ddd(2)+number(7-9). Example: (11)756312633. |
No |
| transaction > order > additionalValues > | Object | 64 | Amount of the order or its associated values. | Yes |
| transaction > order > additionalValues > TX_VALUE | Alphanumeric | 64 | Amount of the transaction. | Yes |
| transaction > order > additionalValues > TX_VALUE > value | Number | 12, 2 | Specifies the amount of the transaction, this value may have two decimal digits (Ex. 10000.00 or 10000). |
Yes |
| transaction > order > additionalValues > TX_VALUE > currency | Alphanumeric | 3 | ISO code of the currency. See accepted currencies. | Yes |
| transaction > order > additionalValues > TX_TAX | Alphanumeric | 64 | Amount of the Value Added Tax (VAT). | No |
| transaction > order > additionalValues > TX_TAX > value | Number | 12, 2 | Specifies the amount of the VAT. | No |
| transaction > order > additionalValues > TX_TAX > currency | Alphanumeric | 3 | ISO code of the currency. See accepted currencies. | No |
| transaction > order > additionalValues > TX_TAX_RETURN_BASE | Alphanumeric | 64 | Base value to calculate the VAT. If the amount does not have IVA, send 0. This value may have two decimal digits. |
No |
| transaction > order > additionalValues > TX_TAX_RETURN_BASE > value | Number | 12, 2 | Specifies the base amount of the transaction. | No |
| transaction > order > additionalValues > TX_TAX_RETURN_BASE > currency | Alphanumeric | 3 | ISO code of the currency. See accepted currencies. | No |
| transaction > payer | Objeto | Payer information. | Yes | |
| transaction > payer > emailAddress | Alphanumeric | Max:255 | Payer e-mail address. | No |
| transaction > payer > merchantPayerId | Alphanumeric | Max:100 | Identifier of the payer in your system. | No |
| transaction > payer > fullName | Alphanumeric | Max:150 | Name of the payer. | Yes |
| transaction > payer > billingAddress | Object | Billing address. | No | |
| transaction > payer > billingAddress > street1 | Alphanumeric | Max:100 | Billing Address Line 1. | No |
| transaction > payer > billingAddress > street2 | Alphanumeric | Max:100 | Billing Address Line 2. | No |
| transaction > payer > billingAddress > city | Alphanumeric | Max:50 | Billing address city. | No |
| transaction > payer > billingAddress > state | Alphanumeric | Max:40 | Billing address state. For Brazil, only send two characters, For example, set SP for São Paulo. |
No |
| transaction > payer > billingAddress > country | Alphanumeric | 2 | Billing address country in format ISO 3166 Alpha-2. | No |
| transaction > payer > billingAddress > postalCode | Alphanumeric | Max:20 | Billing address zip code. For Brazil, use the format XXXXX-XXX or ´. Example: 09210-710 or 09210710. |
No |
| transaction > payer > billingAddress > phone | Alphanumeric | Max:20 | Billing address phone number. For Brazil, use the format ddd(2)+number(7-9). Example: (11)756312633. |
No |
| transaction > payer > birthdate | Alphanumeric | Max:10 | Payer’s date of birth. | No |
| transaction > payer > contactPhone | Alphanumeric | Max:20 | Payer’s phone number. For Brazil, use the format ddd(2)+number(7-9). Example: (11)756312633. |
Yes |
| transaction > payer > dniNumber | Alphanumeric | Max:20 | Identification number of the buyer. You must use an algorithm to validate the CPF and must be set using the format XXX.XXX.XXX-XX. Example: 811.807.405-64. |
Yes |
| transaction > payer > cnpj | Alphanumeric | Max:14 | Identification number of the buyer (For Legal person in Brazil). You must use an algorithm to validate the CNPJ and must be set using the format XXXXXXXXXXXXXX. Example: 32593371000110. |
No |
| transaction > payer > dniType | Alphanumeric | 2 | Identification type of the buyer. See Document types. | Yes |
| transaction > type | Alphanumeric | 32 | As PIX payments are performed using the payer mobile phone, the only available transaction type is AUTHORIZATION_AND_CAPTURE. |
Yes |
| transaction > paymentMethod | Alphanumeric | 32 | Set PIX for this payment method. If you want to see other payment method, refer to Payment Methods for Brazil. |
Yes |
| transaction > paymentCountry | Alphanumeric | 2 | Set BR for Brazil. |
Yes |
| transaction > deviceSessionId | Alphanumeric | Max:255 | Session identifier of the device where the customer performs the transaction. For more information, refer to this topic. | No |
| transaction > ipAddress | Alphanumeric | Max:39 | IP address of the device where the customer performs the transaction. | Yes |
| transaction > extraParameters | Object | Additional parameters or data associated with the request. The maximum size of each extraParameters name is 64 characters. In JSON, the extraParameters parameter follows this structure: "extraParameters": {"PARAMETER_NAME": "VALUE"}In XML, the extraParameters parameter follows this structure: <extraParameters><entry><string>PARAMETER_NAME</string><string>VALUE</string></entry></extraParameters>Set the respective data type |
No |
Response
| Field Name | Format | Size | Description |
|---|---|---|---|
| code | Alphanumeric | The response code of the transaction. Possible values are ERROR and SUCCESS. |
|
| error | Alphanumeric | Max:2048 | The error message associated when the response code is ERROR. |
| transactionResponse | Object | The response data. | |
| transactionResponse > orderId | Number | The generated or existing order Id in PayU. | |
| transactionResponse > transactionId | Alphanumeric | 36 | The identifier of the transaction in PayU. |
| transactionResponse > state | Alphanumeric | Max:32 | The status of the transaction. As the payment is performed by the user in their phone, the state for a successful transaction is PENDING |
| transactionResponse > paymentNetworkResponseCode | Alphanumeric | Max:255 | The response code returned by the financial network. |
| transactionResponse > paymentNetworkResponseErrorMessage | Alphanumeric | Max:255 | The error message returned by the financial network. |
| transactionResponse > trazabilityCode | Alphanumeric | Max:32 | The traceability code returned by the financial network. |
| transactionResponse > authorizationCode | Alphanumeric | Max:12 | The authorization code returned by the financial network. |
| transactionResponse > pendingReason | Alphanumeric | Max:21 | The reason code associated with the status, as mentioned in transactionResponse > state, the transaction is waiting for the payment. |
| transactionResponse > responseCode | Alphanumeric | Max:64 | The response code associated with the status. In this case, for successful transactions is PENDING_PAYMENT_IN_ENTITY. |
| transactionResponse > responseMessage | Alphanumeric | Max:2048 | Message associated with the response code. |
| transactionResponse > operationDate | Date | Creation date of the response in the PayU´s system. | |
| transactionResponse > extraParameters | Object | Additional parameters or data associated with the response. In JSON, the extraParameters parameter follows this structure: "extraParameters": {"EXPIRATION_DATE": "1627488070000"}In XML, the extraParameters parameter follows this structure: <extraParameters><entry><string>EXPIRATION_DATE</string><int>1627488070000</int></entry></extraParameters> |
Considerations
- Payments processed through our gateway will be for PayU on behalf of your commerce.
- If your commerce does not have a local entity, it is mandatory to send either the CPF (parameter
transaction.[payer|buyer].dniNumber) or the CNPJ (parametertransaction.[payer|buyer].cnpj). - To configure the expiration time of the QR code, contact your sales representative. The maximum time you can request is one day.
By default, the expiration time is two (2) hours. - The minimum amount you can process with PIX is R$ 1.00, the maximum amount depends on your customer and their bank.
- The parameter
transaction.payer.fullNameis mandatory to create the request. - The QR code and the PIX key used to receive payments is generated by PayU, it is not supported to configure your own QR code nor PIX key. Nevertheless, the total of the transaction minus the commission fee is transferred to your PayU account.
- To query an active code of your transaction, use the Queries API.
- The parameter
transactionResponse.extraParametershas the following parameters related to the transaction:- EXPIRATION_DATE: deadline to make the payment.
- QRCODE_EMV: code to be pasted in the bank portal to perform the payment. This code is used when the customer cannot read the QR code.
- QRCODE_IMAGE_BASE64: image of the QR code. This is a string codified in Base64.
Note
It is recommended to display in your Checkout both the image of the QR code (parameterQRCODE_IMAGE_BASE64 decoded) and the string of the code (parameter QRCODE_EMV) to avoid payment desertions.
API Call
The following are the bodies of the request and response of this payment method.
Request Example:
{
"language": "pt",
"command": "SUBMIT_TRANSACTION",
"merchant": {
"apiKey": "4Vj8eK4rloUd272L48hsrarnUA",
"apiLogin": "pRRXKOl8ikMmt9u"
},
"transaction": {
"order": {
"accountId": "512327",
"referenceCode": "PRODUCT_TEST_2021-06-17T19:11:57.179Z",
"description": "Payment test description",
"language": "pt",
"signature": "fbc089272288edc52c332395d9566f4c",
"notifyUrl": "http://www.payu.com/notify",
"additionalValues": {
"TX_VALUE": {
"value": 1000,
"currency": "BRL"
}
},
"buyer": {
"merchantBuyerId": "1",
"fullName": "First name and second buyer name",
"emailAddress": "buyer_test@test.com",
"contactPhone": "7563126",
"dniNumber": "811.807.405-64",
"cnpj": "32593371000110",
"shippingAddress": {
"street1": "Quadra QNP 34 Conjunto G 780",
"street2": "5555487",
"city": "Manaos",
"state": "SP",
"country": "BR",
"postalCode": "10012545",
"phone": "(11)756312633"
}
},
"shippingAddress": {
"street1": "Quadra QNP 34 Conjunto G 780",
"street2": "5555487",
"city": "Manaos",
"state": "SP",
"country": "BR",
"postalCode": "10012545",
"phone": "(11)756312633"
}
},
"payer": {
"fullName":"Payer Name",
"emailAddress": "buyer_test@test.com",
"contactPhone": "55 12345678901",
"dniType": "CPF",
"dniNumber": "653.098.319-83"
},
"type": "AUTHORIZATION_AND_CAPTURE",
"paymentMethod": "PIX",
"paymentCountry": "BR",
"ipAddress": "127.0.0.1"
},
"test": false
}
Response Example:
{
"code": "SUCCESS",
"error": null,
"transactionResponse": {
"orderId": 120000260,
"transactionId": "e82ace4c-647b-457d-b4f5-136c921445b6",
"state": "PENDING",
"paymentNetworkResponseCode": null,
"paymentNetworkResponseErrorMessage": null,
"trazabilityCode": "9c7d3f2d-6c2c-436c-a06d-e6f99271ff3f",
"authorizationCode": null,
"pendingReason": "AWAITING_PAYMENT_IN_ENTITY",
"responseCode": "PENDING_PAYMENT_IN_ENTITY",
"errorCode": null,
"responseMessage": null,
"transactionDate": null,
"transactionTime": null,
"operationDate": 1627473671920,
"referenceQuestionnaire": null,
"extraParameters": {
"EXPIRATION_DATE": 1627488070000,
"QRCODE_EMV": "00020101021126950014BR.GOV.BCB.PIX2573spi.dev.cloud.itau.com.br/documentos/198e49c5-2330-4ad7-9d0b-967c7b5371225204000053039865802BR5923PMD Gotham NegA cios ME6009SAO PAULO62410503***50300017BR.GOV.BCB.BRCODE01051.0.063040866",
"QRCODE_IMAGE_BASE64": "iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6AQAAAACgl2eQAAADCUlEQVR4Xu2XUW4cIRBE6YvA/W+Ro8BFIPWKsWU5kpWPbOVn8SaZhWep1F1dTNr5ef1q33e+rTdw1xu466+A2VqtXbuP3etMPY9zlrdjwPLnrNm1NceaNXtv426nAOliqw5K+1io3IBhoFyZsWuaE/UfgM1h0xpzTMqUBfRxXZB2ONylhy/Nej0wMe2fi+0Y4KUend1omcZHR7vufgigNMzLEDXFbL63Pj6bFQBkld57MS0KkEWfdhOg3sWAI0mYRUIJMkvGwq5VCJhWtwkwAWoXIcJvjRxw9WnL/YKQWxejPGKAxvZgEHWoBKlhErztmBhgafaMXCtqWKVDJQYc2oNndY5llncEspUDlOFFrXRA23QiUl9jwB7aPvhkoE5UGeQxBlyFLEaXCbrW+XT16wGe9Kcsk25JsH/oWgjw9PbGge+ysdAtgRAhwNm1iW+rXN5pV2oMuEaVTHlXL30iFaySXU+hAsBGpJulzAAclE3geEQGAIzCfcKrFv7VEVna3LAQMIcNyiue7lKSg1ppQ0OcAshPWWT4amNtarb4GgN8qcmwvlAk8qNRtC4GuEVKLn13fKlUUuxepQC+C9NWJ9ZlHRu5iLMUMPGrdhkZLKwLpvQfoXvXhoCDzsZP0beFgagefgkC0yWiVbxqFBmmn/Xh6tcDyxnGtUpskJ/Mb0dpDGBQnSJSJ7NKHYahaR+Fej3wWMSqMI/+Utmkmm6lgCewfICwmyPdHg4BGtRBkHp+m29VqbPyHCCPKL+pFzpJUiZIep9CBQAnOZ+nQwu3TP8bAybjqvJgkyI+DjLF07gQ4M5wXEibvtod5u0RGQDYKhhZFX3ca9hYuRID9GbDidql+kgt/eKCpYMpwGaVIAZGAaKObZyL1BygxTMgMUKXuOEXbQwBFEWaOt4tusQW/eKXQsDic0vE+17njA4SrjFg8n43XCwbZQsdfooCC4eSJJoXJVkRYJ/NSgHEOBIJ8wtYeAzQh0HpCjLop3GDeU4BtEU2kUpXR1YhQqlXDvhxvYG73sBd/wD4Df7+v4eqIoYgAAAAAElFTkSuQmCC"
},
"additionalInfo": null
}
}
Request Example:
<request>
<language>pt</language>
<command>SUBMIT_TRANSACTION</command>
<merchant>
<apiKey>4Vj8eK4rloUd272L48hsrarnUA</apiKey>
<apiLogin>pRRXKOl8ikMmt9u</apiLogin>
</merchant>
<transaction>
<order>
<accountId>512327</accountId>
<referenceCode>PRODUCT_TEST_2021-06-17T19:11:57.179Z</referenceCode>
<description>payment test</description>
<language>pt</language>
<signature>fbc089272288edc52c332395d9566f4c</signature>
<notifyUrl>http://www.payu.com/notify</notifyUrl>
<additionalValues>
<entry>
<string>TX_VALUE</string>
<additionalValue>
<value>1000</value>
<currency>BRL</currency>
</additionalValue>
</entry>
</additionalValues>
<buyer>
<contactPhone>7563126</contactPhone>
<dniNumber>811.807.405-64</dniNumber>
<cnpj>32593371000110</cnpj>
<emailAddress>buyer_test@test.com</emailAddress>
<fullName>First name and second buyer name</fullName>
<merchantBuyerId>1</merchantBuyerId>
<shippingAddress>
<street1>Quadra QNP 34 Conjunto G 780</street1>
<street2>5555487</street2>
<city>Manaos</city>
<state>SP</state>
<country>BR</country>
<postalCode>10012545</postalCode>
<phone>7563126</phone>
</shippingAddress>
</buyer>
<shippingAddress>
<street1>Quadra QNP 34 Conjunto G 780</street1>
<street2>5555487</street2>
<city>Manaos</city>
<state>SP</state>
<country>BR</country>
<postalCode>10012545</postalCode>
<phone>7563126</phone>
</shippingAddress>
</order>
<payer>
<contactPhone>55 12345678901</contactPhone>
<dniNumber>653.098.319-83</dniNumber>
<dniType>CPF</dniType>
<emailAddress>buyer_test@test.com</emailAddress>
<fullName>Payer Name</fullName>
</payer>
<type>AUTHORIZATION_AND_CAPTURE</type>
<paymentMethod>PIX</paymentMethod>
<paymentCountry>BR</paymentCountry>
<deviceSessionId>vghs6tvkcle931686k1900o6e</deviceSessionId>
<ipAddress>127.0.0.1</ipAddress>
<cookie>pt1t38347bs6jc9ruv2ecpv7o2</cookie>
<userAgent>Mozilla/5.0 (Windows NT 5.1; rv:18.0) Gecko/20100101 Firefox/18.0</userAgent>
</transaction>
<isTest>false</isTest>
</request>
Response Example:
<paymentResponse>
<code>SUCCESS</code>
<transactionResponse>
<orderId>1181965893</orderId>
<transactionId>8397992b-3717-49c5-92ee-345a65ff13cf</transactionId>
<state>PENDING</state>
<trazabilityCode>e0a52a20-6ae2-4970-9b81-47f208bbf40e</trazabilityCode>
<pendingReason>AWAITING_NOTIFICATION</pendingReason>
<responseCode>PENDING_TRANSACTION_CONFIRMATION</responseCode>
<operationDate>2021-10-08T12:14:15</operationDate>
<extraParameters>
<entry>
<string>EXPIRATION_DATE</string>
<date>2021-10-08T18:14:13</date>
</entry>
<entry>
<string>QRCODE_EMV</string>
<string>00020101021226770014BR.GOV.BCB.PIX2555api.itau/pix/qr/v2/8ccd84ae-0c8d-4f71-8abf-b676a666bf9f5204000053039865802BR5911PAYU BRASIL6009SAO PAULO62070503***6304E404</string>
</entry>
<entry>
<string>QRCODE_IMAGE_BASE64</string>
<string>iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6AQAAAACgl2eQAAAC0ElEQVR4Xu2XW27cMAxFpY1I+99FlyJtRO45VFIrUyDoR8z+DDEPj3QMMCTvlVOu7+NXeV15iTew4w3seAM7/g0YpdTJ92p1lTpKveY1XUwE2JyT3TnnqF6WFnd4UxowKq/R56qrldZH68uVfIDc+mqktyBb/w/A6vSMXtms0kePxUyAl79t2AVKyWYsJgIxtK/x11S/xs8CH0GOrJEh7+WmkQWMPpjW3aWYFybY8b3/iucBqtLwjn4txsWSIRs13BMB80E2zqrqoUyle08qQFV6zK0UqfpuXiYC5OQu9sXqMmGRW7wJwBykMxCuWdosb6Fcf5JMAJAMFo5e9HFHZtvaXagEYG7n4kDzHMHRi656NCsBcErJLIQLZc56+t2sDECJ+IF1TWNtI7uTfB64LEswJQR8sYV4j24+Dww9nCeLzzpFo0LHeQCIBO8aEtZYQ0KJgJ4pwsB4qpic2rGFaYC9Kj5k9Rk1o2DSIxMgIxdCL2SMlTq+425WBjCqZ5idwkb57ZeLiYBaoVlLH9lDIzcPdT8PRJkUSkiG3OJ4+9KsxwH2PE/YVi+OjeI5DpQEYDgmJQ73poThMNR1NOt5YKqZmFObxMfSQ5RPHsCkVPfYIMsisLwjE2BqL/eKeZmxvZqHeBOAuX8iGZKjT1g5rTqb9TzADu5hTvYo3ItUj2YlAGywHk3D08ltWKuzks8DeNfSwxwUL6NSX9X9PIBtqBpey+cM9snbtTzg2koZrkz/K3OM19ms5wHr08JM9fHqR+vx+J0IOKXTXTanQ4yU0dGVCAwFa5rVR4zlBb/5SAQMc3R6PelXqGee4n0cMKHl814Ixvy63j4yAdKbnufD2iiYj/M1FRjhGaGd4qMO8/qlWUlAjE1MK7BCqldEJqBfUCwa5NV0fpZMGhDNas2xwTlIUU87zDwBiMZooFZIIYsq4UTgu3gDO97Ajjew4weA30GD9ELLE47fAAAAAElFTkSuQmC</string>
</entry>
</extraParameters>
</transactionResponse>
</paymentResponse>
Submit Transactions Using Cash
This method lets you process the payments in cash of your customers. To integrate with cash transactions, you must redirect the customer to the URL found in the response of the method; your customer sees a payment receipt like this.
Parameters for Request and Response
Request
| Field Name | Format | Size | Description | Mandatory |
|---|---|---|---|---|
| language | Alphanumeric | 2 | Language used in the request, this language is used to display the error messages generated. See supported languages. | Yes |
| command | Alphanumeric | Max:32 | Set SUBMIT_TRANSACTION. |
Yes |
| test (JSON) isTest (XML) |
Boolean | Set true if the request is in test mode. Otherwise, set false. |
Yes | |
| merchant | Object | This object has the authentication data. | Yes | |
| merchant > apiLogin | Alphanumeric | Min:12 Max:32 | User or login provided by PayU. How do I get my API Login | Yes |
| merchant > apiKey | Alphanumeric | Min:6 Max:32 | Password provided by PayU. How do I get my API Key | Yes |
| transaction | Object | This object has the transaction data. | Yes | |
| transaction > order | Object | This object has the order data. | Yes | |
| transaction > order > accountId | Number | Identifier of your account. | Yes | |
| transaction > order > referenceCode | Alphanumeric | Min:1 Max:255 | Represents the identifier of the order in your system. | Yes |
| transaction > order > description | Alphanumeric | Min:1 Max:255 | Description of the order. | Yes |
| transaction > order > language | Alphanumeric | 2 | Language used in emails sent to the buyer and the seller. | Yes |
| transaction > order > notifyUrl | Alphanumeric | Max:2048 | Confirmation URL of the order. | Yes |
| transaction > order > partnerId | Alphanumeric | Max:255 | Partner ID in PayU. | Yes |
| transaction > order > signature | Alphanumeric | Max:255 | The signature associated to the form. For more information refer Authentication signature. | Yes |
| transaction > order > shippingAddress | Object | Shipping address. | No | |
| transaction > order > shippingAddress > street1 | Alphanumeric | Max:100 | Address Line 1. | No |
| transaction > order > shippingAddress > street2 | Alphanumeric | Max:100 | Address Line 2. | No |
| transaction > order > shippingAddress > city | Alphanumeric | Max:50 | Address city. | No |
| transaction > order > shippingAddress > state | Alphanumeric | Max:40 | Address State. For Brazil, only send two characters, For example, set SP for São Paulo. |
No |
| transaction > order > shippingAddress > country | Alphanumeric | 2 | Address country. | No |
| transaction > order > shippingAddress > postalCode | Alphanumeric | Max:8 | Address Zip code. For Brazil, use the format XXXXX-XXX or XXXXXXXX. Example: 09210-710 or 09210710. |
No |
| transaction > order > shippingAddress > phone | Alphanumeric | Max:11 | Phone number associated to the address. For Brazil, use the format ddd(2)+number(7-9). Example: (11)756312633. |
No |
| transaction > order > buyer | Object | Buyer information. | Yes | |
| transaction > order > buyer > merchantBuyerId | Alphanumeric | Max:100 | Buyer ID in your system. | No |
| transaction > order > buyer > fullName | Alphanumeric | Max:150 | Full name of the buyer. | Yes |
| transaction > order > buyer > emailAddress | Alphanumeric | Max:255 | E-mail of the buyer. | Yes |
| transaction > order > buyer > contactPhone | Alphanumeric | Max:20 | Phone number of the buyer. | Yes |
| transaction > order > buyer > dniNumber | Alphanumeric | Max:20 | Identification number of the buyer. You must use an algorithm to validate the CPF and must be set using the format XXX.XXX.XXX-XX. Example: 811.807.405-64. |
Yes |
| transaction > order > buyer > cnpj | Alphanumeric | Max:14 | Identification number of the buyer (For Legal person in Brazil). You must use an algorithm to validate the CNPJ and must be set using the format XXXXXXXXXXXXXX. Example: 32593371000110. |
Yes |
| transaction > order > buyer > shippingAddress | Alphanumeric | Shipping address of the buyer. | Yes | |
| transaction > order > buyer > shippingAddress > street1 | Alphanumeric | Max:150 | Buyer’s shipping address Line 1. | Yes |
| transaction > order > buyer > shippingAddress > city | Alphanumeric | Max:50 | Buyer’s shipping address city. | Yes |
| transaction > order > buyer > shippingAddress > state | Alphanumeric | Max:40 | Buyer’s shipping address state. For Brazil, only send two characters, For example, set SP for São Paulo. |
Yes |
| transaction > order > buyer > shippingAddress > country | Alphanumeric | 2 | Buyer’s shipping address country in format ISO 3166 alpha-2. | Yes |
| transaction > order > buyer > shippingAddress > postalCode | Number | Max:20 | Buyer’s shipping address zip code. For Brazil, use the format XXXXX-XXX or XXXXXXXX. Example: 09210-710 or 09210710. |
Yes |
| transaction > order > buyer > shippingAddress > phone | Number | Max:20 | Buyer’s shipping address phone number. For Brazil, use the format ddd(2)+number(7-9). Example: (11)756312633. |
Yes |
| transaction > order > additionalValues > | Object | 64 | Amount of the order or its associated values. | Yes |
| transaction > order > additionalValues > TX_VALUE | Alphanumeric | 64 | Amount of the transaction. | Yes |
| transaction > order > additionalValues > TX_VALUE > value | Number | 12, 2 | Specifies the amount of the transaction, this value may have two decimal digits (Ex. 10000.00 or 10000). |
Yes |
| transaction > order > additionalValues > TX_VALUE > currency | Alphanumeric | 3 | ISO code of the currency. See accepted currencies. | Yes |
| transaction > order > additionalValues > TX_TAX | Alphanumeric | 64 | Amount of the Value Added Tax (VAT). | Yes |
| transaction > order > additionalValues > TX_TAX > value | Number | 12, 2 | Specifies the amount of the VAT. | No |
| transaction > order > additionalValues > TX_TAX > currency | Alphanumeric | 3 | ISO code of the currency. See accepted currencies. | No |
| transaction > order > additionalValues > TX_TAX_RETURN_BASE | Alphanumeric | 64 | Base value to calculate the VAT. If the amount does not have IVA, send 0. This value may have two decimal digits. |
No |
| transaction > order > additionalValues > TX_TAX_RETURN_BASE > value | Number | 12, 2 | Specifies the base amount of the transaction. | No |
| transaction > order > additionalValues > TX_TAX_RETURN_BASE > currency | Alphanumeric | 3 | ISO code of the currency. See accepted currencies. | No |
| transaction > payer | Object | Payer information. This information is optional. | No | |
| transaction > payer > emailAddress | Alphanumeric | Max:255 | Payer e-mail address. | No |
| transaction > payer > merchantPayerId | Alphanumeric | Max:100 | Identifier of the payer in your system. | No |
| transaction > payer > fullName | Alphanumeric | Max:150 | Name of the payer. | No |
| transaction > payer > billingAddress | Object | Billing address. | No | |
| transaction > payer > billingAddress > street1 | Alphanumeric | Max:100 | Billing Address Line 1. | No |
| transaction > payer > billingAddress > street2 | Alphanumeric | Max:100 | Billing Address Line 2. | No |
| transaction > payer > billingAddress > city | Alphanumeric | Max:50 | Billing address city. | No |
| transaction > payer > billingAddress > state | Alphanumeric | Max:40 | Billing address state. For Brazil, only send two characters, For example, set SP for São Paulo. |
No |
| transaction > payer > billingAddress > country | Alphanumeric | 2 | Billing address country in format ISO 3166 Alpha-2. | No |
| transaction > payer > billingAddress > postalCode | Alphanumeric | Max:20 | Billing address zip code. For Brazil, use the format XXXXX-XXX or ´. Example: 09210-710 or 09210710. |
No |
| transaction > payer > billingAddress > phone | Alphanumeric | Max:20 | Billing address phone number. For Brazil, use the format ddd(2)+number(7-9). Example: (11)756312633. |
No |
| transaction > payer > birthdate | Alphanumeric | Max:10 | Payer’s date of birth. | No |
| transaction > payer > contactPhone | Alphanumeric | Max:20 | Payer’s phone number. For Brazil, use the format ddd(2)+number(7-9). Example: (11)756312633. |
No |
| transaction > payer > dniNumber | Alphanumeric | Max:20 | Identification number of the buyer. You must use an algorithm to validate the CPF and must be set using the format XXX.XXX.XXX-XX. Example: 811.807.405-64. |
No |
| transaction > payer > cnpj | Alphanumeric | Max:14 | Identification number of the buyer (For Legal person in Brazil). You must use an algorithm to validate the CNPJ and must be set using the format XXXXXXXXXXXXXX. Example: 32593371000110. |
No |
| transaction > payer > dniType | Alphanumeric | 2 | Identification type of the buyer. See Document types. | No |
| transaction > type | Alphanumeric | 32 | As cash payments are performed in physical offices, the only available transaction type is AUTHORIZATION_AND_CAPTURE |
Yes |
| transaction > paymentMethod | Alphanumeric | 32 | Select a valid Payment Method in cash. See the available Payment Methods for Brazil. | Yes |
| transaction > paymentCountry | Alphanumeric | 2 | Set BR for Brazil. |
Yes |
| transaction > expirationDate | Alphanumeric | 23 | Maximum date and time that the payer has to make the payment. Format YYYY-MM-DDTHH:MM:SS, for example 2021-06-12T16:07:11.586. |
No |
| transaction > ipAddress | Alphanumeric | Max:39 | IP address of the device where the customer performs the transaction. | Yes |
Response
| Field Name | Format | Size | Description |
|---|---|---|---|
| code | Alphanumeric | The response code of the transaction. Possible values are ERROR and SUCCESS. |
|
| error | Alphanumeric | Max:2048 | The error message associated when the response code is ERROR. |
| transactionResponse | Object | The response data. | |
| transactionResponse > orderId | Number | The generated or existing order Id in PayU. | |
| transactionResponse > transactionId | Alphanumeric | 36 | The identifier of the transaction in PayU. |
| transactionResponse > state | Alphanumeric | Max:32 | The status of the transaction. As the payment is performed by the user in a physical office, the state for a successful transaction is PENDING |
| transactionResponse > paymentNetworkResponseCode | Alphanumeric | Max:255 | The response code returned by the financial network. |
| transactionResponse > paymentNetworkResponseErrorMessage | Alphanumeric | Max:255 | The error message returned by the financial network. |
| transactionResponse > trazabilityCode | Alphanumeric | Max:32 | The traceability code returned by the financial network. |
| transactionResponse > authorizationCode | Alphanumeric | Max:12 | The authorization code returned by the financial network. |
| transactionResponse > pendingReason | Alphanumeric | Max:21 | The reason code associated with the status, as mentioned in transactionResponse > state, the transaction is waiting for the payment. |
| transactionResponse > responseCode | Alphanumeric | Max:64 | The response code associated with the status. In this case, for successful transactions is PENDING_TRANSACTION_CONFIRMATION. |
| transactionResponse > responseMessage | Alphanumeric | Max:2048 | Message associated with the response code. |
| transactionResponse > operationDate | Date | Creation date of the response in the PayU´s system. | |
| transactionResponse > extraParameters | Object | Additional parameters or data associated with the response. In JSON, the extraParameters parameter follows this structure: "extraParameters": {"REFERENCE": "74794"}In XML, the extraParameters parameter follows this structure: <extraParameters><entry><string>REFERENCE</string><int>74794</int></entry></extraParameters> |
Considerations
- If your commerce does not have a local entity, it is mandatory to send either the CPF (parameter
transaction.[payer|buyer].dniNumber) or the CNPJ (parametertransaction.[payer|buyer].cnpj). - The parameter
transaction.expirationDateis not mandatory. If you don’t send this parameter, its default value is seven (7) days after the current date.
If you send a date later than the default number of days, PayU will ignore this value and the expiration will be set as default. - The payment is reflected in the next business day.
- The parameter
transactionResponse.extraParametershas the following parameters related to the transaction:- URL_PAYMENT_RECEIPT_HTML: payment receipt in HTML format. This is where you need to redirect the payment when the payer selects cash payment.
- URL_BOLETO_BANCARIO: payment receipt in printable format.
- EXPIRATION_DATE: maximum term for the payer to perform the payment.
- BAR_CODE: barcode which lets the payer perform the payment.
API Call
The following are the bodies of the request and response of this payment method.
Request Example:
{
"language": "es",
"command": "SUBMIT_TRANSACTION",
"merchant": {
"apiKey": "4Vj8eK4rloUd272L48hsrarnUA",
"apiLogin": "pRRXKOl8ikMmt9u"
},
"transaction": {
"order": {
"accountId": "512327",
"referenceCode": "PRODUCT_TEST_2021-06-17T19:11:57.179Z",
"description": "Payment test description",
"language": "es",
"signature": "fbc089272288edc52c332395d9566f4c",
"notifyUrl": "http://www.payu.com/notify",
"additionalValues": {
"TX_VALUE": {
"value": 1000,
"currency": "BRL"
}
},
"buyer": {
"merchantBuyerId": "1",
"fullName": "First name and second buyer name",
"emailAddress": "buyer_test@test.com",
"contactPhone": "7563126",
"dniNumber": "811.807.405-64",
"cnpj": "32593371000110",
"shippingAddress": {
"street1": "Quadra QNP 34 Conjunto G 780",
"street2": "5555487",
"city": "Manaos",
"state": "SP",
"country": "BR",
"postalCode": "10012545",
"phone": "(11)756312633"
}
},
"shippingAddress": {
"street1": "Quadra QNP 34 Conjunto G 780",
"street2": "5555487",
"city": "Manaos",
"state": "SP",
"country": "BR",
"postalCode": "10012545",
"phone": "(11)756312633"
}
},
"type": "AUTHORIZATION_AND_CAPTURE",
"paymentMethod": "BOLETO_BANCARIO",
"expirationDate": "2021-06-19T21:57:12.559",
"paymentCountry": "BR",
"ipAddress": "127.0.0.1"
},
"test": false
}
Response Example:
{
"code": "SUCCESS",
"error": null,
"transactionResponse": {
"orderId": 43626780,
"transactionId": "63091676-673d-46bf-a283-54e686ba0238",
"state": "PENDING",
"paymentNetworkResponseCode": null,
"paymentNetworkResponseErrorMessage": null,
"trazabilityCode": null,
"authorizationCode": null,
"pendingReason": "AWAITING_NOTIFICATION",
"responseCode": "PENDING_TRANSACTION_CONFIRMATION",
"errorCode": null,
"responseMessage": null,
"transactionDate": null,
"transactionTime": null,
"operationDate": null,
"extraParameters": {
"URL_PAYMENT_RECEIPT_HTML": "https://gateway.payulatam.com/ppp-web-gateway/bl.zul?transactionId=63091676-673d-46bf-a283-54e686ba0238&orderId=43626780&signature=647b061ddef2a25fd19cb362860e1d21ef59e16a",
"EXPIRATION_DATE": 1399507200000,
"URL_BOLETO_BANCARIO": "https://gateway.payulatam.com/ppp-web-gateway/bl.zul?transactionId=63091676-673d-46bf-a283-54e686ba0238&orderId=43626780&signature=647b061ddef2a25fd19cb362860e1d21ef59e16a",
"BAR_CODE": "34191.75389 38894.912930 81898.480009 9 60560000010000"
}
}
}
Request Example:
<request>
<language>es</language>
<command>SUBMIT_TRANSACTION</command>
<merchant>
<apiKey>4Vj8eK4rloUd272L48hsrarnUA</apiKey>
<apiLogin>pRRXKOl8ikMmt9u</apiLogin>
</merchant>
<transaction>
<order>
<accountId>512327</accountId>
<referenceCode>PRODUCT_TEST_2021-06-17T19:11:57.179Z</referenceCode>
<description>Payment test description</description>
<language>es</language>
<signature>fbc089272288edc52c332395d9566f4c</signature>
<notifyUrl>http://www.payu.com/notify</notifyUrl>
<additionalValues>
<entry>
<string>TX_VALUE</string>
<additionalValue>
<value>1000</value>
<currency>BRL</currency>
</additionalValue>
</entry>
</additionalValues>
<buyer>
<merchantBuyerId>1</merchantBuyerId>
<fullName>First name and second buyer name</fullName>
<emailAddress>buyer_test@test.com</emailAddress>
<contactPhone>7563126</contactPhone>
<dniNumber>811.807.405-64</dniNumber>
<cnpj>32593371000110</cnpj>
<shippingAddress>
<street1>Quadra QNP 34 Conjunto G 780</street1>
<street2>5555487</street2>
<city>Manaos</city>
<state>SP</state>
<country>BR</country>
<postalCode>10012545</postalCode>
<phone>(11)756312633</phone>
</shippingAddress>
</buyer>
<shippingAddress>
<street1>Quadra QNP 34 Conjunto G 780</street1>
<street2>5555487</street2>
<city>Manaos</city>
<state>SP</state>
<country>BR</country>
<postalCode>0000000</postalCode>
<phone>(11)756312633</phone>
</shippingAddress>
</order>
<type>AUTHORIZATION_AND_CAPTURE</type>
<paymentMethod>BOLETO_BANCARIO</paymentMethod>
<expirationDate>2021-06-19T21:57:12.559</expirationDate>
<paymentCountry>BR</paymentCountry>
<ipAddress>127.0.0.1</ipAddress>
</transaction>
<isTest>false</isTest>
</request>
Response Example:
<paymentResponse>
<code>SUCCESS</code>
<transactionResponse>
<orderId>43625300</orderId>
<transactionId>89ff03a7-9f86-4193-a25d-94b758c135bb</transactionId>
<state>PENDING</state>
<pendingReason>AWAITING_NOTIFICATION</pendingReason>
<responseCode>PENDING_TRANSACTION_CONFIRMATION</responseCode>
<extraParameters>
<entry>
<string>URL_PAYMENT_RECEIPT_HTML</string>
<string>https://gateway.payulatam.com/ppp-web-gateway/bl.zul?transactionId=89ff03a7-9f86-4193-a25d-94b758c135bb&orderId=43625300&signature=e9e89a2cd8d9d2d79d637eac84debae9012584de</string>
</entry>
<entry>
<string>EXPIRATION_DATE</string>
<date>2014-05-08T00:00:00</date>
</entry>
<entry>
<string>URL_BOLETO_BANCARIO</string>
<string>https://gateway.payulatam.com/ppp-web-gateway/bl.zul?transactionId=89ff03a7-9f86-4193-a25d-94b758c135bb&orderId=43625300&signature=e9e89a2cd8d9d2d79d637eac84debae9012584de</string>
</entry>
<entry>
<string>BAR_CODE</string>
<string>34191.75389 38894.752930 81898.480009 3 60570000010000</string>
</entry>
</extraParameters>
</transactionResponse>
</paymentResponse>
Submit Transactions Using Bank Transfer
This method lets you process the bank transfer payments of your customers. When using this payment method, the payer performs a bank transfer from their bank account issued in ITAU.
To integrate with these transactions, you must redirect the customer to the URL found in the response of the method.
Parameters for Request and Response
Request
| Field Name | Format | Size | Description | Mandatory |
|---|---|---|---|---|
| language | Alphanumeric | 2 | Language used in the request, this language is used to display the error messages generated. See supported languages. | Yes |
| command | Alphanumeric | Max:32 | Set SUBMIT_TRANSACTION. |
Yes |
| test (JSON) isTest (XML) |
Boolean | Set true if the request is in test mode. Otherwise, set false. |
Yes | |
| merchant | Object | This object has the authentication data. | Yes | |
| merchant > apiLogin | Alphanumeric | Min:12 Max:32 | User or login provided by PayU. How do I get my API Login | Yes |
| merchant > apiKey | Alphanumeric | Min:6 Max:32 | Password provided by PayU. How do I get my API Key | Yes |
| transaction | Object | This object has the transaction data. | Yes | |
| transaction > order | Object | This object has the order data. | Yes | |
| transaction > order > accountId | Number | Identifier of your account. | Yes | |
| transaction > order > referenceCode | Alphanumeric | Min:1 Max:255 | Represents the identifier of the order in your system. | Yes |
| transaction > order > description | Alphanumeric | Min:1 Max:255 | Description of the order. | Yes |
| transaction > order > language | Alphanumeric | 2 | Language used in emails sent to the buyer and the seller. | Yes |
| transaction > order > notifyUrl | Alphanumeric | Max:2048 | Confirmation URL of the order. | No |
| transaction > order > partnerId | Alphanumeric | Max:255 | Partner ID in PayU. | No |
| transaction > order > signature | Alphanumeric | Max:255 | The signature associated to the form. For more information refer Authentication signature. | Yes |
| transaction > order > shippingAddress | Object | Shipping address. | No | |
| transaction > order > shippingAddress > street1 | Alphanumeric | Max:100 | Address Line 1. | No |
| transaction > order > shippingAddress > street2 | Alphanumeric | Max:100 | Address Line 2. | No |
| transaction > order > shippingAddress > city | Alphanumeric | Max:50 | Address city. | No |
| transaction > order > shippingAddress > state | Alphanumeric | Max:40 | Address State. | No |
| transaction > order > shippingAddress > country | Alphanumeric | 2 | Address country. | No |
| transaction > order > shippingAddress > postalCode | Alphanumeric | Max:8 | Address Zip code. For Brazil, use the format XXXXX-XXX or XXXXXXXX. Example: 09210-710 or 09210710. |
No |
| transaction > order > shippingAddress > phone | Alphanumeric | Max:11 | Phone number associated to the address. For Brazil, use the format ddd(2)+number(7-9). Example: (11)756312633. |
No |
| transaction > order > buyer | Object | Buyer information. | Yes | |
| transaction > order > buyer > merchantBuyerId | Alphanumeric | Max:100 | Buyer ID in your system. | No |
| transaction > order > buyer > fullName | Alphanumeric | Max:150 | Full name of the buyer. | Yes |
| transaction > order > buyer > emailAddress | Alphanumeric | Max:255 | E-mail of the buyer. | Yes |
| transaction > order > buyer > contactPhone | Alphanumeric | Max:20 | Phone number of the buyer. For Brazil, use the format ddd(2)+number(7-9). Example: (11)756312633. |
Yes |
| transaction > order > buyer > dniNumber | Alphanumeric | Max:20 | Identification number of the buyer. You must use an algorithm to validate the CPF and must be set using the format XXX.XXX.XXX-XX. Example: 811.807.405-64. |
Yes |
| transaction > order > buyer > cnpj | Alphanumeric | Max:14 | Identification number of the buyer (For Legal person in Brazil). You must use an algorithm to validate the CNPJ and must be set using the format XXXXXXXXXXXXXX. Example: 32593371000110. |
Yes |
| transaction > order > buyer > shippingAddress | Alphanumeric | Shipping address of the buyer. | Yes | |
| transaction > order > buyer > shippingAddress > street1 | Alphanumeric | Max:150 | Buyer’s shipping address Line 1. | Yes |
| transaction > order > buyer > shippingAddress > city | Alphanumeric | Max:50 | Buyer’s shipping address city. | Yes |
| transaction > order > buyer > shippingAddress > state | Alphanumeric | Max:40 | Buyer’s shipping address state. | Yes |
| transaction > order > buyer > shippingAddress > country | Alphanumeric | 2 | Buyer’s shipping address country in format ISO 3166 alpha-2. | Yes |
| transaction > order > buyer > shippingAddress > postalCode | Number | Max:20 | Buyer’s shipping address zip code. For Brazil, use the format XXXXX-XXX or XXXXXXXX. Example: 09210-710 or 09210710. |
Yes |
| transaction > order > buyer > shippingAddress > phone | Number | Max:20 | Buyer’s shipping address phone number. For Brazil, use the format ddd(2)+number(7-9). Example: (11)756312633. |
Yes |
| transaction > order > additionalValues > | Object | 64 | Amount of the order or its associated values. | Yes |
| transaction > order > additionalValues > TX_VALUE | Alphanumeric | 64 | Amount of the transaction. | Yes |
| transaction > order > additionalValues > TX_VALUE > value | Number | 12, 2 | Specifies the amount of the transaction, this value may have two decimal digits (Ex. 10000.00 or 10000). |
Yes |
| transaction > order > additionalValues > TX_VALUE > currency | Alphanumeric | 3 | ISO code of the currency. See accepted currencies. | Yes |
| transaction > order > additionalValues > TX_TAX | Alphanumeric | 64 | Amount of the Value Added Tax (VAT). | Yes |
| transaction > order > additionalValues > TX_TAX > value | Number | 12, 2 | Specifies the amount of the VAT. | No |
| transaction > order > additionalValues > TX_TAX > currency | Alphanumeric | 3 | ISO code of the currency. See accepted currencies. | No |
| transaction > order > additionalValues > TX_TAX_RETURN_BASE | Alphanumeric | 64 | Base value to calculate the VAT. If the amount does not have IVA, send 0. This value may have two decimal digits. |
No |
| transaction > order > additionalValues > TX_TAX_RETURN_BASE > value | Number | 12, 2 | Specifies the base amount of the transaction. | No |
| transaction > order > additionalValues > TX_TAX_RETURN_BASE > currency | Alphanumeric | 3 | ISO code of the currency. See accepted currencies. | No |
| transaction > payer | Object | Payer information. | No | |
| transaction > payer > emailAddress | Alphanumeric | Max:255 | Payer e-mail address. | No |
| transaction > payer > merchantPayerId | Alphanumeric | Max:100 | Identifier of the payer in your system. | No |
| transaction > payer > fullName | Alphanumeric | Max:150 | Name of the payer. | No |
| transaction > payer > billingAddress | Object | Billing address. | No | |
| transaction > payer > billingAddress > street1 | Alphanumeric | Max:100 | Billing Address Line 1. | No |
| transaction > payer > billingAddress > street2 | Alphanumeric | Max:100 | Billing Address Line 2. | No |
| transaction > payer > billingAddress > city | Alphanumeric | Max:50 | Billing address city. | No |
| transaction > payer > billingAddress > state | Alphanumeric | Max:40 | Billing address state. | No |
| transaction > payer > billingAddress > country | Alphanumeric | 2 | Billing address country in format ISO 3166 Alpha-2. | No |
| transaction > payer > billingAddress > postalCode | Alphanumeric | Max:20 | Billing address zip code. For Brazil, use the format XXXXX-XXX or XXXXXXXX. Example: 09210-710 or 09210710. |
No |
| transaction > payer > billingAddress > phone | Alphanumeric | Max:20 | Billing address phone number. For Brazil, use the format ddd(2)+number(7-9). Example: (11)756312633. |
No |
| transaction > payer > birthdate | Alphanumeric | Max:10 | Payer’s date of birth. Format YYYY-MM-DD. |
No |
| transaction > payer > contactPhone | Alphanumeric | Max:20 | Payer’s phone number. For Brazil, use the format ddd(2)+number(7-9). Example: (11)756312633. |
No |
| transaction > payer > dniNumber | Alphanumeric | Max:20 | Identification number of the buyer. You must use an algorithm to validate the CPF and must be set using the format XXX.XXX.XXX-XX. Example: 811.807.405-64. |
No |
| transaction > payer > dniType | Alphanumeric | 2 | Identification type of the buyer. See Document types. | No |
| transaction > type | Alphanumeric | 32 | As cash payments are performed in physical offices, the only available transaction type is AUTHORIZATION_AND_CAPTURE |
Yes |
| transaction > paymentMethod | Alphanumeric | 32 | Select a valid Payment Method in Bank transfer. See the available Payment Methods for Brazil. | Yes |
| transaction > paymentCountry | Alphanumeric | 2 | Set BR for Brazil. |
Yes |
| transaction > deviceSessionId | Alphanumeric | Max:255 | Session identifier of the device where the customer performs the transaction. For more information, refer to this topic. | Yes |
| transaction > ipAddress | Alphanumeric | Max:39 | IP address of the device where the customer performs the transaction. | Yes |
| transaction > cookie | Alphanumeric | Max:255 | Cookie stored by the device where the customer performs the transaction. | Yes |
| transaction > userAgent | Alphanumeric | Max:1024 | The User agent of the browser where the customer performs the transaction. | Yes |
Response
| Field Name | Format | Size | Description |
|---|---|---|---|
| code | Alphanumeric | The response code of the transaction. Possible values are ERROR and SUCCESS. |
|
| error | Alphanumeric | Max:2048 | The error message associated when the response code is ERROR. |
| transactionResponse | Object | The response data. | |
| transactionResponse > orderId | Number | The generated or existing order Id in PayU. | |
| transactionResponse > transactionId | Alphanumeric | 36 | The identifier of the transaction in PayU. |
| transactionResponse > state | Alphanumeric | Max:32 | The status of the transaction. As the payment is performed by the user in a physical office, the state for a successful transaction is PENDING |
| transactionResponse > paymentNetworkResponseCode | Alphanumeric | Max:255 | The response code returned by the financial network. |
| transactionResponse > paymentNetworkResponseErrorMessage | Alphanumeric | Max:255 | The error message returned by the financial network. |
| transactionResponse > trazabilityCode | Alphanumeric | Max:32 | The traceability code returned by the financial network. |
| transactionResponse > authorizationCode | Alphanumeric | Max:12 | The authorization code returned by the financial network. |
| transactionResponse > pendingReason | Alphanumeric | Max:21 | The reason code associated with the status, as mentioned in transactionResponse > state, the transaction is waiting for the payment. |
| transactionResponse > responseCode | Alphanumeric | Max:64 | The response code associated with the status. In this case, for successful transactions is PENDING_PAYMENT_IN_ENTITY. |
| transactionResponse > responseMessage | Alphanumeric | Max:2048 | Message associated with the response code. |
| transactionResponse > operationDate | Date | Creation date of the response in the PayU´s system. | |
| transactionResponse > extraParameters | Object | Additional parameters or data associated with the response. In JSON, the extraParameters parameter follows this structure: "extraParameters": {"BANK_URL": "https://gateway.payulatam.com/ppp-web-gateway/payment-redirect.zul?prid=1181964158Ya5b4bd5e7c6e4ebY4085cd2deb967f2"}In XML, the extraParameters parameter follows this structure: <extraParameters><entry><string>BANK_URL</string><string>https://gateway.payulatam.com/ppp-web-gateway/payment-redirect.zul?prid=1181964158Ya5b4bd5e7c6e4ebY4085cd2deb967f2</string></entry></extraParameters> |
|
| transactionResponse > additionalInfo | Object | Additional information associated with the response. This object follows the same structure than transactionResponse.extraParameters. |
Considerations
- If your commerce does not have a local entity, it is mandatory to send either the CPF (parameter
transaction.[payer|buyer].dniNumber) or the CNPJ (parametertransaction.[payer|buyer].cnpj). - The parameter
transaction.expirationDateis not mandatory. If you don’t send this parameter, its default value is four (4) day after the current date.
If you send a date later than the default number of days, PayU will ignore this value and the expiration will be set as default. - When the payer selects this payment method, PayU creates an order in in progress state and a transaction in
PENDINGstate. - In the response body, you can find the receipt generated by PayU and the expiration date.
API Call
The following are the bodies of the request and response of this payment method.
Request Example:
{
"language": "es",
"command": "SUBMIT_TRANSACTION",
"merchant": {
"apiKey": "4Vj8eK4rloUd272L48hsrarnUA",
"apiLogin": "pRRXKOl8ikMmt9u"
},
"transaction": {
"order": {
"accountId": "512327",
"referenceCode": "PRODUCT_TEST_2021-06-17T19:11:57.179Z",
"description": "payment test",
"language": "es",
"signature": "fbc089272288edc52c332395d9566f4c",
"notifyUrl": "http://www.payu.com/notify",
"additionalValues": {
"TX_VALUE": {
"value": 1000,
"currency": "BRL"
}
},
"buyer": {
"merchantBuyerId": "1",
"fullName": "First name and second buyer name",
"emailAddress": "buyer_test@test.com",
"contactPhone": "7563126",
"dniNumber": "811.807.405-64",
"cnpj": "32593371000110",
"shippingAddress": {
"street1": "Quadra QNP 34 Conjunto G 780",
"street2": "5555487",
"city": "Manaos",
"state": "SP",
"country": "BR",
"postalCode": "10012545",
"phone": "7563126"
}
},
"shippingAddress": {
"street1": "Quadra QNP 34 Conjunto G 780",
"street2": "5555487",
"city": "Manaos",
"state": "SP",
"country": "BR",
"postalCode": "10012545",
"phone": "7563126"
}
},
"type": "AUTHORIZATION_AND_CAPTURE",
"paymentMethod": "ITAU",
"expirationDate": "2021-06-23T22:30:21.231",
"paymentCountry": "BR",
"deviceSessionId": "vghs6tvkcle931686k1900o6e1",
"ipAddress": "127.0.0.1",
"cookie": "pt1t38347bs6jc9ruv2ecpv7o2",
"userAgent": "Mozilla/5.0 (Windows NT 5.1; rv:18.0) Gecko/20100101 Firefox/18.0"
},
"test": false
}
Response Example:
{
"code": "SUCCESS",
"error": null,
"transactionResponse": {
"orderId": 1181965590,
"transactionId": "bd273cec-d2f2-4f00-a125-c705c82b5605",
"state": "PENDING",
"paymentNetworkResponseCode": null,
"paymentNetworkResponseErrorMessage": null,
"trazabilityCode": null,
"authorizationCode": null,
"pendingReason": "AWAITING_NOTIFICATION",
"responseCode": "PENDING_TRANSACTION_CONFIRMATION",
"errorCode": null,
"responseMessage": null,
"transactionDate": null,
"transactionTime": null,
"operationDate": null,
"referenceQuestionnaire": null,
"extraParameters": {
"BANK_URL": "https://gateway.payulatam.com/ppp-web-gateway/payment-redirect.zul?prid=1181965590Ybd273cecd2f24f0Y88337fa73366de5",
"EXPIRATION_DATE": 1626207065416
},
"additionalInfo": {
"paymentNetwork": "ITAU_SHOPLINE",
"rejectionType": "NONE",
"responseNetworkMessage": null,
"travelAgencyAuthorizationCode": null,
"cardType": null,
"transactionType": "AUTHORIZATION_AND_CAPTURE"
}
}
}
Request Example:
<request>
<language>es</language>
<command>SUBMIT_TRANSACTION</command>
<merchant>
<apiKey>4Vj8eK4rloUd272L48hsrarnUA</apiKey>
<apiLogin>pRRXKOl8ikMmt9u</apiLogin>
</merchant>
<transaction>
<order>
<accountId>512327</accountId>
<referenceCode>PRODUCT_TEST_2021-06-17T19:11:57.179Z</referenceCode>
<description>payment test</description>
<language>es</language>
<signature>fbc089272288edc52c332395d9566f4c</signature>
<notifyUrl>http://www.payu.com/notify</notifyUrl>
<additionalValues>
<entry>
<string>TX_VALUE</string>
<additionalValue>
<value>1000</value>
<currency>BRL</currency>
</additionalValue>
</entry>
</additionalValues>
<buyer>
<contactPhone>7563126</contactPhone>
<dniNumber>811.807.405-64</dniNumber>
<cnpj>32593371000110</cnpj>
<emailAddress>buyer_test@test.com</emailAddress>
<fullName>First name and second buyer name</fullName>
<merchantBuyerId>1</merchantBuyerId>
<shippingAddress>
<street1>Quadra QNP 34 Conjunto G 780</street1>
<street2>5555487</street2>
<city>Manaos</city>
<state>SP</state>
<country>BR</country>
<postalCode>10012545</postalCode>
<phone>7563126</phone>
</shippingAddress>
</buyer>
<shippingAddress>
<street1>Quadra QNP 34 Conjunto G 780</street1>
<street2>5555487</street2>
<city>Manaos</city>
<state>SP</state>
<country>BR</country>
<postalCode>10012545</postalCode>
<phone>7563126</phone>
</shippingAddress>
</order>
<type>AUTHORIZATION_AND_CAPTURE</type>
<paymentMethod>ITAU</paymentMethod>
<expirationDate>2021-06-23T22:30:21.231</expirationDate>
<paymentCountry>BR</paymentCountry>
<deviceSessionId>vghs6tvkcle931686k1900o6e</deviceSessionId>
<ipAddress>127.0.0.1</ipAddress>
<cookie>pt1t38347bs6jc9ruv2ecpv7o2</cookie>
<userAgent>Mozilla/5.0 (Windows NT 5.1; rv:18.0) Gecko/20100101 Firefox/18.0</userAgent>
</transaction>
<isTest>false</isTest>
</request>
Response Example:
<paymentResponse>
<code>SUCCESS</code>
<transactionResponse>
<orderId>1181965893</orderId>
<transactionId>8397992b-3717-49c5-92ee-345a65ff13cf</transactionId>
<state>PENDING</state>
<pendingReason>AWAITING_NOTIFICATION</pendingReason>
<responseCode>PENDING_TRANSACTION_CONFIRMATION</responseCode>
<extraParameters>
<entry>
<string>BANK_URL</string>
<string>https://gateway.payulatam.com/ppp-web-gateway/payment-redirect.zul?prid=1181965893Y8397992b371749cY7ad19f758dd04bc</string>
</entry>
<entry>
<string>EXPIRATION_DATE</string>
<date>2021-07-13T15:14:00</date>
</entry>
</extraParameters>
<additionalInfo>
<paymentNetwork>ITAU_SHOPLINE</paymentNetwork>
<rejectionType>NONE</rejectionType>
<transactionType>AUTHORIZATION_AND_CAPTURE</transactionType>
</additionalInfo>
</transactionResponse>
</paymentResponse>
Available Payment Methods Query
This method returns a list of the payment methods available in all countries.
Parameters for Request and Response
Request
| Field Name | Format | Size | Description | Mandatory |
|---|---|---|---|---|
| language | Alphanumeric | 2 | Language used in the request, this language is used to display the error messages generated. See supported languages. | Yes |
| command | Alphanumeric | Max:32 | Set GET_PAYMENT_METHODS. |
Yes |
| test (JSON) isTest (XML) |
Boolean | Set true if the request is in test mode. Otherwise, set false. |
Yes | |
| merchant | Object | This object has the authentication data. | Yes | |
| merchant > apiLogin | Alphanumeric | Min:12 Max:32 | User or login provided by PayU. How do I get my API Login | Yes |
| merchant > apiKey | Alphanumeric | Min:6 Max:32 | Password provided by PayU. How do I get my API Key | Yes |
Response
| Field Name | Format | Size | Description |
|---|---|---|---|
| code | Alphanumeric | The response code of the transaction. Possible values are ERROR and SUCCESS. |
|
| error | Alphanumeric | Max:2048 | The error message associated when the response code is ERROR. |
| paymentMethods | Object | List of the payment methods. | |
| paymentMethods > paymentMethodComplete | Object | This object has the information of a payment method. | |
| paymentMethods > paymentMethodComplete > id | Numeric | Payment method identifier. | |
| paymentMethods > paymentMethodComplete > description | Alphanumeric | Max:32 | Payment method name. |
| paymentMethods > paymentMethodComplete > country | Alphanumeric | 2 | ISO code of the Payment method country. |
API Call
The following are the bodies of the request and response of this method. For the sake of the example, the response here shows two payment methods.
Request Example:
{
"test": false,
"language": "en",
"command": "GET_PAYMENT_METHODS",
"merchant": {
"apiLogin": "pRRXKOl8ikMmt9u",
"apiKey": "4Vj8eK4rloUd272L48hsrarnUA"
}
}
Response Example:
{
"code": "SUCCESS",
"error": null,
"paymentMethods": [
{
"id": "177",
"description": "VISA",
"country": "BR",
"enabled": true,
"reason": null
},
{
"id": "172",
"description": "MASTERCARD",
"country": "BR",
"enabled": true,
"reason": null
}
]
}
Request Example:
<request>
<language>en</language>
<command>GET_PAYMENT_METHODS</command>
<merchant>
<apiLogin>pRRXKOl8ikMmt9u</apiLogin>
<apiKey>4Vj8eK4rloUd272L48hsrarnUA</apiKey>
</merchant>
<isTest>false</isTest>
</request>
Response Example:
<paymentMethodsResponse>
<code>SUCCESS</code>
<paymentMethods>
<paymentMethodComplete>
<id>177</id>
<description>VISA</description>
<country>BR</country>
<enabled>true</enabled>
</paymentMethodComplete>
<paymentMethodComplete>
<id>172</id>
<description>MASTERCARD</description>
<country>BR</country>
<enabled>true</enabled>
</paymentMethodComplete>
</paymentMethods>
</paymentMethodsResponse>
Ping
The PING method lets you verify the connection to our platform.
Parameters for Request and Response
Request
| Field Name | Format | Size | Description | Mandatory |
|---|---|---|---|---|
| language | Alphanumeric | 2 | Language used in the request, this language is used to display the error messages generated. See supported languages. | Yes |
| command | Alphanumeric | Max:32 | Set PING. |
Yes |
| test (JSON) isTest (XML) |
Boolean | Set true if the request is in test mode. Otherwise, set false. |
Yes | |
| merchant | Object | This object has the authentication data. | Yes | |
| merchant > apiLogin | Alphanumeric | Min:12 Max:32 | User or login provided by PayU. How do I get my API Login | Yes |
| merchant > apiKey | Alphanumeric | Min:6 Max:32 | Password provided by PayU. How do I get my API Key | Yes |
Response
| Field Name | Format | Size | Description |
|---|---|---|---|
| code | Alphanumeric | The response code of the transaction. | |
| error | Alphanumeric | Max:2048 | The error message associated if an error ocurred. |
| transactionResponse | Object | Max:2048 | The response of the PING method if an error ocurred. |
API Call
The following are the bodies of the request and response of this method.
Request Example:
{
"test": false,
"language": "en",
"command": "PING",
"merchant": {
"apiLogin": "pRRXKOl8ikMmt9u",
"apiKey": "4Vj8eK4rloUd272L48hsrarnUA"
}
}
Response Example:
{
"code": "SUCCESS",
"error": null,
"transactionResponse": null
}
Request Example:
<request>
<language>en</language>
<command>PING</command>
<merchant>
<apiLogin>pRRXKOl8ikMmt9u</apiLogin>
<apiKey>4Vj8eK4rloUd272L48hsrarnUA</apiKey>
</merchant>
<isTest>false</isTest>
</request>
Response Example:
<paymentResponse>
<code>SUCCESS</code>
</paymentResponse>
Last modified
September 30, 2024:
Documentation Updates (a1e8dbe3c)