Installment payment

This example shows how to implement a complete installment flow: query the rates, display the options to the customer, and process the payment with the correct amount.

INFO

The examples use sandbox URLs. For production, replace sandboxappmax with appmax.

Scenario

A customer wants to buy a product for R$ 200.00 and pay in 3 installments. You need to:

1. Query the merchant's installment rates
2. Display the options to the customer
3. Adjust the order value to include interest
4. Process the payment

Prerequisites

This example assumes you already have:

• A valid authentication token (how to obtain)
• A customer_id for the customer (how to create)

---

1. Query the installment options

Send the total order value (in cents) to get the amounts with interest:

curl --request POST \
     --url https://api.sandboxappmax.com.br/v1/payments/installments \
     --header 'Authorization: Bearer YOUR_TOKEN' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
  "installments": 12,
  "total_value": 20000,
  "settings": true
}'

{
  "data": {
    "installments": {
      "1":  { "total": 20000 },
      "2":  { "total": 20400 },
      "3":  { "total": 20812 },
      "4":  { "total": 21228 },
      "5":  { "total": 21648 },
      "6":  { "total": 22072 },
      "7":  { "total": 22500 },
      "8":  { "total": 22932 },
      "9":  { "total": 23368 },
      "10": { "total": 23808 },
      "11": { "total": 24252 },
      "12": { "total": 24700 }
    },
    "settings": {
      "modality": "PP",
      "max_installments": 12,
      "min_installment_value": 500
    }
  }
}

2. Display the options to the customer

On your front-end, calculate the per-installment value by dividing total by the number of installments:

const installments = response.data.installments;
const options = Object.entries(installments).map(([n, { total }]) => ({
  parcelas: Number(n),
  valorParcela: total / Number(n),
  valorTotal: total,
  temJuros: total > 20000
}));

// Result:
// 1x of R$ 200.00 (interest-free)
// 2x of R$ 102.00 (total R$ 204.00)
// 3x of R$ 69.37  (total R$ 208.12)
// ...

Display to the customer — try changing the value and selecting an installment below:

CheckoutIllustrative

Products

Shipping

Discount

TotalR$190.00

Installments

TotalR$197.71

TIP

The component above is interactive and uses illustrative values based on the example above. In production, query POST /v1/payments/installments to get the official values configured by Appmax.

3. Create the order with the adjusted value

The customer chose 3 installments. The total with interest is R$ 208.12 (20812 cents). Distribute the interest across the products:

WARNING

The system does not calculate interest automatically. You must send the value with interest already included, either in unit_value of the products or in products_value.

Option A -- Adjust via products_value (simpler):

curl --request POST \
     --url https://api.sandboxappmax.com.br/v1/orders \
     --header 'Authorization: Bearer YOUR_TOKEN' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
  "customer_id": 2023,
  "products_value": 20812,
  "products": [
    {
      "sku": "CURSO-001",
      "name": "Curso de culinária",
      "quantity": 1,
      "type": "digital"
    }
  ]
}'

Option B -- Adjust via unit_value (when there are multiple products):

curl --request POST \
     --url https://api.sandboxappmax.com.br/v1/orders \
     --header 'Authorization: Bearer YOUR_TOKEN' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
  "customer_id": 2023,
  "products": [
    {
      "sku": "CURSO-001",
      "name": "Curso de culinária",
      "quantity": 1,
      "unit_value": 20812,
      "type": "digital"
    }
  ]
}'

Response:

{
  "data": {
    "order": {
      "id": 4001,
      "status": "pendente"
    }
  }
}

4. Process the installment payment

Submit the payment specifying the number of installments:

curl --request POST \
     --url https://api.sandboxappmax.com.br/v1/payments/credit-card \
     --header 'Authorization: Bearer YOUR_TOKEN' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
  "order_id": 4001,
  "customer_id": 2023,
  "payment_data": {
    "credit_card": {
      "token": "422146c7523a46119d6073ea56193913",
      "holder_document_number": "25226493029",
      "holder_name": "Junior Almeida",
      "installments": 3,
      "soft_descriptor": "MINHALOJA"
    }
  }
}'

{
  "data": {
    "order": {
      "id": 4001,
      "status": "autorizado"
    },
    "payment": {
      "method": "creditcard",
      "installments": 3,
      "paid_at": "2025-03-15 14:30:00"
    }
  }
}

On the customer's card statement it will show: 3x of R$ 69.37.

5. Verify the result

Query the order to see the value breakdown:

curl --request GET \
     --url https://api.sandboxappmax.com.br/v1/orders/4001 \
     --header 'Authorization: Bearer YOUR_TOKEN' \
     --header 'Accept: application/json'

{
  "data": {
    "order": {
      "id": 4001,
      "status": "aprovado",
      "total_paid": 20812,
      "amounts": {
        "sub_total": 20000,
        "shipping_value": 0,
        "discount": 0,
        "installment_fee": 812
      }
    },
    "payment": {
      "method": "creditcard",
      "installments": 3,
      "installments_amount": 6937
    }
  }
}

The installment_fee field shows exactly how much interest was charged (R$ 8.12).

---

Summary

Step	What to do	Watch out for
Query installments	POST /v1/payments/installments	Send settings: true to know the maximum number of installments
Display options	Divide total by the number of installments	Indicate "interest-free" when total == original_value
Create order	Send the value with interest included	Use products_value or adjust each unit_value
Pay	Specify installments in the payment	The number of installments must match the value sent