Cancelar Pagamento
Disponível apenas em Sandbox
Este endpoint está disponível somente no ambiente Sandbox. Não há suporte para Pix Agendado em produção no momento.
O Pix Agendado não está disponível para todas as contas e depende de habilitação prévia pela Marlim. Para verificar a elegibilidade da sua conta, entre em contato com o nosso time comercial.
Use esta rota para cancelar um pagamento agendado que ainda não foi liquidado. Os demais pagamentos do agendamento continuam valendo.
POSTv3/scheduled_pix/payments/:payment_id/cancel
Atenção
O cancelamento só é aceito até as 23:59 do dia anterior à data do pagamento. Para cancelar o agendamento inteiro, cancele cada pagamento ainda em scheduled.
Request Variable Path
| Atributo | Tipo | Descrição |
|---|---|---|
| payment_id | string | ID Marlim do pagamento. |
Request Body Params
| Atributo | Tipo | Descrição |
|---|---|---|
| canceled_by | string | CPF ou CNPJ de quem solicitou o cancelamento, somente números. Deve ser o mesmo documento do pagador. |
Response Object
Retorna o pagamento com os campos de um item de Listar Pagamentos, com current_status igual a canceled.
Error Object
| Atributo | Tipo | Descrição |
|---|---|---|
| api_reference | string | URL para a documentação. Retornado nos erros de parâmetro. |
| errors | array | Array com todos os erros encontrados ao processar a requisição. |
| errors[][type] | string | Tipo de erro ocorrido. |
| errors[][message] | string | Mensagem detalhada do erro ocorrido. |
Exemplos
- Pagamento cancelado
- Pagamento já liquidado
- Fora do prazo
- Documento diferente do pagador
- Pagamento não encontrado
curl -X POST "https://sandbox.api.marlim.co/v3/scheduled_pix/payments/pAy3Pl4OkI7uJy2HtG9r/cancel" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
"canceled_by": "00099988877"
}'
{
"payment_id": "pAy3Pl4OkI7uJy2HtG9r",
"link_id": "sKd4Wp7RtY2nQm9XbC3v",
"item_id": "CURSO_PILOTAGEM_00321",
"current_status": "canceled",
"date": "2027-02-10",
"amount": 25000,
"description": "Curso de Pilotagem 3x",
"customer": {
"name": "Luke Skywalker",
"document_number": "00099988877"
},
"participant": {
"participant_id": "c8f0bf49-4744-4933-8960-7add6e590841",
"name": "Banco da Aliança"
},
"end_to_end_id": null,
"error": null,
"metadata": {
"turma": "2027A"
},
"date_created": "2026-11-16T14:23:02.410Z",
"date_updated": "2027-01-20T10:15:00.000Z"
}
curl -X POST "https://sandbox.api.marlim.co/v3/scheduled_pix/payments/pAy1Mn6BvC3xZq8WeR4t/cancel" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
"canceled_by": "00099988877"
}'
{
"errors": [
{
"type": "status",
"message": "Only payments with scheduled status can be canceled."
}
]
}
curl -X POST "https://sandbox.api.marlim.co/v3/scheduled_pix/payments/pAy2Kj9HgF5dSa1QwE7u/cancel" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
"canceled_by": "00099988877"
}'
{
"errors": [
{
"type": "date",
"message": "Payments can only be canceled until 23:59 of the day before the payment date."
}
]
}
curl -X POST "https://sandbox.api.marlim.co/v3/scheduled_pix/payments/pAy3Pl4OkI7uJy2HtG9r/cancel" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
"canceled_by": "00011122233"
}'
{
"api_reference": "https://docs.api.marlim.co/scheduled-pix/payments/cancel",
"errors": [
{
"type": "canceled_by",
"message": "The parameter [ canceled_by ] must be the document number of the payment payer."
}
]
}
curl -X POST "https://sandbox.api.marlim.co/v3/scheduled_pix/payments/AABBCCDD/cancel" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
"canceled_by": "00099988877"
}'
{
"errors": [
{
"type": "not_found",
"message": "Payment with id [AABBCCDD] was not found"
}
]
}