Whenever a payout changes status, the Payouts API will send a notification to your notification URL using the POST protocol.
If you need to specify a port in the notification URL, it must be the standard HTTPS port 443, and the connection must use TLS 1.2.
Configuring your notification URL
To configure your URL, follow these steps:
- Go to the Merchant Dashboard
- Under the path Settings > Developers > Integration, you'll find an Endpoint section.
- There, you need to update the Payouts Notification URL, setting the webhook for your notifications.
Notification parameters
The parameters you receive in the notification are the same as those you receive in a Get payout request.
Body parameters
Here's an example of how you might receive a notification:
{
"id": "PO-4-39b09aad-7e25-4d56-92aa-cf30a19e5b99",
"external_id": "ex_id8910",
"status": "PENDING",
"status_code": "100",
"status_detail": "The payout is pending",
"created_date": "2023-11-16T00:00:07.00Z",
"last_updated": "2023-11-16T00:00:07.00Z",
"payment_method_id": "BANK_TRANSFER",
"flow_type": "P2P",
"country": "BR",
"currency": "BRL",
"currency_to_pay": "BRL",
"amount": 50000.19,
"purpose": "REMITTANCES",
"statement_descriptor": "ABC remittance provider",
"description": "ABC - Remittance - gift",
"on_hold": false,
"notification_url": "http://merchantsite.com/notification/",
"amount_details": {
"amount_to_pay": 50000.19,
"exchange": {
"source_amount": 50000.19,
"source_currency": "BRL",
"destination_amount": 9746.81,
"destination_currency": "USD",
"exchange_rate": 5.1299
},
"fees": {
"amount": 0.1,
"currency": "USD"
},
"taxes": {
"amount": 37.04,
"currency": "USD"
},
"debit": {
"amount": 9783.95,
"currency": "USD"
}
},
"beneficiary": {
"first_name": "John",
"last_name": "Doe",
"phone": "+5511971111111",
"email": "[email protected]",
"bank_account": {
"code": "341",
"branch": "0167",
"type": "SAVINGS",
"account": "12345-1"
},
"document": {
"type": "CPF",
"id": "12345677890"
},
"birth_info": {
"date": "1980-06-23",
"country": "BR",
"city": "Sao Paulo"
},
"address": {
"street": "Avenida Paulista",
"number": "123",
"city": "Sao Paulo",
"state": "Sao Paulo",
"country": "BR",
"postal_code": "05319-000"
}
},
"remitter": {
"first_name": "Ashley",
"last_name": "Peterson",
"nationality": "US",
"phone": "+12021111111",
"email": "[email protected]",
"funds_source": "SALARY",
"document": {
"type": "PASS",
"id": "1234567789",
"issue_date": "2020-01-01",
"expiration_date": "2030-01-01"
},
"birth_info": {
"date": "1981-06-23",
"country": "US",
"city": "Washington DC"
},
"address": {
"street": "4400 ABC Ave NW",
"number": "123",
"city": "Washington DC",
"state": "District of Columbia",
"country": "US",
"postal_code": "20036"
}
}
}Sample notification payload
Example of a notification payload:
{
"id": "PO-4-39b09aad-7e25-4d56-92aa-cf30a19e5b99",
"external_id": "ex_id8910",
"status_code": "100",
"status": "PENDING",
"status_detail": "The payout is pending",
"created_date": "2023-11-16T00:00:07.00Z",
"last_updated": "2023-11-16T00:00:07.00Z",
"payment_method_id": "BANK_TRANSFER",
"flow_type": "P2P",
"country": "BR",
"currency": "BRL",
"currency_to_pay": "BRL",
"amount": 50000.19,
"purpose": "REMITTANCES",
"statement_descriptor": "ABC remittance provider",
"description": "ABC - Remittance - gift",
"on_hold": false,
"notification_url": "https://merchantsite.com/notification",
"amount_details": {
"amount_to_pay": 50000.19,
"exchange": {
"source_amount": 50000.19,
"source_currency": "BRL",
"destination_amount": 9746.81,
"destination_currency": "USD",
"exchange_rate": 5.1299
},
"fees": {
"amount": 0.1,
"currency": "USD"
},
"taxes": {
"amount": 37.04,
"currency": "USD"
},
"debit": {
"amount": 9783.95,
"currency": "USD"
}
},
"beneficiary": {
"first_name": "John",
"last_name": "Doe",
"phone": "+5511971111111",
"email": "[email protected]",
"bank_account": {
"code": "341",
"branch": "0167",
"type": "S",
"account": "12345-1"
},
"document": {
"type": "CPF",
"id": "12345677890"
},
"birth_info": {
"date": "1980-06-23",
"country": "BR",
"city": "Sao Paulo"
},
"address": {
"street": "Avenida Paulista",
"number": "123",
"city": "Sao Paulo",
"state": "Sao Paulo",
"country": "BR",
"postal_code": "05319-000"
}
},
"remitter": {
"first_name": "Ashley",
"last_name": "Peterson",
"nationality": "US",
"phone": "+12021111111",
"email": "[email protected]",
"funds_source": "SALARY",
"document": {
"type": "PASS",
"id": "1234567789"
},
"birth_info": {
"date": "1981-06-23",
"country": "US",
"city": "Washington DC"
},
"address": {
"street": "4400 ABC Ave NW",
"number": "123 ",
"city": "Washington DC",
"state": "District of Columbia",
"country": "DC",
"postal_code": "20036"
}
}
}Retry Logic
When an IPN notification fails to be delivered successfully (due to non-2xx HTTP response or connection issues), our system does not perform immediate retries at the HTTP level. Instead, the failed notification is returned to the message queue and automatically reprocessed with progressive delays according to the queue's configured visibility timeout. This progressive retry mechanism gradually increases the time between retry attempts to avoid overwhelming your endpoint during temporary outages or high-load scenarios.
The notification delivery will be reattempted multiple times based on the queue's maximum receive count configuration. After all automatic retry attempts are exhausted, failed notifications are moved to a dead-letter queue for manual investigation and reprocessing by our technical account managers if needed.
Important: We strongly recommend implementing idempotent notification handling on your endpoint. Since our retry mechanism may deliver the same notification multiple times (due to network issues, timeouts, or processing failures), your system should be able to safely process duplicate notifications without unintended side effects. This ensures reliable communication and prevents inconsistencies during retry scenarios.