HomeGuidesRecipesAPI Reference
Guides
Sign in
Start typing to search…

Recurring Payments

Recurring payment solution enables merchants to automatically charge customers at regular intervals, perfect for subscription services, membership programs, and installment plans. This service supports credit cards across multiple countries with flexible billing cycles.

ℹ️

Note

Recurring payments are only available for credit card transactions.

How It Works

The process for setting up recurring payments through Localpayment involves the following steps:

  1. Subscription Initiation: The customer subscribes to a service or plan in your application, providing their credit card details and other necessary information.
  2. 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.
  3. Payment Processing: Localpayment processes the payment information to set up the recurring billing agreement.
  4. Transaction Result: Localpayment returns a response to your application with the result of the subscription creation. If successful, the funds are debited from the customer's card and will be transferred to your Localpayment account.
  5. Customer Confirmation: Your application displays the transaction result to the customer, confirming the subscription setup.
  6. Recurring Charges: Localpayment will automatically charge the customer's card according to the configured schedule. Your application will receive webhook notifications with the status of each recurring payment.

Availability

Recurring payment processing is available in the following countries:

  • 🇧🇷 Brazil: Visa, Mastercard, American Express, Elo, Hipercard.
  • 🇨🇱 Chile: Visa, Mastercard, American Express, Diners, Magna.
  • 🇨🇴 Colombia: Visa, Mastercard, American Express, Diners.
  • 🇲🇽 Mexico: Visa, Mastercard, American Express.
  • 🇵🇪 Peru: Visa, Mastercard, American Express, Diners.

Before a recurring payment request

Before initiating a recurring payment, ensure you have completed the following:

  1. 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.
  2. 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.
  3. Validate Identity Document (Optional): You can optionally validate the customer's identity document information before processing the payment. This helps prevent transaction failures and ensures compliance with local regulations. Refer to the Validate Identity Document documentation for more information.
  4. Get BIN Info (Optional): You can optionally validate the card's Bank Identification Number (BIN) to obtain information such as the card brand and card type. This can help you prevent transaction rejections due to invalid card details. See the Get BIN Info documentation for more information.
  5. Get National Holidays (Optional): You can optionally retrieve information about national holidays in the relevant country. This information can be useful for anticipating potential delays in bank processing. See the Get National Holidays documentation for more information.
  6. Generate Currency Exchange Quote (Optional): If you need to process payments in a different currency than your Localpayment account's currency, you can use this step to obtain a currency exchange quote. Refer to the Generate Currency Exchange Quote documentation for details.

Request a Recurring Payment

When initiating a recurring payment, it is crucial to accurately gather and securely transmit all necessary payer information. This includes:

  1. Cardholder Details:
    • Full name (as it appears on the card)
    • Valid card number
    • Expiration date
    • CVV security code
  2. Payer Information:
    • Country-specific identification document
    • Contact information (email and phone number)
    • Billing address
  3. Transaction Details:
    • Payment amount
    • Currency (local or foreign)
    • Merchant reference ID
    • Number of subscription repetitions
    • Subscription start and end date

To request a recurring payment, send a POST request to the Create a Subscription endpoint.

Request Example

Below is an example using curl:

curl --request POST \
  --url 'https://api.stage.localpayment.com/api/payin/subscriptions/' \
  --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"
        }
    },
    "card": {
        "number": "4000000000000002",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2029"
    },
    "type": "SOFTWARE",
    "autoRecurring": {
        "repetitions": 1,
        "type": "day"
    }
}'

