Installments

Localpayment enables merchants to offer installment plans, allowing customers to split their purchases into multiple monthly payments. This guide outlines the process for creating installment plans through Localpayment's API, detailing required parameters, handling responses, and managing the complete installment lifecycle.

Before You Begin

Ensure you have:

Step 1: Create Installment Plan Quote

Before processing an installment payment, you need to generate an installment plan quote to present payment options to the customer.

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

Key Request Parameters

Example Request

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": "1600"
  },
  "country": "MEX",
  "currency": "MXN",
  "amount": 1000,
  "accountNumber": "{{accountNumber}}"
}
'

See all available parameters in the request.

Step 2: Handle the Quote Response

Successful Response

A successful installment quote includes detailed payment plan information:

{
  "installmentsToken": "bc1a1923-fadc-427b-b014-e43eb4462e81",
  "creationDate": "2025-01-29T23:53:52.7150456+00:00",
  "expirationDate": "2025-01-30T00:03:52.71509+00:00",
  "currency": "MXN",
  "amount": 1000,
  "installments": [
        {
            "installments": 3,
            "installmentAmount": 448.98,
            "totalPaymentAmount": 1346.95,
            "financingFee": 346.95
        },
        {
            "installments": 6,
            "installmentAmount": 275.68, 
            "totalPaymentAmount": 1654.12, 
            "financingFee": 654.12
        }
    ]
}

Key Response Fields

Error Response

When installment quote generation fails::

{
  "status": {
    "code": "300",
    "detail": "Instalment Payment Plan is only for types of Credit Card methods"
  }
}

Best Practices for Installment Presentation

• Display all costs clearly (financing fees, total amount)
• Show monthly payment amounts prominently
• Include comparison between different installment options
• Explain automatic payment process for future installments
• Include customer support information
• Handle token expiration gracefully (10-minute window)

Step 3: Process Installment Payment

Once the customer selects an installment plan, process the payment using the installments token.

Example Request

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": "1600",
        "flow": "DIRECT"
    },
    "externalId": "dffbd2a6-6e65-469b-8bbe-dac269882220",
    "country": "MEX",
    "currency": "MXN",
    "amount": 1000,
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "merchant": {
        "type": "COMPANY",
        "name": "Company",
        "document": {
            "type": "RFC",
            "id": "XXX840510XX1"
        },
        "email": "[email protected]"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "RFC",
            "id": "YYY180222YY6"
        },
        "email": "[email protected]"
    },
    "card": {
        "number": "4000000000000002",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2029",
        "installments": 3,
        "installmentsToken": "bc1a1923-fadc-427b-b014-e43eb4462e81"
    }
}'

Step 4: Track Installment Status

Monitor installment plan progress through these methods:

Common Status Codes

The Localpayment API provides various status codes for installment plans and payments.

📝

For complete status code reference, see the Transaction Status documentation.

Step 5: Manage Installment Lifecycle

Installment Payment Flow

sequenceDiagram
    participant C as Customer
    participant M as Merchant
    participant LP as Localpayment
    participant B as Bank
    
    C->>M: Initiate payment with installment option
    M->>LP: Request installment quote
    LP->>M: Return installmentsToken and options
    M->>C: Present installment plans
    C->>M: Select preferred plan
    M->>LP: Process payment with installmentsToken
    LP->>B: Authorize first installment
    B->>LP: Authorization confirmed
    LP->>M: Payment confirmation
    M->>C: Display payment result (approved/declined)
    Note over C: Customer receives transaction status and payment plan details
    Note over LP: Monthly installments processed automatically
    LP->>M: Webhook for each installment

Testing Your Integration

Test Scenarios

Verify your integration handles these scenarios:

1. Successful Installment: Complete installment payment flow
2. Multiple Plan Options: Present different installment terms (2, 3, 6 months)
3. Token Expiration: Handle expired installmentsToken (10-minute window)
4. Status Updates: Webhook handling and status polling.

Next Steps

After implementing installments, consider these additional capabilities::