---
updatedAt: 2026-06-03T12:16:05.000Z
agentTools:
projectIndex: https://docs.asaas.com/llms.txt
---
# Create a payment dunning
Endpoint responsible for submitting a dunning request linked to an existing charge in Asaas.
This call starts the debt reporting flow based on a previously created charge. In addition to the charge data, the request also requires complementary customer information and, when applicable, supporting documents related to the debt.
### Important rule before integrating
To use this endpoint, the account must have permission to create dunning requests via API.
If this feature is not yet enabled, you must contact your Asaas account manager and request activation.
### Main request parameters
Some fields play a central role in submitting the dunning request:
`payment` - Unique identifier of the charge that will be linked to the dunning request.
`type` - Type of dunning request to be submitted. Currently, the available value is:
* `CREDIT_BUREAU`
`description` - Description of the product or service that originated the debt.
`customerName` - Name of the customer who will be reported.
`customerCpfCnpj` - Customer's CPF or CNPJ.
`customerPrimaryPhone` - Customer's primary phone number.
`customerSecondaryPhone` - Customer's secondary phone number.
`customerPostalCode` - Customer's ZIP code.
`customerAddress` - Customer's street address.
`customerAddressNumber` - Customer's address number.
`customerComplement` - Customer's address complement.
`customerProvince` - Customer's district or neighborhood.
`documents` - File containing the invoice and/or a notarized contract.
### Relation to the charge
A dunning request always starts from an existing charge.
Because of this, the integration must store the charge identifier correctly and make sure that the record sent in the `payment` field matches exactly the debt that will be reported.
### Supporting documentation
Depending on the analysis flow, the dunning request may require supporting documentation for the debt.
Submitting the correct documents is important to avoid rejection during review and the need for a new submission later.
# 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": "Payment Dunning"
}
],
"paths": {
"/v3/paymentDunnings": {
"post": {
"tags": [
"Payment Dunning"
],
"summary": "Create a payment dunning",
"description": "",
"operationId": "create-a-payment-dunning",
"parameters": [],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/PaymentDunningSaveRequestDTO"
}
}
}
},
"responses": {
"200": {
"description": "Ok",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaymentDunningShowResponseDTO"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponseDTO"
},
"example": {
"errors": [
{
"code": "error_code",
"description": "Error description"
}
]
}
}
}
},
"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
},
"PaymentDunningShowResponseDTO": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the payment dunning in Asaas",
"example": "ce35702d-0d9f-475a-ba46-e251ad265c91",
"deprecated": false
},
"dunningNumber": {
"type": "integer",
"description": "Payment dunning number",
"format": "int32",
"example": 15,
"deprecated": false
},
"status": {
"$ref": "#/components/schemas/PaymentDunningShowResponsePaymentDunningStatus"
},
"type": {
"$ref": "#/components/schemas/PaymentDunningShowResponsePaymentDunningType"
},
"requestDate": {
"type": "string",
"description": "Request date",
"format": "date",
"example": "2020-05-26",
"deprecated": false
},
"description": {
"type": "string",
"description": "Description of the payment dunning",
"example": "Duas mesas com 8 cadeiras solicitadas via encomenda no dia 01/05/2018",
"deprecated": false
},
"value": {
"type": "number",
"description": "Payment amount",
"example": 80,
"deprecated": false
},
"feeValue": {
"type": "number",
"description": "Cost and/or payment dunning fee",
"example": 8,
"deprecated": false
},
"netValue": {
"type": "number",
"description": "Net amount to be recovered",
"example": 72,
"deprecated": false
},
"receivedInCashFeeValue": {
"type": "number",
"description": "Cash receipt fee",
"example": 0,
"deprecated": true
},
"denialReason": {
"type": "string",
"description": "Reason for denial of payment dunning",
"deprecated": false,
"example": null
},
"cancellationFeeValue": {
"type": "number",
"description": "Fee charged in case of cancellation",
"example": 0,
"deprecated": true
},
"canBeCancelled": {
"type": "boolean",
"description": "Whether the payment dunning can be canceled",
"deprecated": false,
"default": true,
"example": null
},
"cannotBeCancelledReason": {
"type": "string",
"description": "Reason for not being able to request cancellation",
"deprecated": false,
"example": null
},
"isNecessaryResendDocumentation": {
"type": "boolean",
"description": "Determine whether documentation needs to be resubmitted",
"deprecated": false,
"example": null
},
"payment": {
"type": "string",
"description": "Unique identifier of the payment to be recovered in Asaas",
"example": "pay_080225913252",
"deprecated": false
}
}
},
"PaymentDunningShowResponsePaymentDunningStatus": {
"type": "string",
"description": "Payment dunning status",
"example": "PENDING",
"deprecated": false,
"enum": [
"PENDING",
"AWAITING_APPROVAL",
"AWAITING_CANCELLATION",
"PROCESSED",
"PAID",
"PARTIALLY_PAID",
"DENIED",
"CANCELLED"
]
},
"PaymentDunningShowResponsePaymentDunningType": {
"type": "string",
"description": "Type of payment dunning",
"example": "CREDIT_BUREAU",
"deprecated": false,
"enum": [
"CREDIT_BUREAU"
]
},
"PaymentDunningSaveRequestDTO": {
"required": [
"payment",
"type",
"customerName",
"customerCpfCnpj",
"customerPrimaryPhone",
"customerPostalCode",
"customerAddress",
"customerAddressNumber",
"customerProvince"
],
"type": "object",
"properties": {
"payment": {
"type": "string",
"description": "Unique identifier of the payment to be recovered in Asaas",
"nullable": false,
"example": "pay_080225913252",
"deprecated": false
},
"type": {
"$ref": "#/components/schemas/PaymentDunningSaveRequestPaymentDunningType"
},
"description": {
"type": "string",
"description": "Description of the product or service provided",
"example": "Duas mesas com 8 cadeiras solicitadas via encomenda no dia 01/05/2018",
"deprecated": false
},
"customerName": {
"type": "string",
"description": "Client name",
"nullable": false,
"example": "John Doe",
"deprecated": false
},
"customerCpfCnpj": {
"type": "string",
"description": "Customer CPF or CNPJ",
"nullable": false,
"example": "378.285.120-07",
"deprecated": false
},
"customerPrimaryPhone": {
"type": "string",
"description": "Customer main telephone number",
"nullable": false,
"example": "(11) 99999-9999",
"deprecated": false
},
"customerSecondaryPhone": {
"type": "string",
"description": "Secondary customer phone number",
"example": "(11) 99999-9999",
"deprecated": false
},
"customerPostalCode": {
"type": "string",
"description": "Customer address zip code",
"nullable": false,
"example": "99050-460",
"deprecated": false
},
"customerAddress": {
"type": "string",
"description": "Customer public address",
"nullable": false,
"example": "Rua Izaías Fontana",
"deprecated": false
},
"customerAddressNumber": {
"type": "string",
"description": "Customer address number",
"nullable": false,
"example": "123",
"deprecated": false
},
"customerComplement": {
"type": "string",
"description": "Customer address complement",
"example": "AP 101",
"deprecated": false
},
"customerProvince": {
"type": "string",
"description": "Customer neighborhood",
"nullable": false,
"example": "Petrópolis",
"deprecated": false
},
"documents": {
"type": "string",
"description": "Invoice and/or contract notarized",
"format": "binary",
"deprecated": false,
"example": null
}
}
},
"PaymentDunningSaveRequestPaymentDunningType": {
"type": "string",
"description": "Type of payment dunning",
"nullable": false,
"example": "CREDIT_BUREAU",
"deprecated": false,
"enum": [
"CREDIT_BUREAU"
]
}
},
"securitySchemes": {
"Authorization": {
"type": "apiKey",
"name": "access_token",
"in": "header"
}
}
},
"x-readme": {
"headers": [
{
"key": "User-Agent",
"value": "NomeDaSuaAplicacao/1.0.0"
}
]
}
}
```
# Sibling pages
* [List payment dunnings](https://docs.asaas.com/reference/list-payment-dunnings.md)
* [Simulate a payment dunning](https://docs.asaas.com/reference/simulate-a-payment-dunning.md)
* [Recover a single payment dunning](https://docs.asaas.com/reference/recover-a-single-payment-dunning.md)
* [Event history lists](https://docs.asaas.com/reference/event-history-lists.md)
* [List payments received](https://docs.asaas.com/reference/list-payments-received.md)
* [List payments available for payment dunning](https://docs.asaas.com/reference/list-payments-available-for-payment-dunning.md)
* [Resend documents](https://docs.asaas.com/reference/resend-documents.md)
* [Cancel payment dunning](https://docs.asaas.com/reference/cancel-payment-dunning.md)