Create Payments with Installments

This guide explains how to process installment-based payment transactions using the Getnet Global API. Installments allow customers to divide the total purchase price into several smaller, equal amounts paid over an agreed period of time, providing greater flexibility instead of requiring full payment upfront. This payment method’s implementation depends on card support availability and regional regulations.

Requirements

Before following the steps, you need to:

• Create your account by contacting the Integration Support team to get your API credentials client_id and client_secret.
• Generate your token with your credentials using the Authentication endpoint.

Getnet provides a Postman Collection to help you to replicate these use cases locally. You can also test the API in sandbox using the API Reference available in the documentation.

Use Cases Specifics

When integrating any Getnet solution, market-specific requirements apply. Be sure to review the resources below before you go live:

• Currency codes
• Document types
• Local taxes and regulations

You can also use test cards to simulate specific scenarios. More information about specific requirements for each country can be found in the Developer Resources section of the Getnet documentation.

Payment facilitators: When Getnet enables your credential as a payment facilitator, you must also send the data.sub_merchant object on this request. See Payment Facilitators.

Platform availability

Installment support varies by country and card brand. For a complete reference of installment rules, available card schemes, and plan types by market, see Installments Rules and Availability.

Understanding How Installment Payments Work

An installment payment is created as a single payment transaction, not multiple separate authorizations. When you create an installment payment, you make one API call, and the settlement/capture is handled automatically by the card network and issuing banks according to the installment plan type.

How Settlement Works

Each country has different installment plan types with specific schemas and settlement models. The settlement process varies depending on the plan selected:

• Some plans settle the full amount to the merchant at once, with the bank collecting installments from the customer over time.
• Other plans settle to the merchant in monthly installments automatically.
• The customer may or may not pay interest depending on the plan type.

For detailed information about installment plans, schemas, and settlement models available in each country, see Installments Rules and Availability.

Installment Payment Process

This section guides you through creating an installment payment transaction. The process involves two main steps: requesting available installment offers and submitting the payment with the selected installment option.

The diagram below illustrates the complete installment payment flow:

Quote ID Generation

When implementing installments in Argentina and Chile markets, it is mandatory to include the quote_id value in the API installment requests so transactions can be processed correctly. This field is used to calculate interest rates, taxes, and other requirements prior to payment authorization.

Interest fees calculations

For this process, there are two alternatives for merchants and partners, depending on their needs:

• Calculated by User: The merchant calculates the interest fees externally and informs the API through the amount field. On API calls, the quote_id must be generated under no_interest.
• Calculated by Getnet: The merchant relies on Getnet’s interest fees calculations that include up-to-date issuer/government information and therefore won’t have to calculate them externally. On API calls, the quote_id must be generated under with_interest.

Tokenize Card Data (Optional)

Instead of sending the raw card number in your payment request, you can use tokenization to enhance security and reduce PCI DSS compliance scope. To use a tokenized card:

1. Tokenize the card by calling the Card Tokenization endpoint with the card_number and customer_id.
2. In your payment request, replace the card.number field with card.number_token using the token value received from the tokenization endpoint.

Step 1: Request Available Installment Offers

Before initiating a payment, you must query the available installment offers for the selected card and transaction amount using the Get Installments endpoint.

The Getnet API expects to receive the following details in the request:

The following code block shows an example request:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments/quotes \
  --header 'authorization: Bearer ' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --data '{
  "amount": 100000,
  "bin": "515590122",
  "installment_type_filter": "no_interest"
}'

Example response with available installment options:

{
  "quote_id": "4a29251d-41af-41fc-ac74-fa131e215e1b",
  "amount": 100000,
  "currency": "BRL",
  "credits": [
    {
      "number_installments": 1,
      "installment_value": 100000,
      "total_amount": 100000,
      "schema": "no_interest",
      "type": "no_interest"
    },
    {
      "number_installments": 3,
      "installment_value": 33334,
      "total_amount": 100002,
      "schema": "no_interest",
      "type": "no_interest"
    },
    {
      "number_installments": 6,
      "installment_value": 16667,
      "total_amount": 100002,
      "schema": "no_interest",
      "type": "no_interest"
    }
  ]
}

You’ll need to extract the following properties from the response to use in the next step:

