Pricing API
The Pricing API lets you query all available financing options and associated costs for your transactions. This includes the pricing configuration of your PayU virtual account, such as standard installments, interest-free installments, and other features relevant to your customers.
Pricing Options
The Pricing API allows you to retrieve financing options available for a given transaction, including standard installment plans and interest-free promotions. Each option specifies the applicable payment methods, eligible banks (if any), the days of the week it is available, and the validity period of any promotional program.
The table below shows where each type of installment option is available across PayU Latam countries. For more details, see the Interest-Free Installments documentation.
| Installment Type | Available Countries | |
|---|---|---|
| Standard Installments |
 Argentina Brazil Chile |
 Colombia Mexico Peru
|
| Specific Interest-Free Installments |
Argentina Colombia
|
Mexico Peru
|
| General Interest-Free Installments (MSI) |
Argentina
|
Mexico
|
Note
To enable an interest-free installment plan according to your agreements with local issuers, contact your PayU sales representative.The following diagram illustrates the full process, from querying the Pricing API to transaction approval:
Querying the Available Pricing Options
To retrieve the pricing information, send a GET request to the appropriate URL based on the environment.
API Endpoints
- Test:
GET https://sandbox.api.payulatam.com/payments-api/rest/v4.9/pricing - Production:
GET https://api.payulatam.com/payments-api/rest/v4.9/pricing
As this is a RESTful service, we strongly recommend against strict schema validation. Avoiding schema validation ensures seamless integration, minimizing changes when updates are made to the Web Service.
Authentication for Requests
To authenticate API requests, you must use an HMAC-based mechanism. You need your MerchantPublicKey, which can be found in your PayU Management Panel under Settings > Technical Configuration > Public Key.
Note
To test in the sandbox environment, use the credentials listed in the Test Your Solution documentation.
Configuring the Authentication
Include the Authorization and Date headers in your request. The Authorization header follows this structure:
"Hmac" + " " + MerchantPublicKey + ":" + Signature
Where Signature is created as follows:
Signature = Base64(HMAC-SHA256(MerchantApiKey,ContentToSign))
And ContentToSign corresponds to:
HTTP-Verb + "\n" + "\n" + "\n" +
Date + "\n" +
URI
Note
It is mandatory to include the three line breaks (\n) after the HTTP-Verb.
Example: Generating the Authentication Header
The following example shows how to create the Authentication header using the following test values:
ContentToSign:
GET
Fri, 28 Apr 2017 18:32:01 GMT
/payments-api/rest/v4.9/pricing
MerchantApiKey:
4Vj8eK4rloUd272L48hsrarnUA
MerchantPublicKey:
PKaC6H4cEDJD919n705L544kSU
Encrypt ContentToSign using MerchantApiKey as the passphrase. Then, concatenate the result with MerchantPublicKey as shown below:
Authorization
Hmac PKaC6H4cEDJD919n705L544kSU:sIxh54sANfKaxO0ugX6QwhPmZRS+TGy8gmdCwr3kjP0=
To prevent replay attacks, include the Date header formatted as follows:
Date
Mon, 11 May 2015 21:14:41 GMT
If REST client restrictions prevent using Date, you may alternatively send x-hmac-date using the same format:
x-hmac-date
Mon, 11 May 2015 21:14:41 GMT
Parameters for Request and Response
This section describes the parameters used in the API request and the fields returned in the response. The request parameters define the input values required to retrieve pricing, promotions, and tax details. The response parameters outline the structure and meaning of the data returned, including transaction amounts, payment method fees, installment breakdowns, promotions, and applicable taxes.
Request Parameters
| Parameter | Description | Mandatory |
|---|---|---|
accountId |
Unique identifier of your account. | Yes |
currency |
Currency associated with your account. | No |
amount |
Total amount of the purchase. Used to calculate the fees shown in the response. Does not filter promotions by amount. | Yes |
paymentMethod |
Optional parameter to filter promotions by payment method. | No |
tax |
Amount of tax included in the transaction. Applicable only in Argentina and Colombia. | No |
taxReturnBase |
Base value used to calculate the tax. Applicable only in Argentina and Colombia. | No |
Response Parameters
| Field Name | Type | Description |
|---|---|---|
amount |
Object | Details of the transaction amount. |
amount > value |
Number | Total value of the transaction. |
amount > tax |
Number | Amount of tax included in the transaction. |
amount > purchaseValue |
Number | Purchase value before taxes. |
amount > adminFeeValue |
Number | Administrative fee amount included in the transaction. |
amount > adminFeeTax |
Number | Tax amount applied to the administrative fee. |
amount > adminFeeTaxableBase |
Number | Taxable base used to calculate taxes on the administrative fee. |
amount > currency |
String | Currency code of the original transaction. |
amount > taxableBase |
Number | Value of the transaction used as the tax base. |
convertedAmount |
Object | Contains the transaction amount converted to another currency (if applicable). |
convertedAmount > value |
Number | Converted total transaction amount. |
convertedAmount > tax |
Number | Converted tax amount. |
convertedAmount > purchaseValue |
Number | Converted purchase value before taxes. |
convertedAmount > adminFeeValue |
Number | Converted administrative fee value. |
convertedAmount > adminFeeTaxableBase |
Number | Converted taxable base for calculating administrative fee taxes. |
convertedAmount > currency |
String | Currency code of the converted amount. |
convertedAmount > taxableBase |
Number | Converted value used as the tax base. |
paymentMethodFee |
List | Breakdown of costs incurred by the merchant based on the payment method. |
paymentMethodFee > paymentMethod |
String | Name of the payment method. |
paymentMethodFee > pricingFees |
Object | Contains pricing details by payment method and installment range. |
paymentMethodFee > pricingFees > installments |
String | Number of installments, either a single value (e.g., 1) or, in applicable countries, a range (e.g., 1-36). |
paymentMethodFee > pricingFees > pricing |
Object | Contains pricing details for the transaction. |
paymentMethodFee > pricingFees > pricing > payerDetail |
Object | Breakdown of interest and fees charged to the payer. |
paymentMethodFee > pricingFees > pricing > payerDetail > commission |
Number | Total commission amount (including taxes) charged to the payer. |
paymentMethodFee > pricingFees > pricing > payerDetail > interests |
Number | Total interest amount (including taxes) charged to the payer. |
paymentMethodFee > pricingFees > pricing > payerDetail > total |
Number | Total amount to be paid by the payer, including interest and fees. |
paymentMethodFee > pricingFees > pricing > merchantDetail |
Object | Breakdown of interest and fees charged to the merchant. |
paymentMethodFee > pricingFees > pricing > merchantDetail > commission |
Number | Total commission amount (including taxes) charged to the merchant. |
paymentMethodFee > pricingFees > pricing > merchantDetail > interests |
Number | Total interest amount (including taxes) charged to the merchant. |
paymentMethodFee > pricingFees > pricing > merchantDetail > total |
Number | Total cost incurred by the merchant, including interest and fees. |
paymentMethodFee > pricingFees > pricing > totalValue |
Number | Total value of the transaction including interest and fees. |
paymentMethodFee > pricingFees > pricing > totalIncomeTransaction |
Number | Total income generated by the transaction. |
paymentMethodFee > pricingFees > pricing > additionalInfo |
Object | Includes financial information such as the Annual Effective Rate (TEA) and Total Financial Cost (CFT). Applies only to Argentina. |
paymentMethodFee > pricingFees > pricing > additionalInfo > cft |
Number | Total Financial Cost (CFT) applied to the transaction. |
paymentMethodFee > pricingFees > pricing > additionalInfo > tea |
Number | Annual Effective Rate (TEA) applied to the transaction. |
paymentMethodFee > pricingFees > promos |
Array | List of available promotions applicable to the pricing configuration. |
paymentMethodFee > pricingFees > promos > id |
Integer | Unique promotion ID in the PayU system. |
paymentMethodFee > pricingFees > promos > pricing |
Object | Contains pricing details for the specific promotion. |
paymentMethodFee > pricingFees > promos > pricing > payerDetail |
Object | Breakdown of interest and fees for the payer under the promotion. |
paymentMethodFee > pricingFees > promos > pricing > payerDetail > commission |
Number | Commission charged to the payer under the promotion. |
paymentMethodFee > pricingFees > promos > pricing > payerDetail > interests |
Number | Interest charged to the payer under the promotion. |
paymentMethodFee > pricingFees > promos > pricing > payerDetail > total |
Number | Total amount to be paid by the payer, including commissions and interest, under the promotion. |
paymentMethodFee > pricingFees > promos > pricing > merchantDetail |
Object | Breakdown of interest and fees for the merchant under the promotion. |
paymentMethodFee > pricingFees > promos > pricing > merchantDetail > commission |
Number | Commission charged to the merchant under the promotion. |
paymentMethodFee > pricingFees > promos > pricing > merchantDetail > interests |
Number | Interest charged to the merchant under the promotion. |
paymentMethodFee > pricingFees > promos > pricing > merchantDetail > total |
Number | Total cost for the merchant, including commissions and interest, under the promotion. |
paymentMethodFee > pricingFees > promos > pricing > totalValue |
Number | Total transaction value including commissions and interest under the promotion. |
paymentMethodFee > pricingFees > promos > pricing > totalIncomeTransaction |
Number | Total income generated by the transaction under the promotion. |
paymentMethodFee > pricingFees > promos > priority |
Number | Promotion priority level within the pricing configuration. |
promotions |
Object | Contains details about the applied promotion (if applicable). |
promotions > id |
Integer | Unique promotion ID in the PayU system. |
promotions > title |
String | Promotion title (maximum 50 characters). |
promotions > termsAndConditions |
String | Terms and conditions applicable to the promotion (maximum 250 characters). |
promotions > paymentMethod |
String | Payment method associated with the promotion. |
promotions > subFranchise |
String | Sub-brand or sub-franchise associated with the promotion. If subFranchise is not provided, the promotion is not tied to a local card (such as Naranja), but instead applies to an international brand (e.g., Mastercard), as defined by paymentMethodMain. |
promotions > banksNames |
List | List of banks where the promotion applies. If banksNames is not provided, the promotion applies to the entire payment method, with paymentMethodMain taking precedence. |
promotions > paymentMethodMain |
String | Main payment method associated with the promotion. |
promotions > iin |
List | List of eligible card IIN/BIN numbers for the promotion. |
promotions > iins |
List | List of eligible card IIN/BIN numbers for the promotion. If iins is not provided, the promotion is available for all cards under the payment method specified in paymentMethodMain. |
promotions > days |
List | Days of the week the promotion is available. |
promotions > startDate |
DateTime | Promotion start date and time. |
promotions > endDate |
DateTime | Promotion end date and time. |
promotions > priority |
Number | Promotion priority level. |
promotions > type |
String | Type of promotion. Possible values: PRICING – The promotion is automatically applied based on configured pricing rules. For example, in Mexico, if interest-free installments are configured, the merchant only needs to send the number of installments in transaction > extraParameters > INSTALLMENTS_NUMBER. The system will automatically apply the interest-free condition without requiring a promotion ID.MSI – Requires the merchant to explicitly send both the promotion ID and number of installments. This applies when the promotion must match a specific combination of payment method, installments, and promotion ID. To apply this type, the following fields must be sent: - transaction > extraParameters > INSTALLMENTS_NUMBER- transaction > extraParameters > PROMOTION_IDNote: If the promotion ID is not sent when required, the transaction will be processed without the promotion, using the default pricing configuration for the selected installment option. |
paymentTaxesDetails |
Object | Contains details of applied taxes (structure depends on the tax service response). |
taxesServiceFailed |
Boolean | Indicates whether the tax calculation service failed. |
API Call
To retrieve available pricing options, send a GET request using the following format:
GET
https://{env-api}.payulatam.com/payments-api/rest/v4.9/pricing?accountId={accountId}¤cy={currency}&amount={amount}&paymentMethod={paymentMethod}
Accept: application/json
Content-Type: application/json
Authorization: Hmac PKaC6H4cEDJD919n705L544kSU:sIxh54sANfKaxO0ugX6QwhPmZRS+TGy8gmdCwr3kjP0=
Date: Fri, 16 May 2025 14:37:05 GMT
The {env-api} variable should be set as follows:
sandbox.apifor testingapifor production
The paymentMethod parameter is optional and can be used to filter promotions by a specific payment method. The tax and taxReturnBase parameters are also optional but are only applicable in Argentina and Colombia.
Request Example for Argentina:
https://sandbox.api.payulatam.com/payments-api/rest/v4.9/pricing?accountId=512322¤cy=ARS&amount=110524.91&tax=19182.01&taxReturnBase=91342.90
Request Example for Colombia:
https://sandbox.api.payulatam.com/payments-api/rest/v4.9/pricing?accountId=512321¤cy=COP&amount=11601.71&tax=1769.75&taxReturnBase=9831.96
Request Example for Mexico:
https://sandbox.api.payulatam.com/payments-api/rest/v4.9/pricing?accountId=512324¤cy=MXN&amount=15662.37
Request Example for Peru:
https://sandbox.api.payulatam.com/payments-api/rest/v4.9/pricing?accountId=516634¤cy=PEN&amount=2897.78
Response Example:
{
"amount": {
"value": 1000.00,
"tax": 0,
"purchaseValue": 1000.00,
"currency": "ARS"
},
"convertedAmount": {
"value": 1000.00,
"tax": 0.00,
"purchaseValue": 1000.00,
"currency": "ARS"
},
"promotions": [
{
"id": 49,
"title": "Promotion_ID AMEX",
"termsAndConditions": "SI",
"paymentMethodMain": "AMEX",
"startDate": "2018-08-16 18:48:00",
"endDate": "2090-08-16 18:48:00",
"days": [
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY",
"SATURDAY",
"SUNDAY"
],
"priority": 10,
"type": "MSI"
},
{
"id": 45,
"title": "Promotion Test - Master",
"termsAndConditions": "Terminos y condiciones",
"paymentMethodMain": "MASTERCARD",
"startDate": "2018-06-26 17:06:00",
"endDate": "2030-06-26 17:06:00",
"days": [
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY",
"SATURDAY",
"SUNDAY"
],
"priority": 10,
"type": "MSI"
}
],
"paymentMethodFee": [
{
"paymentMethod": "DINERS",
"pricingFees": [
{
"installments": "1",
"pricing": {
"payerDetail": {
"commission": 0.00,
"interests": 0.00,
"total": 0.00
},
"merchantDetail": {
"commission": 44.65,
"interests": 0.00,
"total": 44.65
},
"totalValue": 1000.00,
"totalIncomeTransaction": 955.35,
"additionalInfo": {
"cft": "0%",
"tea": "0%"
}
}
},
{
"installments": "3",
"pricing": {
"payerDetail": {
"commission": 0.00,
"interests": 171.29,
"total": 171.29
},
"merchantDetail": {
"commission": 44.65,
"interests": 0.00,
"total": 44.65
},
"totalValue": 1171.29,
"totalIncomeTransaction": 955.35,
"additionalInfo": {
"cft": "162%",
"tea": "123.28%"
}
}
},
{
"installments": "6",
"pricing": {
"payerDetail": {
"commission": 0.00,
"interests": 230.01,
"total": 230.01
},
"merchantDetail": {
"commission": 44.65,
"interests": 0.00,
"total": 44.65
},
"totalValue": 1230.01,
"totalIncomeTransaction": 955.35,
"additionalInfo": {
"cft": "107%",
"tea": "83.97%"
}
}
},
{
"installments": "9",
"pricing": {
"payerDetail": {
"commission": 0.00,
"interests": 340.05,
"total": 340.05
},
"merchantDetail": {
"commission": 44.65,
"interests": 0.00,
"total": 44.65
},
"totalValue": 1340.04,
"totalIncomeTransaction": 955.35,
"additionalInfo": {
"cft": "108%",
"tea": "85.03%"
}
}
},
{
"installments": "12",
"pricing": {
"payerDetail": {
"commission": 0.00,
"interests": 490.01,
"total": 490.01
},
"merchantDetail": {
"commission": 44.65,
"interests": 0.00,
"total": 44.65
},
"totalValue": 1490.02,
"totalIncomeTransaction": 955.35,
"additionalInfo": {
"cft": "119%",
"tea": "93.68%"
}
}
},
{
"installments": "18",
"pricing": {
"payerDetail": {
"commission": 0.00,
"interests": 641.38,
"total": 641.38
},
"merchantDetail": {
"commission": 44.65,
"interests": 0.00,
"total": 44.65
},
"totalValue": 1641.39,
"totalIncomeTransaction": 955.35,
"additionalInfo": {
"cft": "97%",
"tea": "77.91%"
}
}
},
{
"installments": "24",
"pricing": {
"payerDetail": {
"commission": 0.00,
"interests": 822.72,
"total": 822.72
},
"merchantDetail": {
"commission": 44.65,
"interests": 0.00,
"total": 44.65
},
"totalValue": 1822.72,
"totalIncomeTransaction": 955.35,
"additionalInfo": {
"cft": "90%",
"tea": "72.47%"
}
}
}
]
},
{
"paymentMethod": "AMEX",
"pricingFees": [
{
"installments": "1",
"pricing": {
"payerDetail": {
"commission": 0.00,
"interests": 0.00,
"total": 0.00
},
"merchantDetail": {
"commission": 44.65,
"interests": 0.00,
"total": 44.65
},
"totalValue": 1000.00,
"totalIncomeTransaction": 955.35,
"additionalInfo": {
"cft": "0%",
"tea": "0%"
}
},
"promos": [
{
"id": 49,
"pricing": {
"payerDetail": {
"commission": 0.00,
"interests": 0.00,
"total": 0.00
},
"merchantDetail": {
"commission": 1044.65,
"interests": 0.00,
"total": 1044.65
},
"totalValue": 1000.00,
"totalIncomeTransaction": -44.65,
"additionalInfo": {
"cft": "0%",
"tea": "0%"
}
},
"priority": 10
}
]
},
{
"installments": "3",
"pricing": {
"payerDetail": {
"commission": 0.00,
"interests": 171.29,
"total": 171.29
},
"merchantDetail": {
"commission": 44.65,
"interests": 0.00,
"total": 44.65
},
"totalValue": 1171.29,
"totalIncomeTransaction": 955.35,
"additionalInfo": {
"cft": "162%",
"tea": "123.28%"
}
}
},
{
"installments": "6",
"pricing": {
"payerDetail": {
"commission": 0.00,
"interests": 230.01,
"total": 230.01
},
"merchantDetail": {
"commission": 44.65,
"interests": 0.00,
"total": 44.65
},
"totalValue": 1230.01,
"totalIncomeTransaction": 955.35,
"additionalInfo": {
"cft": "107%",
"tea": "83.97%"
}
}
},
{
"installments": "9",
"pricing": {
"payerDetail": {
"commission": 0.00,
"interests": 340.05,
"total": 340.05
},
"merchantDetail": {
"commission": 44.65,
"interests": 0.00,
"total": 44.65
},
"totalValue": 1340.04,
"totalIncomeTransaction": 955.35,
"additionalInfo": {
"cft": "108%",
"tea": "85.03%"
}
}
},
{
"installments": "12",
"pricing": {
"payerDetail": {
"commission": 0.00,
"interests": 490.01,
"total": 490.01
},
"merchantDetail": {
"commission": 44.65,
"interests": 0.00,
"total": 44.65
},
"totalValue": 1490.02,
"totalIncomeTransaction": 955.35,
"additionalInfo": {
"cft": "119%",
"tea": "93.68%"
}
}
},
{
"installments": "18",
"pricing": {
"payerDetail": {
"commission": 0.00,
"interests": 641.38,
"total": 641.38
},
"merchantDetail": {
"commission": 44.65,
"interests": 0.00,
"total": 44.65
},
"totalValue": 1641.39,
"totalIncomeTransaction": 955.35,
"additionalInfo": {
"cft": "97%",
"tea": "77.91%"
}
}
},
{
"installments": "24",
"pricing": {
"payerDetail": {
"commission": 0.00,
"interests": 822.72,
"total": 822.72
},
"merchantDetail": {
"commission": 44.65,
"interests": 0.00,
"total": 44.65
},
"totalValue": 1822.72,
"totalIncomeTransaction": 955.35,
"additionalInfo": {
"cft": "90%",
"tea": "72.47%"
}
}
}
]
}
],
"paymentTaxesDetails": [],
"taxesServiceFailed": true
}
<consultPriceListResponse xmlns:atom="http://www.w3.org/2005/Atom" xmlns:ns3="http://wadl.dev.java.net/2009/02">
<amount>
<value>1000.00</value>
<tax>0</tax>
<purchaseValue>1000.00</purchaseValue>
<currency>ARS</currency>
</amount>
<convertedAmount>
<value>1000.00</value>
<tax>0.00</tax>
<purchaseValue>1000.00</purchaseValue>
<currency>ARS</currency>
</convertedAmount>
<promotions>
<promotion id="49" title="Promotion_ID AMEX">
<priority>10</priority>
<type>MSI</type>
<paymentMethod>AMEX</paymentMethod>
<termsAndConditions>SI</termsAndConditions>
<startDate>2018-08-16 18:48:00</startDate>
<endDate>2090-08-16 18:48:00</endDate>
<days>
<day>MONDAY</day>
<day>TUESDAY</day>
<day>WEDNESDAY</day>
<day>THURSDAY</day>
<day>FRIDAY</day>
<day>SATURDAY</day>
<day>SUNDAY</day>
</days>
</promotion>
<promotion id="45" title="Promotion Test - Master">
<priority>10</priority>
<type>MSI</type>
<paymentMethod>MASTERCARD</paymentMethod>
<termsAndConditions>Terminos y condiciones</termsAndConditions>
<startDate>2018-06-26 17:06:00</startDate>
<endDate>2030-06-26 17:06:00</endDate>
<days>
<day>MONDAY</day>
<day>TUESDAY</day>
<day>WEDNESDAY</day>
<day>THURSDAY</day>
<day>FRIDAY</day>
<day>SATURDAY</day>
<day>SUNDAY</day>
</days>
</promotion>
</promotions>
<paymentMethodFee>
<paymentMethodFeeDetail paymentMethod="DINERS">
<pricingFees>
<fee installments="1">
<pricing>
<payerDetail>
<commission>0.00</commission>
<interests>0.00</interests>
<total>0.00</total>
</payerDetail>
<merchantDetail>
<commission>44.65</commission>
<interests>0.00</interests>
<total>44.65</total>
</merchantDetail>
<totalValue>1000.00</totalValue>
<totalIncomeTransaction>955.35</totalIncomeTransaction>
<additionalInfo>
<entry>
<key>cft</key>
<value>0%</value>
</entry>
<entry>
<key>tea</key>
<value>0%</value>
</entry>
</additionalInfo>
</pricing>
</fee>
<fee installments="3">
<pricing>
<payerDetail>
<commission>0.00</commission>
<interests>171.29</interests>
<total>171.29</total>
</payerDetail>
<merchantDetail>
<commission>44.65</commission>
<interests>0.00</interests>
<total>44.65</total>
</merchantDetail>
<totalValue>1171.29</totalValue>
<totalIncomeTransaction>955.35</totalIncomeTransaction>
<additionalInfo>
<entry>
<key>cft</key>
<value>162%</value>
</entry>
<entry>
<key>tea</key>
<value>123.28%</value>
</entry>
</additionalInfo>
</pricing>
</fee>
<fee installments="6">
<pricing>
<payerDetail>
<commission>0.00</commission>
<interests>230.01</interests>
<total>230.01</total>
</payerDetail>
<merchantDetail>
<commission>44.65</commission>
<interests>0.00</interests>
<total>44.65</total>
</merchantDetail>
<totalValue>1230.01</totalValue>
<totalIncomeTransaction>955.35</totalIncomeTransaction>
<additionalInfo>
<entry>
<key>cft</key>
<value>107%</value>
</entry>
<entry>
<key>tea</key>
<value>83.97%</value>
</entry>
</additionalInfo>
</pricing>
</fee>
<fee installments="9">
<pricing>
<payerDetail>
<commission>0.00</commission>
<interests>340.05</interests>
<total>340.05</total>
</payerDetail>
<merchantDetail>
<commission>44.65</commission>
<interests>0.00</interests>
<total>44.65</total>
</merchantDetail>
<totalValue>1340.04</totalValue>
<totalIncomeTransaction>955.35</totalIncomeTransaction>
<additionalInfo>
<entry>
<key>cft</key>
<value>108%</value>
</entry>
<entry>
<key>tea</key>
<value>85.03%</value>
</entry>
</additionalInfo>
</pricing>
</fee>
<fee installments="12">
<pricing>
<payerDetail>
<commission>0.00</commission>
<interests>490.01</interests>
<total>490.01</total>
</payerDetail>
<merchantDetail>
<commission>44.65</commission>
<interests>0.00</interests>
<total>44.65</total>
</merchantDetail>
<totalValue>1490.02</totalValue>
<totalIncomeTransaction>955.35</totalIncomeTransaction>
<additionalInfo>
<entry>
<key>cft</key>
<value>119%</value>
</entry>
<entry>
<key>tea</key>
<value>93.68%</value>
</entry>
</additionalInfo>
</pricing>
</fee>
<fee installments="18">
<pricing>
<payerDetail>
<commission>0.00</commission>
<interests>641.38</interests>
<total>641.38</total>
</payerDetail>
<merchantDetail>
<commission>44.65</commission>
<interests>0.00</interests>
<total>44.65</total>
</merchantDetail>
<totalValue>1641.39</totalValue>
<totalIncomeTransaction>955.35</totalIncomeTransaction>
<additionalInfo>
<entry>
<key>cft</key>
<value>97%</value>
</entry>
<entry>
<key>tea</key>
<value>77.91%</value>
</entry>
</additionalInfo>
</pricing>
</fee>
<fee installments="24">
<pricing>
<payerDetail>
<commission>0.00</commission>
<interests>822.72</interests>
<total>822.72</total>
</payerDetail>
<merchantDetail>
<commission>44.65</commission>
<interests>0.00</interests>
<total>44.65</total>
</merchantDetail>
<totalValue>1822.72</totalValue>
<totalIncomeTransaction>955.35</totalIncomeTransaction>
<additionalInfo>
<entry>
<key>cft</key>
<value>90%</value>
</entry>
<entry>
<key>tea</key>
<value>72.47%</value>
</entry>
</additionalInfo>
</pricing>
</fee>
</pricingFees>
</paymentMethodFeeDetail>
<paymentMethodFeeDetail paymentMethod="AMEX">
<pricingFees>
<fee installments="1">
<pricing>
<payerDetail>
<commission>0.00</commission>
<interests>0.00</interests>
<total>0.00</total>
</payerDetail>
<merchantDetail>
<commission>44.65</commission>
<interests>0.00</interests>
<total>44.65</total>
</merchantDetail>
<totalValue>1000.00</totalValue>
<totalIncomeTransaction>955.35</totalIncomeTransaction>
<additionalInfo>
<entry>
<key>cft</key>
<value>0%</value>
</entry>
<entry>
<key>tea</key>
<value>0%</value>
</entry>
</additionalInfo>
</pricing>
<promos>
<promo id="49">
<priority>10</priority>
<pricing>
<payerDetail>
<commission>0.00</commission>
<interests>0.00</interests>
<total>0.00</total>
</payerDetail>
<merchantDetail>
<commission>1044.65</commission>
<interests>0.00</interests>
<total>1044.65</total>
</merchantDetail>
<totalValue>1000.00</totalValue>
<totalIncomeTransaction>-44.65</totalIncomeTransaction>
<additionalInfo>
<entry>
<key>cft</key>
<value>0%</value>
</entry>
<entry>
<key>tea</key>
<value>0%</value>
</entry>
</additionalInfo>
</pricing>
</promo>
</promos>
</fee>
<fee installments="3">
<pricing>
<payerDetail>
<commission>0.00</commission>
<interests>171.29</interests>
<total>171.29</total>
</payerDetail>
<merchantDetail>
<commission>44.65</commission>
<interests>0.00</interests>
<total>44.65</total>
</merchantDetail>
<totalValue>1171.29</totalValue>
<totalIncomeTransaction>955.35</totalIncomeTransaction>
<additionalInfo>
<entry>
<key>cft</key>
<value>162%</value>
</entry>
<entry>
<key>tea</key>
<value>123.28%</value>
</entry>
</additionalInfo>
</pricing>
</fee>
<fee installments="6">
<pricing>
<payerDetail>
<commission>0.00</commission>
<interests>230.01</interests>
<total>230.01</total>
</payerDetail>
<merchantDetail>
<commission>44.65</commission>
<interests>0.00</interests>
<total>44.65</total>
</merchantDetail>
<totalValue>1230.01</totalValue>
<totalIncomeTransaction>955.35</totalIncomeTransaction>
<additionalInfo>
<entry>
<key>cft</key>
<value>107%</value>
</entry>
<entry>
<key>tea</key>
<value>83.97%</value>
</entry>
</additionalInfo>
</pricing>
</fee>
<fee installments="9">
<pricing>
<payerDetail>
<commission>0.00</commission>
<interests>340.05</interests>
<total>340.05</total>
</payerDetail>
<merchantDetail>
<commission>44.65</commission>
<interests>0.00</interests>
<total>44.65</total>
</merchantDetail>
<totalValue>1340.04</totalValue>
<totalIncomeTransaction>955.35</totalIncomeTransaction>
<additionalInfo>
<entry>
<key>cft</key>
<value>108%</value>
</entry>
<entry>
<key>tea</key>
<value>85.03%</value>
</entry>
</additionalInfo>
</pricing>
</fee>
<fee installments="12">
<pricing>
<payerDetail>
<commission>0.00</commission>
<interests>490.01</interests>
<total>490.01</total>
</payerDetail>
<merchantDetail>
<commission>44.65</commission>
<interests>0.00</interests>
<total>44.65</total>
</merchantDetail>
<totalValue>1490.02</totalValue>
<totalIncomeTransaction>955.35</totalIncomeTransaction>
<additionalInfo>
<entry>
<key>cft</key>
<value>119%</value>
</entry>
<entry>
<key>tea</key>
<value>93.68%</value>
</entry>
</additionalInfo>
</pricing>
</fee>
<fee installments="18">
<pricing>
<payerDetail>
<commission>0.00</commission>
<interests>641.38</interests>
<total>641.38</total>
</payerDetail>
<merchantDetail>
<commission>44.65</commission>
<interests>0.00</interests>
<total>44.65</total>
</merchantDetail>
<totalValue>1641.39</totalValue>
<totalIncomeTransaction>955.35</totalIncomeTransaction>
<additionalInfo>
<entry>
<key>cft</key>
<value>97%</value>
</entry>
<entry>
<key>tea</key>
<value>77.91%</value>
</entry>
</additionalInfo>
</pricing>
</fee>
<fee installments="24">
<pricing>
<payerDetail>
<commission>0.00</commission>
<interests>822.72</interests>
<total>822.72</total>
</payerDetail>
<merchantDetail>
<commission>44.65</commission>
<interests>0.00</interests>
<total>44.65</total>
</merchantDetail>
<totalValue>1822.72</totalValue>
<totalIncomeTransaction>955.35</totalIncomeTransaction>
<additionalInfo>
<entry>
<key>cft</key>
<value>90%</value>
</entry>
<entry>
<key>tea</key>
<value>72.47%</value>
</entry>
</additionalInfo>
</pricing>
</fee>
</pricingFees>
</paymentMethodFeeDetail>
</paymentMethodFee>
<paymentTaxesDetails/>
<taxesServiceFailed>true</taxesServiceFailed>
</consultPriceListResponse>
Processing Transactions with Installments
This section explains how to use and apply the different installment plans.
Installment Types
The table below summarizes the available installment types, their required parameters, and who covers the interest.
| Installment Type | Applicable Countries | Required Parameters | Who Covers the Interest? | Notes |
|---|---|---|---|---|
| Standard Installments | Argentina, Brazil, Chile, Colombia, Mexico, Peru | INSTALLMENTS_NUMBER |
Payer | Default installment plan with interest. |
| Specific Interest-Free Installments | Argentina, Colombia, Mexico, Peru | PROMOTION_ID + INSTALLMENTS_NUMBER |
Merchant | Linked to a specific promotion or agreement. |
| General Interest-Free Installments (MSI) | Argentina, Mexico | INSTALLMENTS_NUMBER |
Merchant | Must be enabled in your PayU account. No promotion ID required. In Mexico, the promotion ID 9999 is not required. |
Considerations:
- Confirm that interest-free or MSI plans are enabled in your PayU account to ensure the system applies them correctly.
- If you send only
INSTALLMENTS_NUMBERwithout an active General Interest-Free Installments plan, the system applies standard installments and charges interest to the payer.
Displaying Eligible Installments at Checkout
When displaying available installment options during checkout, validate eligibility using the following rules:
- Match the card’s BIN with the values in
promotions[].iin. - If no BINs are specified, check whether the user’s bank matches any in
promotions[].banksNames. - If no banks are specified, fall back to the payment method (card brand) defined in
paymentMethodFee[].paymentMethod.
Use the following fields from the Pricing API response to determine eligibility and display the correct installment options:
paymentMethodFee[].pricingFees[].installments→ Number of installments availablepaymentMethodFee[].pricingFees[].promos[].id→ Associated promotion IDpromotions[].id, promotions[].iin, promotions[].banksNames→ Promotion eligibility criteriapaymentMethodFee[].paymentMethod→ Card brand (e.g., Visa, Mastercard)
By validating this hierarchy, you ensure that users only see installment options that apply to their card.
Checkout Examples
Example: Standard Installments in Argentina
In this example, the payer covers the interest. Values in paymentMethodFee[].pricingFees[].pricing.payerDetail are greater than 0.
Example: Specific Interest-Free Installments in Argentina
In this example, the merchant covers the interest. Values in paymentMethodFee[].pricingFees[].promos[].pricing.merchantDetail are greater than 0.
Displaying CFT and TEA in Argentina
According to Resolution E 51/2017 of the Secretaría de Comercio (Argentina), merchants must clearly display financing information when processing credit or debit card transactions with installments.
Specifically, you must:
- Differentiate the cash price from the financing cost in both interest-bearing and interest-free installments.
- Display the Total Financial Cost (CFT) prominently next to the cash price.
- Use a highlighted color and a font size at least five times larger than the one used for TEA, the number of installments, and their amount.
- The CFT must include interest and applicable taxes (such as VAT).
- Display the Annual Effective Rate (TEA), which shows the difference between the cash price and the financed price.
- Avoid using the phrase “sin interés” (without interest) or similar wording if the financial cost is incorporated into the product or service price.
This information is available in the API response fields:
paymentMethodFee[].pricingFees[].pricing.additionalInfopaymentMethodFee[].pricingFees[].promos[].pricing.additionalInfo
Example Display
When showing installment options to customers, include the following elements:
Where:
| Number in the screen | Option | Description |
|---|---|---|
| 1 | Total purchase | Total amount of the purchase without financing. |
| 2 | Total payment | Total amount financed of the purchase. |
| 3 | Installments | Number of installments and their amount. |
| 4 | TEA | The annual effective interest rate (TEA) applied. |
| 5 | CFT | The total financial cost (CFT). |
Note
For interest-free installments, you must still display TEA and CFT, but set their values to 0%.Identifying Installment Types by Interest Allocation
The table below shows how to identify the installment type based on how the system allocates interest between the payer and the merchant, using fields from the Pricing API response.
| Installment Type | Payer Interest | Merchant Interest | Who Assumes the Interest? | Notes |
|---|---|---|---|---|
| Standard Installment (No Interest) |
Values in: paymentMethodFee[].pricingFees[]. = 0
|
Values in: paymentMethodFee[].pricingFees[] = 0
|
Bank (outside the promotion system) | Interest-free from PayU's perspective; any fees come directly from the bank. |
| Standard Installment (With Interest) |
Values in: paymentMethodFee[].pricingFees[]. > 0
|
Values in: paymentMethodFee[].pricingFees[]. = 0
|
Payer | Merchant does not cover interest. |
| General Interest-Free Installments |
Values in: paymentMethodFee[].pricingFees[]. = 0
|
Values in: paymentMethodFee[].pricingFees[]. > 0
|
Merchant | Applies to the entire payment method or card brand. |
Identifying Specific Interest-Free Installments
When you query the Pricing API, you can identify a specific promotional installment if the promos array contains a promotion where:
- The payer pays 0 interest.
- The merchant covers the full cost (commission or interest is greater than
0).
This type of promotion may apply to specific banks or BINs tied to a particular card brand.
Validating Specific Interest-Free Installments
- Values in
paymentMethodFee[].pricingFees[].promos[].pricing.payerDetail=0 - Values in
paymentMethodFee[].pricingFees[].promos[].pricing.merchantDetail>0
To fully understand a promotion’s conditions, check the promotions[] object that matches the promotion ID from:
paymentMethodFee[].pricingFees[].promos[].id
Key fields in promotions[] to review: |
|
|---|---|
promotions[].id |
promotions[].banksNames |
promotions[].title |
promotions[].iins |
promotions[].termsAndConditions |
promotions[].days |
promotions[].paymentMethod |
promotions[].startDate |
promotions[].subFranchise |
promotions[].endDate |
promotions[].priority |
promotions[].type |
Important
When displaying Specific Interest-Free Installments at checkout, make sure to show them only if the BIN, bank, or payment method matches the user’s card.If you display an ineligible promotion and the user selects it, the transaction will be declined because PayU cannot find a valid authorization route.
Response Example for Specific Interest-Free Installments
The following example illustrates how a response may look when a promotion is tied to specific conditions such as BIN ranges, banks, card brands, or days of the week.
"promotions": [
{
"id": 1218,
"title": "ABC Bank",
"termsAndConditions": "6-month interest-free financing for cards with BIN 828076 from ABC Bank. Promotion valid from 08/20/2025 to 08/20/2025. Applies only on weekdays: Tuesday",
"iin": [
"828076"
],
"paymentMethodMain": "VISA",
"startDate": "2025-08-20 00:00:00",
"endDate": "2025-08-20 23:59:00",
"days": [
"TUESDAY"
],
"priority": 10,
"type": "MSI"
}
]
<promotions>
<promotion>
<id>1218</id>
<title>ABC Bank</title>
<termsAndConditions>
6-month interest-free financing for cards with BIN 828076 from ABC Bank. Promotion valid from 08/20/2025 to 08/20/2025. Applies only on weekdays: Tuesday
</termsAndConditions>
<iin>
<value>828076</value>
</iin>
<paymentMethodMain>VISA</paymentMethodMain>
<startDate>2025-08-20 00:00:00</startDate>
<endDate>2025-08-20 23:59:00</endDate>
<days>
<day>TUESDAY</day>
</days>
<priority>10</priority>
<type>MSI</type>
</promotion>
</promotions>
Displaying the Terms and Conditions at Checkout
You can use the termsAndConditions field to state the details for Specific Interest-Free Installments plans. Below is an example of how to show the payer the conditions at checkout using the response retrieved above:
Differentiating Standard vs. Specific Interest-Free Installments
When you use the Pricing API, you need to know how the system distinguishes standard installments from promotional ones.
Use the following structure to identify the installment type:
paymentMethodFee[].pricingFees[].pricing{}→ Standard installments (no promotion ID)paymentMethodFee[].pricingFees[].promos[].pricing{}→ Installments linked to a specificPROMOTION_ID
Key Notes
- The
pricingFees[]array may include entries with or without apricing{}object. - The
pricingFees[]array may include entries with or without apromos[]array. - The
promos[]array can contain multiple individual promotions.
Depending on which elements are present, you can determine the installment type:
-
Standard + Promotional:
The installment plan includes both a standardpricing{}object and one or more entries in thepromos[]array.
Example: A 3-installment Mastercard plan may include a standard pricing option with interest, plus two different interest-free promotions targeting specific BINs. -
Standard-Only:
The installment plan includespricing{}but nopromos[]array.
Example: A 6-installment Visa plan offers only standard pricing with no available promotions. -
Promotional-Only:
The installment plan includes only thepromos[]array with nopricing{}object.
Example: A 3-installment AMEX plan offers interest-free terms through a promotion that applies to all AMEX cards, with no standard pricing available.
By checking these elements in the API response, you can programmatically decide which promotions to display and how to process each installment correctly.
Handling Missing Fields in Promotions
In some cases, promotions do not include certain fields. The absence of a field defines how the promotion applies.
| Missing Field | Meaning |
|---|---|
promotions[].subFranchise |
The promotion is not tied to a local card (e.g., Naranja). Instead, it applies to an international brand (e.g., Mastercard) as defined by paymentMethodMain. |
promotions[].banksNames |
The promotion applies to all banks for the payment method, with paymentMethodMain taking priority. |
promotions[].iins |
The promotion applies to all cards under the payment method specified in paymentMethodMain. |
Processing a Transaction with Standard Installments
To process a transaction using standard installments, specify the number of months in the extraParameters field:
"extraParameters": {
"INSTALLMENTS_NUMBER": (number of months)
}
<extraParameters>
<entry>
<string>INSTALLMENTS_NUMBER</string>
<string>Number of months</string>
</entry>
</extraParameters>
Processing a Transaction with General Interest-Free Installments
General Interest-Free Installments plan do not require a PROMOTION_ID. Once you configure this plan in your PayU account, submit the request with the number of months in the extraParameters field:
"extraParameters": {
"INSTALLMENTS_NUMBER": (number of months)
}
<extraParameters>
<entry>
<string>INSTALLMENTS_NUMBER</string>
<string>Number of months</string>
</entry>
</extraParameters>
Interest-Free Months (MSI) in Mexico
In Mexico, General Interest-Free Installments are commonly known as Meses sin Intereses (MSI). This option allows you to offer fixed payment plans (3, 6, 9, 12, or 18 months) without interest.
MSI transactions use the same structure as standard installments by specifying the number of months in the INSTALLMENTS_NUMBER field of the extraParameters object. Unlike promotional installments, MSI does not require a PROMOTION_ID. Valid MSI durations are 3, 6, 9, 12, or 18 months.
Fields to check:
paymentMethodFee[].pricingFees[].promos[9999].pricing.payerDetail→ no interest.paymentMethodFee[].pricingFees[].promos[9999].pricing.merchantDetail→ has interest.promotions[9999].type=PRICING
Note
Because this promotion is of typePRICING, PayU does not require including the 9999 promotion ID to create the transaction or authorization.
Once you configure this plan in your PayU account, submit the request with the number of months in the extraParameters field:
"extraParameters": {
"INSTALLMENTS_NUMBER": (number of months)
}
<extraParameters>
<entry>
<string>INSTALLMENTS_NUMBER</string>
<string>Number of months</string>
</entry>
</extraParameters>
Considerations
- Supported options: 3, 6, 9, 12, or 18 months.
- Minimum purchase amounts:
- 3 months → $300 MXN
- 6 months → $600 MXN
- 9 months → $900 MXN
- 12 months → $1200 MXN
- 18 months → $1800 MXN
- MSI is available with the following banks: BANAMEX, BANCO REGIONAL DE MONTERREY S.A, BANCOPPEL, BANCO AZTECA, SCOTIABANK, HSBC, INBURSA, BANCA MIFEL SA, BANCO MULTIVA, BAJIO, CI BANCO, Afirme, Banregio, Banjercito, Banorte, Famsa, Invex, Premium Card Liverpool, Santander, and Bancomer.
- When using the promotion always display the phrase MESES SIN INTERESES during the payment process. For standard installments (no promotional installments), use PAGOS DIFERIDOS.
Notes
-
To enable MSI plans in your account, contact your sales representative.
-
For additional details, see the Payments API for Mexico.
Identifying General vs. Specific Interest-Free Installments Plans in Mexico
Because the API handles General Interest-Free Installments differently in Mexico, you may confuse them with Specific Interest-Free Installments. Use the promotions[].type field in the API response to distinguish them:
| Installment type | promotions[].type |
Description |
|---|---|---|
| Specific Interest-Free Installments | MSI |
The term MSI is common in Mexico, but the API returns MSI for all countries offering Specific Interest-Free Installments: Argentina, Colombia, Peru, and Mexico. |
| General Interest-Free Installments (Mexico) | PRICING |
In Mexico, the API uses PRICING for General Interest-Free Installments, even though they are known locally as Meses Sin Intereses (MSI). |
Processing a Transaction with Specific Interest-Free Installments
When using a Specific Interest-Free Installments plan, include both the PROMOTION_ID and INSTALLMENTS_NUMBER inside the extraParameters object in your request:
"extraParameters": {
"INSTALLMENTS_NUMBER": (number of installments),
"PROMOTION_ID": (selected promotion ID)
}
<extraParameters>
<entry>
<string>INSTALLMENTS_NUMBER</string>
<string>Number of installments</string>
</entry>
<entry>
<string>PROMOTION_ID</string>
<string>Selected promotion ID</string>
</entry>
</extraParameters>
Note
For more details on these extra parameters, see the Payments API documentation for your country:
Last modified
September 9, 2025:
Documentation updates (2c1fad8e5)