> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Reprocessar delivery
> Reenvia uma entrega já concluída e devolve o desfecho da nova tentativa.
`POST /webhooks/deliveries/:id/retry`
Faz parte do recurso [Webhooks](/pt-BR/webhooks) — o cadastro e o catálogo de eventos estão lá.
Reenvia uma entrega para a URL **atual** do webhook. O caso de uso é o de sempre: seu endpoint
esteve fora do ar, você corrigiu, e agora quer receber o que ficou para trás. Responde `200` com a
entrega relida depois do reenvio.
**Só entregas concluídas.** `failed` é o caso normal; `success` também é aceito, para quando você
processou mal e quer o evento de novo. As que ainda estão em curso (`pending`, `retrying`)
respondem `409 DELIVERY_ALREADY_RUNNING` — a Z2Pay já vai reenviá-las sozinha, sem você pedir.
**O reenvio é assíncrono: o `status` da resposta ainda pode ser `retrying`.** A entrega é
reenfileirada e relida logo em seguida, então o corpo mostra o estado imediato, não
necessariamente o desfecho. Para saber como terminou, consulte
[a entrega](/pt-BR/webhooks/deliveries-get) alguns instantes depois.
**O corpo reenviado é o original, sem alterações** — mesmo `id`, mesmo `occurredAt`. Se o recurso
mudou de estado desde então, o payload continua descrevendo o momento do evento, não o de agora.
Um receptor que trate o webhook como aviso e consulte a API pelo `id` não se incomoda com isso.
## Limites e recusas
Cada entrega tem **12 tentativas no total**: as 7 do ciclo automático mais 5 reprocessamentos
manuais. O reenvio recusa com código próprio, para você distinguir o que fazer:
| Código | HTTP | O que fazer |
| -------------------------- | ---- | ------------------------------------------------------------- |
| `DELIVERY_NOT_FOUND` | 404 | Conferir o id — ou a entrega é de outra conta |
| `DELIVERY_ALREADY_RUNNING` | 409 | Nada: ela já está sendo processada |
| `DELIVERY_IS_TEST` | 400 | Disparo de teste não se reprocessa; dispare outro pelo painel |
| `MAX_RETRIES_EXCEEDED` | 400 | Reconciliar pela API; esta entrega não sai mais |
| `WEBHOOK_NOT_FOUND` | 404 | O webhook foi removido; recriar e reconciliar pela API |
| `WEBHOOK_INACTIVE` | 400 | [Ativar o webhook](/pt-BR/webhooks/status) e tentar de novo |
## Exemplo
```bash theme={null}
curl -X POST https://api.sandbox.z2pay.com/v1/webhooks/deliveries/whd_t3ysa1qmxmusn47dhojdraxdi/retry \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX"
```
```json Resposta 200 theme={null}
{
"id": "whd_t3ysa1qmxmusn47dhojdraxdi",
"webhookId": "whk_k9clfafnldd96dbbxruh34233",
"eventType": "transaction.paid",
"url": "https://meusite.com/webhooks/z2pay",
"payload": {
"id": "whd_t3ysa1qmxmusn47dhojdraxdi",
"type": "transaction.paid",
"data": { "id": "txn_fcfcvfq9ryd6t3yczj6e87gyh" },
"occurredAt": "2026-06-24T13:46:00.000Z"
},
"status": "retrying",
"attemptCount": 7,
"returnStatus": 500,
"returnData": { "error": "internal server error" },
"errorMessage": "Request failed with status code 500",
"lastAttemptAt": "2026-06-25T20:16:00.000Z",
"createdAt": "2026-06-24T13:46:00.000Z",
"updatedAt": "2026-06-26T09:30:00.000Z"
}
```
Os campos de resultado ainda são os da tentativa anterior — eles só mudam quando a nova tentativa
termina.
## OpenAPI
````yaml openapi/psp.json POST /webhooks/deliveries/{id}/retry
openapi: 3.0.3
info:
title: Z2Pay PSP API
version: 1.0.0
description: API pública do PSP — autenticação via API Key (Credential)
servers:
- url: https://api.sandbox.z2pay.com/v1
description: Sandbox
- url: https://api.z2pay.com/v1
description: Produção
security: []
tags:
- name: Cards
description: Cartões salvos de um cliente
- name: Chargebacks
description: Gerenciamento de chargebacks
- name: Customers
description: Gerenciamento de clientes (compradores)
- name: Fees
description: Tabela de taxas da conta (pix, boleto, cartão, saque, refund, chargeback)
- name: Recipients
description: Gerenciamento de recebedores (sellers/merchants que recebem repasses)
- name: Refunds
description: Gerenciamento de reembolsos e estornos
- name: Splits
description: Regras de divisão do valor de uma venda entre recebedores
- name: Transactions
description: Gerenciamento de transações e payments
- name: Wallets
description: Saldo, extrato e resumo da carteira de um recebedor, agrupados por moeda
- name: Webhooks
description: Configuração, gerenciamento e histórico de entregas de webhooks
- name: Withdrawals
description: Solicitação e acompanhamento de saques (payouts) por recipient
paths:
/webhooks/deliveries/{id}/retry:
post:
tags:
- Webhooks
summary: Reprocessar delivery
description: Reenvia uma delivery que falhou anteriormente
operationId: DeliveryController_retry
parameters:
- name: id
in: path
required: true
description: ID da delivery
schema:
type: string
- name: Idempotency-Key
in: header
required: false
description: Chave única para garantir idempotência da requisição
schema:
type: string
responses:
'200':
description: Entrega reenviada, com o resultado da nova tentativa
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Identificador único do registro.
webhookId:
type: string
description: ID do webhook relacionado ao registro.
eventType:
type: string
description: 'Tipo do evento entregue (ex.: transaction.paid).'
url:
type: string
description: URL de destino do webhook ou link de download do arquivo.
payload:
type: object
description: Conteúdo (payload) enviado na entrega do webhook.
status:
type: string
description: >-
Situação da entrega. Valores: `pending`, `success`,
`failed`, `retrying`.
attemptCount:
type: integer
description: Número de tentativas de entrega já realizadas.
returnStatus:
type: integer
nullable: true
description: Código de status HTTP retornado pelo endpoint na entrega.
returnData:
type: object
nullable: true
description: Corpo da resposta retornada pelo endpoint na entrega.
errorMessage:
type: string
nullable: true
description: Mensagem de erro quando o processamento falha.
lastAttemptAt:
type: string
format: date-time
nullable: true
description: Data e hora da última tentativa de entrega (ISO 8601).
createdAt:
type: string
format: date-time
description: Data e hora de criação do registro (ISO 8601).
updatedAt:
type: string
format: date-time
description: Data e hora da última atualização do registro (ISO 8601).
example:
id: whd_w2wwfrrrvwx9axbb1wj1bgg75
webhookId: whk_tnuvglgyl74mm7k3cx18mmd6h
eventType: transaction.refused
url: https://api.minhaloja.com.br/webhooks/z2pay
payload:
id: whd_w2wwfrrrvwx9axbb1wj1bgg75
type: transaction.refused
data:
id: txn_wb8adjjeajavewrebxzvv1wna
amount: 9990
status: refused
occurredAt: '2025-06-29T13:50:00.000Z'
status: failed
attemptCount: 3
returnStatus: 500
returnData:
error: Internal Server Error
errorMessage: Request failed with status code 500
lastAttemptAt: '2025-06-29T14:02:30.000Z'
createdAt: '2025-06-29T13:50:00.000Z'
updatedAt: '2025-06-29T14:02:30.000Z'
'401':
description: Chave de API ausente, malformada ou inválida
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: UNAUTHORIZED
message: Invalid API key
'404':
description: Delivery não encontrada
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: NOT_FOUND
message: Delivery not found
'409':
description: >-
Já existe uma requisição em andamento com esta Idempotency-Key. A
API aguarda a primeira concluir por até 5 segundos antes de
responder assim
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: A request with this idempotency key is already being processed
'422':
description: >-
Idempotency-Key já usada com um corpo diferente. Use uma chave nova
para uma operação diferente
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: Idempotency key already used with a different request body
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````