Installments

Installments allow customers to split their payments into multiple smaller amounts over a set period, making purchases more accessible and manageable. This feature is available exclusively for credit card transactions.

Merchants can retrieve information about available installment plans and their associated fees through the Localpayment API. This data helps businesses offer installment options that best suit their customers, enhancing the purchasing experience and increasing conversion rates.

How it Works

The process of making installments through Localpayment involves the following steps:

Payment Method Selection: Your customer selects the credit card payment method and chooses to pay in installments.
Installments Plan Quote: Your application requests a quote for the available installment plans to display to the customer.
Installments Selection: Your customer selects the number of installments to split the payment.
Payment Information Collection: Your application securely collects the necessary payment information and any additional required data from the customer. This information is then sent to Localpayment for processing.
Payment Processing: Localpayment processes the payment information.
Transaction Result: Localpayment returns a response to your application with the result of the transaction. If successful, the funds are debited from the customer's card and will be transferred to your Localpayment account.
Confirmation to Customer: Your application displays the transaction result to the customer, allowing them to proceed with their purchase.
Automated Installment Charges: The customer's account will be automatically debited according to the configured installment plan.

Availability

Installments processing is available in the following countries:

🇦🇷 Argentina: Visa, Mastercard, American Express, Diners, Argencard, Cabal.
🇧🇴 Bolivia: Visa.
🇧🇷 Brazil: Visa, Mastercard, American Express, Elo, Hipercard.
🇨🇱 Chile: Visa, Mastercard, American Express, Diners, Magna.
🇨🇴 Colombia: Visa, Mastercard, American Express, Diners.
🇩🇴 Dominic Republic: Visa.
🇲🇽 Mexico: Visa, Mastercard, American Express.
🇵🇦 Panama: Visa.
🇵🇪 Peru: Visa, Mastercard, American Express, Diners.

Before quoting installment plan

Before quoting installment plan, ensure you have completed the following:

Generate an Access Token (Required): You'll need a valid access token to authenticate your API requests. Refer to the Generate an Access Token documentation for instructions.
Get Available Payment Methods (Required): You must retrieve a list of available payment methods configured for your Localpayment account. This will provide you with the necessary payment method codes. See the Get Available Payment Methods documentation for details.

Quote installment plan

To quote an installment plan, you'll need to send a POST request to the Generate Installment Plan Quote endpoint.

ℹ️
Token expiration
The obtained token is only valid for 10 minutes.

Request Example

Below is an example using curl:

curl --request POST \
     --url https://api.stage.localpayment.com/api/installments-plans \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "paymentMethod": {
    "code": "1000"
  },
  "country": "ARG",
  "currency": "ARS",
  "amount": 1000,
  "accountNumber": "032.032.00000002"
}
'

Parameters

paymentMethod: Object with payment method information.
paymentMethod.code: Payment method code (e.g. 1000).
country: Set the country from which the operation is made. ISO 3166-1 alpha-3 (e.g. ARG).
currency: The currency of the amount can be the local currency (charged directly) or the account's currency (triggering a Foreign Exchange operation), with paymentMethod.code resolving ambiguity in bicurrency countries. E.g. ARS.
amount: Transaction amount (e.g. 1000).
accountNumber: The Localpayment account number where the specified amount will be credited.

See all available parameters in the request.

Successful response example

{
  "installmentsToken": "bc1a1973-fadc-427b-b014-e43eb4462e82",
  "creationDate": "2025-01-29T23:53:52.7150456+00:00",
  "expirationDate": "2025-01-30T00:03:52.71509+00:00",
  "currency": "ARS",
  "amount": 2000,
  "installments": [
    {
      "installments": 2,
      "installmentAmount": 1100,
      "totalPaymentAmount": 2200,
      "financingFee": 200
    },
    {
      "installments": 3,
      "installmentAmount": 941.71,
      "totalPaymentAmount": 2825.15,
      "financingFee": 825.15
    },
    {
      "installments": 6,
      "installmentAmount": 633.17,
      "totalPaymentAmount": 3799.04,
      "financingFee": 1799.04
    }
  ]
}

Key Fields in the Response

installmentsToken: Token for the installments plan quote. This must be sent in the request when creating a One-time payment.
creationDate: Timestamps for when the transaction was created and processed.
installments: Object containing the payment options quote.

Make an installment payment

To process a payment in installments, you must include the installments property within the card object, specifying the desired number of installments when making a One-time payment request. Additionally, if you have previously obtained an installmentsToken (valid for 10 minutes), you must also include this token in the card object.

Request example

curl --request POST \
  --url https://api.stage.localpayment.com/api/payin/ \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "paymentMethod": {
        "type": "CreditCard",
        "code": "1000",
        "flow": "DIRECT"
    },
    "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
    "country": "ARG",
    "currency": "ARS",
    "amount": 1000,
    "accountNumber": "032.032.00000000",
    "conceptCode": "0001",
    "merchant": {
        "type": "COMPANY",
        "name": "Company",
        "document": {
            "type": "CUIT",
            "id": "3000091105"
        },
        "email": "[email protected]",
        "phone": {
            "countryCode": "54",
            "areaCode": "351",
            "number": "1234567"
        }
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "DNI",
            "id": "37993123"
        },
        "email": "[email protected]",
        "phone": {
            "countryCode": "1",
            "areaCode": "11",
            "number": "98189123"
        },
        "bank": {
            "name": "BANCO BBVA ARGENTINA S.A.",
            "code": "017",
            "account": {
                "type": "S",
                "number": "19101196551119123456789"
            }
        }
    },
    "commercialData": {
        "items": [
            {
                "id": "12345",
                "quantity": "1",
                "description": "Test product",
                "title": "Test",
                "unitPrice": "1000"
            }
        ]
    },
    "card": {
        "number": "4000000000000002",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2029",
        "installments": 3,
        "installmentsToken": "bc1a1973-fadc-427b-b014-e43eb4462e82"
    }
}'

Review the One-Time Payments documentation for more information.

Next Steps

After an installment payment is processed, you may need to perform additional actions, such as:

Refund the transaction: If necessary, you can refund the payment to the customer. Refer to the Refunds documentation for details.
Handle chargebacks: In case of a dispute, you may need to handle chargebacks. Refer to the Chargebacks documentation for information on this process.
Review transaction details: You can retrieve transaction information using the Localpayment API. See the Transaction Information documentation for details.

How it Works

Availability

Before quoting installment plan

Quote installment plan

ℹ️Token expiration

Make an installment payment

Next Steps

ℹ️
Token expiration