Connect
dpay Connect is dpay's Payments-as-a-Service surface for partners and ISVs. With a single partner key (Authorization: Bearer dpk_...) you onboard your own merchants and, once a merchant delegates access, act on their behalf: read their account (transactions, settlements, balance), register payments, and request payouts.
Every call is scoped to your channel's merchants and gated by both your key's scopes (onboarding:read, onboarding:write, account:read, payments:write, payouts:write) and the merchant's delegation (granted when the merchant signs your channel agreement; payouts require a separate opt-in). All endpoints in this section are served from https://panel.dpay.pl.
Registering a payment on-behalf is not a separate endpoint - it is a mode of the classic Register Payment endpoint (send On-Behalf-Of: {ref} with your partner key). For the conceptual guides, onboarding flows, consent model, and webhook catalog, see the dpay Connect integration guide.
Create Merchant Onboarding Draft
Creates a draft merchant onboarding under your partner channel and returns the merchant `ref`, current `status`, and `channel`. The distribution channel is derived from the authenticated partner key (never trusted from the body); if your key owns more than one channel you must supply `channel`, and it must belong to you. Creation is **idempotent** on `partner_external_ref` (scoped per channel): repeating the call with the same reference returns the existing draft with `200` instead of creating a duplicate — a new draft returns `201`. The response never contains the hosted-flow URL; obtain it from `finalize` or `GET /onboarding/{ref}` in `next_action.url`. Requires scope `onboarding:write`.
List Onboardings
Cursor-paginated status feed of every onboarding draft under your partner channels, newest first. Returns `{ data, next_cursor }`; pass the returned `next_cursor` back as the `cursor` query param to fetch the next page (`next_cursor` is `null` on the last page). `per_page` defaults to `50` and is capped at `200`. Each row is the lightweight `{ id, ref, channel, status }` shape (no `next_action` or `invited`). Requires scope `onboarding:read`.
Get Onboarding Status
Returns the full status for one merchant onboarding, identified by the `ref` you chose at creation. Includes the base fields (`id`, `ref`, `channel`, `status`), the hosted hand-off (`next_action` — always an object; `next_action.url` may be `null`), and any third-party invitations (`invited`, PII-free). Lookup is scoped to your partner channels: an unknown `ref` returns `404`. Requires scope `onboarding:read`.
Finalize Onboarding
Validates data completeness and returns the hosted hand-off for one merchant onboarding. This is a **read-only** operation: it never advances the onboarding — personal acts (contact and identity verification, declarations such as PEP, agreement signing, verification transfer) are always completed by the merchant under `next_action.url`. It always responds `200`, even when data is incomplete; `missing[]` lists the outstanding data-segment codes (empty array when the data is complete). Takes no request body. Requires scope `onboarding:write`.
Set Company Data Segment
Sets the entity type and (for companies) the tax id and registration data on an onboarding draft. Send `has_nip: false` for a natural person (no other fields needed) or `has_nip: true` with the full company block. When a tax id is supplied, dpay enriches the draft from public registers; an entity struck off the register returns `422`. This segment does not move the merchant's position in the hosted flow. Requires scope `onboarding:write`.
Set Bank Account And Transactional Profile
Sets the settlement/payout bank account together with the AML transactional profile, shop industry and (for companies) the main business activity code. Requires the entity type to be set first via `PATCH /company` (otherwise `422`). All monetary fields are whole Polish zloty (PLN major units), never minor units. Requires scope `onboarding:write`.
Prefill Applicant Identity
Prefills the identity data of the main applicant (a natural person or a sole trader): national id number, identity document, residential address, place of birth and citizenships. It only stores data - the identity verification itself and the statutory declarations (PEP, acting on own behalf) are always completed by the merchant in the hosted flow. For a multi-person company the representative's identity is handled in the hosted flow and this segment returns `422`. Requires scope `onboarding:write`.
Set Company Representation Decision
Records whether the person creating the account is a representative of a multi-person company and derives the representation mode from the company's registered governing body. Applies to multi-person companies only (`422` for sole traders / natural persons). The response includes `representation_mode` (`solo`, `co_representative` or `proxy`) and `requires_invitation_or_poa`; non-`solo` modes require inviting the other person and/or uploading a power of attorney. Requires scope `onboarding:write`.
Upload Onboarding Document
Uploads a supporting document to the onboarding draft (e.g. power of attorney, identity document, or a regulated-activity document). Supply the file either as a multipart `file` part or as base64 (`content_base64` + `filename`). Provide either a free-form `document_type` + `subject`, or a `document_id` referencing a required regulated-activity document. Accepted formats: pdf, png, jpg, jpeg, tiff; maximum size 5120 KB (5 MB). The response includes the created `document_id`, which you can attach to a proxy-representative invitation. Requires scope `onboarding:write`.
Add Beneficial Owner
Adds a beneficial owner (manual entry) to a multi-person company: identity, address, indication basis, identity document, the PEP declaration and the source-of-wealth declaration (both declared by the submitter on the beneficial owner's behalf). Applies to multi-person companies only (`422` otherwise). The response includes a stable `beneficiary_uuid` used to remove the entry. Requires scope `onboarding:write`.
Remove Beneficial Owner
Removes a previously added beneficial owner entry by its `uuid`. Applies to multi-person companies only. Returns `404` when the uuid is not found on this onboarding. Requires scope `onboarding:write`.
Invite Representative Or Beneficial Owner
Invite a second person - a company **representative** or a **beneficial owner** - to complete the personal steps that cannot be done through the API. The person is identified only by `first_name`, `last_name`, `email` and `phone` (a 9-digit Polish mobile number, no country prefix); no account or login is created for them.
List Invitations
List every invitation on this onboarding (representatives and beneficial owners), ordered by `invitation_id` ascending. Read-only and free of the invited people's personal data; it keeps working even after the account has been activated.
Resend Invitation
Resend an existing invitation's e-mail and SMS - for example when the address had a typo or the SMS never arrived. Resending keeps the same invitation and refreshes its expiry.
Cancel Invitation
Cancel an invitation. Its hosted link stops working immediately (the invited person then sees a gone page when they open it). Use this when the details were wrong, for example a typo in the e-mail or phone number.
List Connected Merchants
Lists the merchants onboarded through your partner channel. Requires scope `account:read`.
Get Merchant Details And Balance
Returns a single merchant's details together with its available balance broken down per product. Requires scope `account:read` **and** an active merchant delegation covering that scope (granted when the merchant signs the agreement).
List Merchant Transactions
Lists a merchant's transactions, newest first. Requires scope `account:read` and an active merchant delegation covering that scope.
List Merchant Settlements
Lists a merchant's settlements (amounts paid out to the merchant's bank account and their state), newest first. Requires scope `account:read` and an active merchant delegation covering that scope.
Mint Account Frame URL
Mints a short-lived URL for the embeddable account frame, so the merchant can view their account (balance, transactions, payout opt-in) inside your product without logging in to dpay. Requires scope `account:read` and an active merchant delegation covering that scope.
Create Merchant Payout
Requests a payout of the merchant's **entire available balance** to the merchant's verified bank account on file. Requires scope `payouts:write` **and** the merchant's separate payout opt-in (confirmed by SMS in the account frame) - the read/payment delegation does not cover payouts.