Parameters

  • paymentMethod: Object with payment method information.
  • paymentMethod.type: Payment method type. Send CreditCard for credit cards.
  • paymentMethod.code: Payment method code (e.g. 1000).
  • paymentMethod.flow: Set as DIRECT.
  • externalId:  A unique identifier generated by your system to track the transaction (alphanumeric and hyphens). We recommend using UUID4 to ensure uniqueness (e.g. 40bac59a-0381-4cc0-a6a5-33418d84c2e4).
  • 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.
  • conceptCode: Operation concept code (e.g. 0001 for Corporate Payments).
  • merchant: Information about the merchant initiating the transaction.
  • merchant.type: Merchant type (e.g. COMPANY).
  • merchant.name: Merchant name.
  • merchant.document: Merchant documentation information.
  • merchant.document.type: The type of identity document, such as a National Identity Number, Social Security Number, or Driver's License, depending on the country of issuance.
  • merchant.document.id: Identity document number (usually a number). This must be a valid number according to the rules for the specific document type.
  • merchant.email: Merchant email.
  • merchant.phone: Object with merchant phone number information.
  • merchant.phone.countryCode: International country code (e.g. 54).
  • merchant.phone.areaCode: Area code (e.g. 351).
  • merchant.phone.number: Phone number (e.g. 1234567).
  • payer: Object with information about the payer making the transaction.
  • payer.type: Payer type (e.g. INDIVIDUAL).
  • payer.name: Payer name.
  • payer.lastname: Payer last name.
  • payer.document: Payer documentation information.
  • payer.document.type: The type of identity document, such as a National Identity Number, Social Security Number, or Driver's License, depending on the country of issuance.
  • payer.document.id: Identity document number (usually a number). This must be a valid number according to the rules for the specific document type.
  • payer.email: Payer email.
  • payer.phone: Payer phone number.
  • payer.phone.countryCode: International country code.
  • payer.phone.areaCode: Area code.
  • payer.phone.number: Phone number.
  • payer.bank: Payer's banking information.
  • payer.bank.name: Bank name.
  • payer.bank.code: Bank code.
  • payer.bank.account: Bank account information.
  • payer.bank.account.type: Payer account type (e.g. S for Saving account).
  • payer.bank.account.number: Payer account number.
  • commercialData: Object with commercial details about the transaction.
  • commercialData.items: Array of items included in the transaction.
  • commercialData.items.id: A unique identifier for the item.
  • commercialData.items.quantity: The quantity of this item purchased.
  • commercialData.items.description: A description of the item.
  • commercialData.items.title: The title or name of the item.
  • commercialData.items.unitPrice: The price per unit of the item.
  • card: Object with card payment information.
  • card.name: Cardholder name.
  • card.number: Card number (PAN).
  • card.cvv: Card Verification Value.
  • card.expirationMonth: Card expiration month. Format MM.
  • card.expirationYear: Card expiration year. Format YYYY.
  • type: Subscription category. Required. Allowed values: SOFTWARE, STREAMING, CONTENT, PRODUCTS, MEMBERSHIP.
  • autoRecurring: Object with subscription configuration.
  • autoRecurring.repetitions: Number of charges that will be made during the subscription. For on-demand payments, set the value to 0.
  • autoRecurring.type: Unit of the recurring interval. Allowed values: day, month.
  • autoRecurring.trialDays: Number of trial days for the subscription.
  • autoRecurring.dateToStart: Subscription start date. If no date is provided, the request date will be used. Format: YYYY-MM-DD'T'HH:mm:ss.
  • retry: Object with retry information.
  • retry.repetitions: Number of retry attempts in case of payment issues.
  • retry.intervalUnit: Time unit for retries. Allowed values: day, hour.
  • retry.intervalValue: Time interval value for retries.
  • discount: Object with discount information for a subscription.
  • discount.amount: The amount charged to the user after applying the discount.
  • discount.period: Number of billing periods during which the discount applies (1-12).
  • planId: Subscription ID to associate it with a specific plan.

See all available parameters in the request.

Subscription Billing Cycles

Once a subscription is successfully created, Localpayment automates the recurring billing process according to the parameters you've defined. This means that subsequent charges to the customer's account will occur automatically, without requiring further customer interaction. Localpayment will then send webhook notifications to your application, providing real-time updates on the status of each recurring payment.

Recurring payment Status

After initiating a recurring payment, you can track the status of the suscription. The Localpayment API provides various status codes to indicate the progress and outcome of the payment in the response.

  • Successful Transaction: A successful transaction will typically have a status code of 105 (INPROGRESS).
  • Failed Transaction: A failed transaction will be indicated by an error status code. The response will include an array of error messages with details about the reason for the failure.

Successful response example

{
    "subscriptionId": "133440f9-ac06-49fc-aa82-08bfb52ceb52",
    "status": {
        "code": "105",
        "description": "INPROGRESS",
        "detail": "The subscription is in progress"
    },
    "creationDate": "2025-03-29T15:05:47.665+00:00",
    "nextPaymentDate": "2025-04-28T15:05:47.665+00:00",
    "payments": [
        {
            "externalId": "bb7d32e5-04da-4b8a-856f-8caff9d9862a",
            "internalId": "9977c253-ce00-48fd-b3ac-f68ccbe10895",
            "status": {
                "code": "103",
                "description": "APPROVED",
                "detail": "The payin was confirmed but not credited yet"
            }
        }
    ]
}

Key Fields in the Response

  • subscriptionId: A unique identifier for the suscription in your system. It will be used to perform other operations such as update or cancel the suscription.
  • internalId: A unique identifier for the transaction in Localpayment’s system.
  • status: Object with information about the status of the transaction.
  • status.code: The status code (e.g., 105 for INPROGRESS).
  • creationDate: Timestamps for when the transaction was created and processed.
  • nextPaymentDate: Date of the next scheduled payment.

For a complete list of status codes and their meanings, please refer to the Transaction Status documentation.

Localpayment also sends webhooks to your application to notify you of changes in the transaction status. For more information on webhooks, please refer to the Webhooks documentation.

Retrieve Recurring Payment Information

