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"
    }
  }
}

Security

There is no authentication method for the payout notification itself. If you require extra security, you can choose to whitelist dLocal's IPs in your system to only accept requests from us, or you can validate the notification by calling our Get payout endpoint with your regular authentication.