Skip to main content

On-behalf payouts

You can request a payout of the merchant's balance to the merchant's bank account, for example through a "Withdraw funds" button in your product. This is the most sensitive on-behalf operation, so additional safeguards apply.

Key rule: you decide when, not how much​

When requesting a payout, you provide neither a bank account number nor an amount. dpay pays the merchant's entire available balance exclusively to the merchant's verified bank account on file. You only decide when the payout should be made.

This is intentional. It ensures that:

  • funds cannot be sent to someone else's account, even if your key is compromised,
  • you do not become an intermediary handling funds,
  • the merchant knows that their money can only be sent to them.

Requesting a payout​

The endpoint accepts no fields. Send an empty request, and dpay pays out the merchant's entire available balance.

POST/api/partner/v1/merchants/{ref}/payoutsRequest a payout of the entire available balance to the merchant's verified bank account.Full contract in the API Reference

When the request is accepted, the response has the queued status and reports the balance included in the payout, with amounts expressed in PLN. If a payout for this merchant is already being processed, dpay returns in_progress with status code 200. The payout identifier (payout_id) is not included in this response. It appears in payout.* webhooks when dpay processes the payout.

Errors​

CodeWhen
409The merchant has automatic payouts enabled. On-behalf payouts work only in manual mode; in automatic mode, dpay controls the schedule instead of you.
409A reverification hold restricts the merchant's account during a periodic AML review, so payouts are temporarily unavailable.
422There is no available balance to pay out.
403The payouts:write scope or the merchant's payout consent is missing.

Three permission gates​

A payout is accepted only when all conditions are met:

  1. The key has the payouts:write scope.
  2. The merchant has granted separate payout consent. This is an independent opt-in confirmed by SMS code in the account frame, separate from delegation for account access and payments.
  3. The merchant uses manual payouts, has no reverification hold, and has no payout already in progress.
Payouts always require separate consent

The merchant's consent for account access and payments does not include payouts. Payouts require a separate, explicit merchant opt-in confirmed by SMS code in the account frame. This protects against broad consent for "account management" unintentionally allowing funds to be moved.

Payout holds​

Payouts can be suspended independently of other operations, for example during periodic AML reverification. Payments continue to work in this state, but a payout request returns 409. Once the hold is removed, subsequent requests succeed again. dpay does not send a separate webhook when the hold is removed, so after a 409, retry later, for example after a reverification_submitted webhook or after some time.

Payout webhooks​

dpay confirms payout processing through webhooks:

EventMeaning
payout.paidFunds were sent to the merchant's bank account. The payload contains payout_id and the net amount.
payout.failedThe payout was rejected, for example because of a hold or inconsistency.

payout.* webhooks are sent when dpay processes a payout, including when a dpay employee manually approves or rejects it.

Partner sandbox​

If your partner account operates in sandbox mode, the payout request is simulated and no real bank transfer is made. The response then includes an additional "simulated": true field and otherwise has the same structure as a production payout.

Next steps​