You can retrieve information about a previously created subscription. This request returns useful details such as the subscription status, pending payments, total successful payments, next payment date, and other relevant data.

To retrieve recurring payment information, send a GET request to the Check Subscription endpoint with the necessary parameters.

Request Example

Below is an example using curl:

curl --request GET \
     --url https://api.stage.localpayment.com/api/subscriptions/{subscriptionId} \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json'

Successful response example

{
  "externalId": "1623540689",
  "subscriptionId": "ad5bb089-1095-446f-88ca-3bf2fae3610d",
  "status": {
    "code": "202",
    "description": "COMPLETED",
    "detail": "The subscription was completed"
  },
  "totalPayments": 2,
  "pendingPayments": 0,
  "creationDate": "2021-06-12T23:31:29.869+00:00",
  "nextPaymentDate": "2021-03-14T03:00:00.000+00:00",
  "request": {
    "payer": {
      "name": "Fernando",
      "type": "INDIVIDUAL",
      "email": "[email protected]",
      "phone": {
        "number": "98789632",
        "areaCode": "11",
        "countryCode": "1"
      },
      "address": {
        "city": "Temperley",
        "state": "state",
        "number": "1234",
        "street": "Siempre viva",
        "comment": "timbre roto, llamar",
        "country": "Argentina",
        "zipCode": "1686"
      },
      "document": {
        "id": "37993830",
        "type": "DNI"
      },
      "lastname": "Gomez",
      "birthdate": "01/01/1990",
      "nationality": "Argentino",
      "userReference": "identificador del pagador"
    },
    "amount": 150,
    "device": {
      "id": "Android 9",
      "ip": "127.111.142",
      "browser": "Google Chrome"
    },
    "comment": "Primer pago",
    "country": "ARG",
    "currency": "ARS",
    "metaData": {
      "algoDelCliente": "informacion adicional del cliente"
    },
    "clientCode": "0002",
    "externalId": "1623540689",
    "beneficiary": {
      "name": "Netflix Argentina1",
      "type": "COMPANY",
      "email": "[email protected]",
      "phone": {
        "number": "98789632",
        "areaCode": "11",
        "countryCode": "1"
      },
      "address": {
        "city": "Hurlingham",
        "state": "state",
        "number": "938",
        "street": "Charruas",
        "comment": "portero 801",
        "country": "Argentina",
        "zipCode": "1688"
      },
      "document": {
        "id": "30558251405",
        "type": "CUIT"
      },
      "lastname": "Solo si es type INDIVIDUAL",
      "merchant": "Netflix001",
      "birthdate": "1994-02-20",
      "nationality": "Argentino"
    },
    "conceptCode": "String",
    "accountNumber": "032.032.00000001",
    "autoRecurring": {
      "nextPayment": "2021-01-13",
      "repetitions": 2
    },
    "paymentMethod": {
      "code": "1000",
      "flow": "DIRECT",
      "type": "CreditCard"
    },
    "commercialData": {
      "items": [
        {
          "id": "PR0001",
          "title": "Point Mini",
          "quantity": "1",
          "unitPrice": 58.8,
          "categoryId": "electronics",
          "pictureUrl": "https://http2.mlstatic.com/resources/frontend/statics/growth-sellers-landings/[email protected]",
          "description": "Producto Point para cobros con tarjetas mediante bluetooth"
        }
      ],
      "invoice": "Refencia a una factura",
      "shipments": [
        {
          "city": "Temperley",
          "state": "state",
          "number": "1234",
          "street": "Siempre viva",
          "comment": "timbre roto, llamar",
          "country": "Argentina",
          "zipCode": "1686"
        }
      ]
    },
    "intermediaries": [
      {
        "name": "Fernando",
        "type": "INDIVIDUAL",
        "email": "[email protected]",
        "phone": {
          "number": "98789632",
          "areaCode": "11",
          "countryCode": "1"
        },
        "address": {
          "city": "Temperley",
          "state": "state",
          "number": "1234",
          "street": "Siempre viva",
          "comment": "timbre roto, llamar",
          "country": "Argentina",
          "zipCode": "1686"
        },
        "document": {
          "id": "37993830",
          "type": "DNI"
        },
        "lastname": "Gomez",
        "birthdate": "01/01/1990",
        "nationality": "Argentino"
      }
    ],
    "exchangeRateToken": "String"
  },
  "payments": [
    {
      "internalId": "9341125e-6f24-4141-adb5-b2e555d58558",
      "status": {
        "code": "103",
        "description": "APPROVED",
        "detail": "The payin was confirmed but not credited yet"
      }
    },
    {
      "internalId": "887517fe-d052-4634-8d85-f1e632d3357e",
      "status": {
        "code": "103",
        "description": "APPROVED",
        "detail": "The payin was confirmed but not credited yet"
      }
    }
  ],
  "retries": 0
}