• quote_id - Unique identifier for the installment quote
• schema - Code that groups credits by category

Step 2: Create the Payment with Installments

Once the customer has selected their preferred installment option, use the Create - Authorize endpoint to process the payment.

The Getnet API expects to receive the installment details within the additional_data object. If the installment object is included, the payment will be made according to the previously defined number of installments; otherwise, the payment will be made in a single installment.

Country-specific requirements: Some markets may require additional mandatory fields. In Uruguay you must include a rates array with the iva key. Send regional_regulation_code only when the transaction qualifies for a regional regulation or tax benefit. Each entry takes a code (17934 or 19210) and an optional invoice of up to 9 alphanumeric characters. When you omit the invoice, Getnet derives it from your order_id. Review the Taxes and Regulations reference for more information.

The table below lists the minimum fields you need to send:

The objects required for antifraud validation must include the following fields:

Antifraud data is mandatory for production environments. Transactions missing device fingerprint or customer information will be automatically blocked by antifraud teams to prevent fraud. See the Antifraud documentation for complete implementation details.

The following code block shows an example payment request with installments:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer ' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "ORDER-10187383",
  "data": {
    "amount": 100000,
    "currency": "BRL",
    "customer_id": "test",
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "document_type": "CPF",
      "document_number": "12345678900",
      "phone_number": "+5511999999999",
      "billing_address": {
        "street": "Av. Paulista",
        "number": "1000",
        "complement": "Apto 101",
        "district": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR",
        "postal_code": "01310-100"
      }
    },
    "payment": {
      "payment_method": "CREDIT",
      "save_card_data": false,
      "transaction_type": "INSTALL_NO_INTEREST",
      "number_installments": 3,
      "soft_descriptor": "LOJA*TESTE*COMPRA-123",
      "dynamic_mcc": 1799,
      "card": {
        "number": "5155901222260000",
        "expiration_month": "09",
        "expiration_year": "30",
        "cardholder_name": "Card Holder",
        "security_code": "517"
      }
    },
    "additional_data": {
      "installment": {
        "schema": "no_interest",
        "type": "no_interest",
        "quote_id": "4a29251d-41af-41fc-ac74-fa131e215e1b"
      },
      "device": {
        "ip_address": "192.168.1.1",
        "device_id": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
        "finger_print": "1a2b3c4d5e6f7g8h9i0j"
      }
    }
  }
}'

Example of response with status as APPROVED:

{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
  "seller_id": "e0ed6f00-fdc5-46d6-9557-6a2cac641b09",
  "payment_id": "053de7f9-3725-437b-bdfc-bbf3ed0acb75",
  "order_id": "ORDER-10187383",
  "amount": 100000,
  "currency": "BRL",
  "status": "APPROVED",
  "payment_method": "CREDIT",
  "received_at": "2025-10-31T13:40:47.382Z",
  "transaction_id": "MCC50205G1020",
  "original_transaction_id": "MCC50205G1020",
  "authorized_at": "2025-10-31T13:40:47.382Z",
  "reason_code": "00",
  "reason_message": "captured",
  "acquirer": "GETNET",
  "soft_descriptor": "LOJA*TESTE*COMPRA-123",
  "brand": "MASTERCARD",
  "authorization_code": "204050",
  "acquirer_transaction_id": "405030304060404030501060",
  "installments": {
    "number_installments": 3,
    "installment_value": 33334,
    "total_amount": 100002
  }
}

Step 3: Check the Payment Status (Optional)

The Create - Authorize response will show the status as APPROVED for successful installment payments.

Because some payments are processed asynchronously, the status can change over time. To get the latest status of a transaction, use the Get Transaction endpoint.

For real-time updates without polling, it is recommended to use Webhooks to receive notifications for every status change.

Country-Specific Installment Requirements

Each market has specific installment options, plan types, and implementation requirements. For detailed information about installment rules, available plans by card brand, and country-specific requirements (including required field values for the installment object), see Installments Rules and Availability.

Next Steps

Now that you have successfully created a payment with installments, you can explore more features of the Getnet Global API:

• Learn how to create Combined Payments.
• Read about 3DS Payments.
• Explore Pre-authorization Payments.