--- updatedAt: 2026-06-03T12:16:05.000Z agentTools: projectIndex: https://docs.asaas.com/llms.txt --- # Create Installment # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "title": "Asaas", "description": "API pública de integração com a plataforma Asaas.", "version": "3.0.0" }, "servers": [ { "url": "https://api-sandbox.asaas.com", "description": "Sandbox" } ], "security": [ { "Authorization": [] } ], "tags": [ { "name": "Installment" } ], "paths": { "/v3/installments": { "post": { "tags": [ "Installment" ], "summary": "Create Installment", "description": "", "operationId": "create-installment", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallmentSaveRequestDTO" } } } }, "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallmentGetResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDTO" }, "example": { "errors": [ { "code": "invalid_object", "description": "Informe o número de parcelas." } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDTO" }, "example": { "errors": [ { "code": "invalid_access_token", "description": "A chave de API fornecida é inválida" } ] } } } } }, "deprecated": false } } }, "components": { "schemas": { "ErrorResponseDTO": { "type": "object", "properties": { "errors": { "type": "array", "description": "List of objects", "deprecated": false, "items": { "$ref": "#/components/schemas/ErrorResponseItemDTO" } } } }, "ErrorResponseItemDTO": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code", "deprecated": false, "example": null }, "description": { "type": "string", "description": "Error description", "deprecated": false, "example": null } }, "description": "List of objects", "deprecated": false }, "PaymentChargebackResponseDTO": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique chargeback identifier.", "example": "8e784c3e-afe8-4844-bb93-6b445763", "deprecated": false }, "payment": { "type": "string", "description": "Unique payment identifier in Asaas", "example": "pay_pBtDdshgBD2Rt", "deprecated": false }, "installment": { "type": "string", "description": "Unique installment identifier in Asaas", "example": "b8dd74c-d078-40a0-9ae1-61a66c61a204", "deprecated": false }, "customerAccount": { "type": "string", "description": "Unique identifier of customer to which the chargeback is linked.", "example": "cus_000000004085", "deprecated": false }, "status": { "$ref": "#/components/schemas/PaymentChargebackResponseChargebackStatus" }, "reason": { "$ref": "#/components/schemas/PaymentChargebackResponseChargebackReason" }, "disputeStartDate": { "type": "string", "description": "Chargeback opening date.", "format": "date", "example": "2024-11-10", "deprecated": false }, "value": { "type": "number", "description": "Chargeback value.", "example": 2323.45, "deprecated": false }, "paymentDate": { "type": "string", "description": "Payment date on Asaas", "format": "date", "example": "2024-03-10", "deprecated": false }, "creditCard": { "$ref": "#/components/schemas/ChargebackCreditCardResponseDTO" }, "disputeStatus": { "$ref": "#/components/schemas/PaymentChargebackResponseChargebackDisputeStatus" }, "deadlineToSendDisputeDocuments": { "type": "string", "description": "Deadline to send dispute documents.", "format": "date", "example": "2024-12-10", "deprecated": false } } }, "PaymentChargebackResponseChargebackStatus": { "type": "string", "description": "Chargeback status", "example": "DONE", "deprecated": false, "enum": [ "REQUESTED", "IN_DISPUTE", "DISPUTE_LOST", "REVERSED", "DONE" ] }, "PaymentChargebackResponseChargebackReason": { "type": "string", "description": "Chargeback reason", "example": "COMMERCIAL_DISAGREEMENT", "deprecated": false, "enum": [ "ABSENCE_OF_PRINT", "ABSENT_CARD_FRAUD", "CARD_ACTIVATED_PHONE_TRANSACTION", "CARD_FRAUD", "CARD_RECOVERY_BULLETIN", "COMMERCIAL_DISAGREEMENT", "COPY_NOT_RECEIVED", "CREDIT_OR_DEBIT_PRESENTATION_ERROR", "DIFFERENT_PAY_METHOD", "FRAUD", "INCORRECT_TRANSACTION_VALUE", "INVALID_CURRENCY", "INVALID_DATA", "LATE_PRESENTATION", "LOCAL_REGULATORY_OR_LEGAL_DISPUTE", "MULTIPLE_ROCS", "ORIGINAL_CREDIT_TRANSACTION_NOT_ACCEPTED", "OTHER_ABSENT_CARD_FRAUD", "PROCESS_ERROR", "RECEIVED_COPY_ILLEGIBLE_OR_INCOMPLETE", "RECURRENCE_CANCELED", "REQUIRED_AUTHORIZATION_NOT_GRANTED", "RIGHT_OF_FULL_RECOURSE_FOR_FRAUD", "SALE_CANCELED", "SERVICE_DISAGREEMENT_OR_DEFECTIVE_PRODUCT", "SERVICE_NOT_RECEIVED", "SPLIT_SALE", "TRANSFERS_OF_DIVERSE_RESPONSIBILITIES", "UNQUALIFIED_CAR_RENTAL_DEBIT", "USA_CARDHOLDER_DISPUTE", "VISA_FRAUD_MONITORING_PROGRAM", "WARNING_BULLETIN_FILE" ] }, "ChargebackCreditCardResponseDTO": { "type": "object", "properties": { "number": { "type": "string", "description": "Last 4 digits of the card used", "example": "8829", "deprecated": false }, "brand": { "$ref": "#/components/schemas/ChargebackCreditCardResponseCreditCardBrand" } }, "description": "Credit card information", "deprecated": false }, "ChargebackCreditCardResponseCreditCardBrand": { "type": "string", "description": "Flag of the card used", "example": "VISA", "deprecated": false, "enum": [ "VISA", "MASTERCARD", "ELO", "DINERS", "DISCOVER", "AMEX", "CABAL", "BANESCARD", "CREDZ", "SOROCRED", "CREDSYSTEM", "JCB", "UNKNOWN" ] }, "PaymentChargebackResponseChargebackDisputeStatus": { "type": "string", "description": "Chargeback dispute status.", "example": "ACCEPTED", "deprecated": false, "enum": [ "REQUESTED", "ACCEPTED", "REJECTED" ] }, "InstallmentGetResponseDTO": { "type": "object", "properties": { "object": { "type": "string", "description": "Object type", "example": "installment", "deprecated": false }, "id": { "type": "string", "description": "Unique installment identifier in Asaas", "example": "2765d086-c7c5-5cca-898a-4262d212587c", "deprecated": false }, "value": { "type": "number", "description": "Installment amount", "example": 360, "deprecated": false }, "netValue": { "type": "number", "description": "Net installment amount", "example": 312.12, "deprecated": false }, "paymentValue": { "type": "number", "description": "Value of each installment", "example": 30, "deprecated": false }, "installmentCount": { "type": "integer", "description": "Number of installments", "format": "int32", "example": 12, "deprecated": false }, "billingType": { "$ref": "#/components/schemas/InstallmentGetResponseBillingType" }, "paymentDate": { "type": "string", "description": "Bill settlement date on Asaas", "format": "date", "deprecated": false, "example": null }, "description": { "type": "string", "description": "Description of the installment", "example": "Order 056984", "deprecated": false }, "expirationDay": { "type": "integer", "description": "Due date of each installment", "format": "int32", "example": 31, "deprecated": false }, "dateCreated": { "type": "string", "description": "Installment creation date", "format": "date", "example": "2021-01-19", "deprecated": false }, "customer": { "type": "string", "description": "Unique identifier of the customer to whom the installment belongs", "example": "cus_000000001645", "deprecated": false }, "paymentLink": { "type": "string", "description": "Unique identifier of the payment link to which the installment belongs", "example": "997152082166122", "deprecated": false }, "checkoutSession": { "type": "string", "description": "Unique checkout identifier", "example": "5a3e564f-81cd-4f4e-9c8e-af43f9ac4287", "deprecated": false }, "transactionReceiptUrl": { "type": "string", "description": "URL of proof of confirmation, receipt, reversal or removal.", "deprecated": false, "example": null }, "chargeback": { "$ref": "#/components/schemas/PaymentChargebackResponseDTO" }, "creditCard": { "$ref": "#/components/schemas/PaymentSaveWithCreditCardCreditCardDTO" }, "deleted": { "type": "boolean", "description": "Indicates whether the installment has been removed", "example": false, "deprecated": false }, "refunds": { "type": "array", "description": "Refunds information", "deprecated": false, "items": { "$ref": "#/components/schemas/InstallmentRefundResponseDTO" } }, "threeDSecureChallengeUrl": { "type": "string", "description": "URL to which the cardholder must be redirected to complete the 3D Secure authentication challenge. Only returned when the authentication challenge is required by the card issuer", "deprecated": false, "example": null } } }, "InstallmentGetResponseBillingType": { "type": "string", "description": "Form of payment", "example": "CREDIT_CARD", "deprecated": false, "enum": [ "UNDEFINED", "BOLETO", "CREDIT_CARD", "DEBIT_CARD", "TRANSFER", "DEPOSIT", "PIX" ] }, "PaymentSaveWithCreditCardCreditCardDTO": { "type": "object", "properties": { "creditCardNumber": { "type": "string", "description": "Last 4 digits of the card used", "example": "8829", "deprecated": false }, "creditCardBrand": { "$ref": "#/components/schemas/PaymentSaveWithCreditCardCreditCardCreditCardBrand" }, "creditCardToken": { "type": "string", "description": "Credit card token if tokenization is active.", "deprecated": false, "example": null } }, "description": "Credit card information", "deprecated": false }, "PaymentSaveWithCreditCardCreditCardCreditCardBrand": { "type": "string", "description": "Flag of the card used", "example": "VISA", "deprecated": false, "enum": [ "VISA", "MASTERCARD", "ELO", "DINERS", "DISCOVER", "AMEX", "CABAL", "BANESCARD", "CREDZ", "SOROCRED", "CREDSYSTEM", "JCB", "UNKNOWN" ] }, "InstallmentRefundResponseDTO": { "type": "object", "properties": { "dateCreated": { "type": "string", "description": "Refund creation date", "format": "date-time", "example": "2024-10-18 10:19:06", "deprecated": false }, "status": { "$ref": "#/components/schemas/InstallmentRefundResponsePaymentRefundStatus" }, "value": { "type": "number", "description": "Refund value", "example": 40, "deprecated": false }, "endToEndIdentifier": { "type": "string", "description": "(Pix only) Unique identifier of the Pix transaction at the Central Bank", "deprecated": false, "example": null }, "description": { "type": "string", "description": "Description of the refund", "deprecated": false, "example": null }, "effectiveDate": { "type": "string", "description": "(Pix only) Refund effective date", "format": "date-time", "example": "2024-10-19 10:19:06", "deprecated": false }, "transactionReceiptUrl": { "type": "string", "description": "Transaction receipt link", "deprecated": false, "example": null }, "refundedSplits": { "type": "array", "description": "Refunded Splits, if any", "deprecated": false, "items": { "$ref": "#/components/schemas/PaymentRefundedSplitResponseDTO" } }, "paymentId": { "type": "string", "description": "Unique payment identifier in Asaas", "example": "pay_080225913252", "deprecated": false } }, "description": "Refunds information", "deprecated": false }, "InstallmentRefundResponsePaymentRefundStatus": { "type": "string", "description": "Refund status", "example": "DONE", "deprecated": false, "enum": [ "PENDING", "AWAITING_CRITICAL_ACTION_AUTHORIZATION", "AWAITING_CUSTOMER_EXTERNAL_AUTHORIZATION", "CANCELLED", "DONE" ] }, "PaymentRefundedSplitResponseDTO": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique split identifier", "example": "cff860dd-148e-48ca-ac8e-849684175158", "deprecated": false }, "value": { "type": "number", "description": "Refunded value", "example": 10, "deprecated": false }, "done": { "type": "boolean", "description": "Indicates whether the split was refunded", "example": true, "deprecated": false } }, "description": "Refunded Splits, if any", "deprecated": false }, "InstallmentSaveRequestDTO": { "required": [ "installmentCount", "customer", "value", "billingType", "dueDate" ], "type": "object", "properties": { "installmentCount": { "type": "integer", "description": "Number of installments", "format": "int32", "nullable": false, "example": 3, "deprecated": false }, "customer": { "type": "string", "description": "Unique customer identifier in Asaas", "nullable": false, "example": "cus_G7Dvo4iphUNk", "deprecated": false }, "value": { "type": "number", "description": "Value of each installment", "nullable": false, "example": 100, "deprecated": false }, "totalValue": { "type": "number", "description": "Total installment amount", "example": 150, "deprecated": false }, "billingType": { "$ref": "#/components/schemas/InstallmentSaveRequestBillingType" }, "dueDate": { "type": "string", "description": "Due date of the first installment", "format": "date", "nullable": false, "example": "2025-07-08", "deprecated": false }, "description": { "type": "string", "description": "Installment description (max. 500 characters)", "example": "Installment 08652", "deprecated": false }, "postalService": { "type": "boolean", "description": "Define whether the payment will be sent via post", "example": false, "deprecated": false }, "daysAfterDueDateToRegistrationCancellation": { "type": "integer", "description": "Days after registration cancellation deadline (only for bank slip)", "format": "int32", "example": 1, "deprecated": false }, "paymentExternalReference": { "type": "string", "description": "Free search field", "example": "056984", "deprecated": false }, "discount": { "$ref": "#/components/schemas/PaymentDiscountDTO" }, "interest": { "$ref": "#/components/schemas/PaymentInterestRequestDTO" }, "fine": { "$ref": "#/components/schemas/PaymentFineRequestDTO" }, "splits": { "type": "array", "description": "Split Settings", "deprecated": false, "items": { "$ref": "#/components/schemas/InstallmentSplitRequestDTO" } } } }, "InstallmentSaveRequestBillingType": { "type": "string", "description": "Payment billing type", "nullable": false, "example": "BOLETO", "deprecated": false, "enum": [ "UNDEFINED", "BOLETO", "CREDIT_CARD", "PIX" ] }, "PaymentDiscountDTO": { "type": "object", "properties": { "value": { "type": "number", "description": "Percentage or fixed amount of discount to be applied to the Payment amount", "example": 10, "deprecated": false }, "dueDateLimitDays": { "type": "integer", "description": "Days before expiration to apply discount. Ex: 0 = until expiration, 1 = up to one day before, 2 = up to 2 days before, and so on", "format": "int32", "example": 0, "deprecated": false }, "type": { "$ref": "#/components/schemas/PaymentDiscountDiscountType" } }, "description": "Discount information", "deprecated": false }, "PaymentDiscountDiscountType": { "type": "string", "description": "Discount type", "example": "PERCENTAGE", "deprecated": false, "enum": [ "FIXED", "PERCENTAGE" ] }, "PaymentInterestRequestDTO": { "type": "object", "properties": { "value": { "type": "number", "description": "Percentage of interest per month on the amount charged for payment after maturity", "deprecated": false, "example": null } }, "description": "Interest information for payment after due date", "deprecated": false }, "PaymentFineRequestDTO": { "type": "object", "properties": { "value": { "type": "number", "description": "Percentage of fine on the amount of the charge for payment after the due date", "deprecated": false, "example": null }, "type": { "$ref": "#/components/schemas/PaymentFineRequestFineType" } }, "description": "Fine information for payment after due date", "deprecated": false }, "PaymentFineRequestFineType": { "type": "string", "description": "Fine type", "example": "FIXED", "deprecated": false, "enum": [ "FIXED", "PERCENTAGE" ] }, "InstallmentSplitRequestDTO": { "required": [ "walletId" ], "type": "object", "properties": { "walletId": { "type": "string", "description": "Asaas wallet identifier that will be transferred", "nullable": false, "deprecated": false, "example": null }, "fixedValue": { "type": "number", "description": "Fixed amount to be transferred to the account when the payment is received", "deprecated": false, "example": null }, "percentualValue": { "type": "number", "description": "Percentage of the net value of the charge to be transferred when received", "deprecated": false, "example": null }, "totalFixedValue": { "type": "number", "description": "(Instalments only). Amount that will be split relative to the total amount that will be paid in installments.", "deprecated": false, "example": null }, "externalReference": { "type": "string", "description": "Split identifier in your system", "deprecated": false, "example": null }, "description": { "type": "string", "description": "Split description", "deprecated": false, "example": null }, "installmentNumber": { "type": "integer", "description": "Installment number to which the split will be linked. Cannot be provided along with the 'totalFixedValue' field", "format": "int32", "deprecated": false, "example": null } }, "description": "Split Settings", "deprecated": false } }, "securitySchemes": { "Authorization": { "type": "apiKey", "name": "access_token", "in": "header" } } }, "x-readme": { "headers": [ { "key": "User-Agent", "value": "NomeDaSuaAplicacao/1.0.0" } ] } } ``` # Sibling pages * [List installments](https://docs.asaas.com/reference/list-installments.md) * [Create Installment with credit card](https://docs.asaas.com/reference/create-installment-with-credit-card.md) * [Retrieve a single installment](https://docs.asaas.com/reference/retrieve-a-single-installment.md) * [Remove installment](https://docs.asaas.com/reference/remove-installment.md) * [List payments of a installment](https://docs.asaas.com/reference/list-payments-of-a-installment.md) * [Generate installment booklet](https://docs.asaas.com/reference/generate-installment-booklet.md) * [Refund installment](https://docs.asaas.com/reference/refund-installment.md) * [Update installment splits](https://docs.asaas.com/reference/update-installment-splits.md) * [Cancel charges of an installment (pending and overdue)](https://docs.asaas.com/reference/cancel-charges-of-an-installment.md)