Key Fields in the Response

  • subscriptionId: Unique identifier for the subscription within Localpayment.
  • status: Object with information about the status of the transaction.
  • status.code: The status code (e.g., 103 for APPROVED).
  • totalPayments: Total number of successful payments made under this subscription.
  • pendingPayments: Number of pending payments that have not been processed yet.
  • nextPaymentDate: Date and time of the next scheduled payment (ISO 8601 format).

Update Recurring Payment

Once a recurring payment is created, it can be updated to modify various details, such as the amount, payment method (card), trial days, discounts, retries, and more. Additionally, subscriptions can be temporarily suspended if needed.

To update a recurring payment, send a PATCH request to the Update a Subscription endpoint with the necessary parameters.

Request Example

Below is an example using curl:


curl --location --request PATCH 'https://api.stage.localpayment.com/api/payin/subscriptions/{subscriptionId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your_access_token>' \
--data '{
    "dateToUpdate": "2025-04-30",
    "amount": 16000.0,

   "autoRecurring": {
        "repetitions": "3",
        "type": "month",
        "trialDays": "0"
    },

   "retry": {
    "repetitions": 2,
    "intervalUnit": "day",
    "intervalValue": 1
  }
}'

Parameters

  • amount: Transaction amount (e.g. 1000).
  • card: Object with card payment information.
  • card.name: Cardholder name.
  • card.number: Card number (PAN).
  • card.cvv: Card Verification Value.
  • card.expirationMonth: Card expiration month. Format MM.
  • card.expirationYear: Card expiration year. Format YYYY.
  • autoRecurring: Object with subscription configuration.
  • autoRecurring.repetitions: Number of charges that will be made during the subscription. For on-demand payments, set the value to 0.
  • autoRecurring.type: Unit of the recurring interval. Allowed values: day, month.
  • autoRecurring.trialDays: Number of trial days for the subscription.
  • retry: Object with retry information.
  • retry.repetitions: Number of retry attempts in case of payment issues.
  • retry.intervalUnit: Time unit for retries. Allowed values: day, hour.
  • retry.intervalValue: Time interval value for retries.
  • discount: Object with discount information for a subscription.
  • discount.amount: The amount charged to the user after applying the discount.
  • discount.period: Number of billing periods during which the discount applies (1-12).
  • planId: Subscription ID to associate it with a specific plan.
  • suspension: An object containing additional information about the subscription suspension.
  • suspension.dateToStart: The date and time when the subscription suspension should begin. Format: yyyy-MM-dd'T'HH:mm:ss.
  • suspension.dateToEnd: The date and time when the subscription suspension should end. Format: yyyy-MM-dd'T'HH:mm:ss.
  • suspension.reason: The reason for the subscription suspension.
  • status: Send the value ACTIVE when you want to immediately activate a previously suspended subscription.
  • dateToUpdate: Applies only when the requested update is required to apply to a future date. Format: YYYY-MM-DD.

See all available parameters in the request.

Successful response example

{
    "externalId": "564b161a-76ba-4a84-b5cf-583f2df8c377",
    "internalId": "52425bbd-b68b-4abc-9480-5ae88d53adb3",
    "status": {
        "code": "107",
        "description": "APPROVED",
        "detail": "Update subscription success"
    },
    "errors": []
}

Key Fields in the Response

  • externalId: A unique identifier generated by your system to track the transaction.
  • status: Object with information about the status of the transaction.
  • status.code: The status code (e.g., 107 for APPROVED).

End Recurring Payments

A subscription can be canceled after it has been created. However, cancellation is irreversible, so it should be done with caution. Once a subscription is canceled, no further payments will be processed.

A subscription is canceled either when the number of charges configured at the moment of the subscription is completed or it can be canceled using the API.

To cancel a recurring payment, send a PATCH request to the Cancel a Subscription endpoint.

Request Example

Below is an example using curl:

Curl --location --request PATCH 'https://api.stage.localpayment.com/api/subscriptions/{subscriptionId}/status' \
header 'Authorization: Bearer <your_access_token>' \
header 'Content-Type: application/json' \
--data-raw '{
    "status": "CANCEL"
}'

Parameters

  • status: This parameter must be set to CANCEL to initiate the cancellation of the subscription.

Successful response example

{
    "externalId": "564b161a-76ba-4a84-b5cf-583f2df8c377",
    "subscriptionId": "498e4a08-13a8-405e-96a5-eccb44345ada",
    "status": {
        "code": "903",
        "description": "CANCELLED",
        "detail": "The subscription was canceled - merchant request"
    }
}

Key Fields in the Response

  • externalId: A unique identifier generated by your system to track the transaction.
  • status: Object with information about the status of the transaction.
  • status.code: The status code (e.g., 903 for CANCELLED).

Next Steps

After a recurring 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.

Updated 2 months ago