Skip to main content

Payment facilitator (sub-aggregation)

tip

The sub-aggregation model requires an additional aggregation agreement with dpay.pl. Contact your account manager to enable aggregation for your payment service.

The payment facilitator model lets aggregators (platforms serving many merchants of their own) accept payments on behalf of their clients - sub-merchants - within a single dpay.pl payment service.

Payment processing is a regulated business: card schemes and payment institutions require every transaction to be attributed to a specific, previously registered sub-merchant. Therefore:

  • every sub-merchant must be registered before accepting its first payment,
  • sub-merchant data must be kept up to date whenever it changes (name, address, website, MCC).

Sub-merchant lifecycle​

A sub-merchant with transfer-type products (PBL, BLIK) is active immediately after successful registration. Card products (MC, V, AMEX, wallets) go through additional card onboarding - card payments become available once verification completes.

If downstream registration fails, the sub-merchant record is not persisted and the response carries the failure reason - fix the data and retry the call.

Managing sub-merchants​

All calls are signed with a SHA-256 checksum (checksum) and require a fresh timestamp (60 seconds max).

PUT/api/v1/aggregator/merchantsSub-merchant registration: fields, products, card onboarding and error codes.Full contract in the API Reference PATCH/api/v1/aggregator/merchantsUpdating sub-merchant data (by id or MID).Full contract in the API Reference POST/api/v1/aggregator/merchantsList of sub-merchants of the payment service.Full contract in the API Reference DELETE/api/v1/aggregator/merchantsDeleting a sub-merchant.Full contract in the API Reference

Required data​

FieldDescription
aggregator_midSub-merchant identifier assigned by the aggregator (MID) - the key for updates and transaction attribution
merchant_nameTrade name shown to the buyer
merchant_urlSub-merchant website URL
mccMerchant Category Code
tax_idSub-merchant tax id (e.g. NIP)
productsList of payment products (e.g. ["PBL", "BLIK"])
companyNameRegistered legal name of the sub-merchant company
addressRegistered address: street, postalCode, locality, country (ISO 3166-1)
Registered address

For transfer-type products the address.* fields are required - without them registration fails with a validation error (HTTP 422). The address must be the registered company address matching companyName and tax_id, not a mailing address.

Registration example​

PUT /api/v1/aggregator/merchants
{
  "service": "my-aggregator",
  "timestamp": "1753357200",
  "aggregator_mid": "MID-10045",
  "merchant_name": "superstore.com",
  "merchant_url": "https://www.superstore.com",
  "mcc": "5999",
  "tax_id": "1234567890",
  "products": ["PBL", "BLIK"],
  "companyName": "Superstore Ltd",
  "address": {
    "street": "1 Flower St",
    "postalCode": "00-000",
    "locality": "Flowerton",
    "country": "PL"
  },
  "checksum": "..."
}

Attributing transactions to sub-merchants​

When registering a transaction, the aggregator indicates the sub-merchant in the products array:

  • products[].id - the sub-merchant's aggregator_mid,
  • products[].description - the buyer's e-mail address,
  • the transaction email field set to void@dpay.pl (aggregation transaction marker).

Based on this, dpay.pl attributes the payment to the right sub-merchant and passes its details to settlement systems - the transaction description shown to the buyer includes the sub-merchant's name and domain.

info

A transaction for a sub-merchant that has not been registered beforehand may be rejected by settlement systems. Always register the sub-merchant before its first payment.

Updates and deletion​

  • Update (PATCH) - identify the record by id or aggregator_mid; changed data is propagated to the payment facilitator registration. Keeping sub-merchant data current is a scheme compliance obligation.
  • Deletion (DELETE) - removes the sub-merchant from dpay.pl; historical transactions keep their attribution.
Last updated on