Direct Settlement (Payout)
POST/api/v1/user-api/directSettlement/:key/:checksum/:timestamp
Send money directly to a partner. Requires special dpay staff verification. Each payout costs 0.20 PLN (bank commission, no dpay commission). The fee is waived when the DigitalPayments-PSP-Offer: DIRECT_NO_FEE header is sent (subject to your agreement with dpay).
The fee is added on top of amount: the balance check requires amount + fee, and the settlement is booked as gross amount + fee.
Checksum
sha256({crc32(client_id)}{api_key}DirectSettlement{timestamp})
Values are concatenated directly without any separator. crc32(client_id) is the CRC32 hash of your client ID. Note the PascalCase DirectSettlement.
The timestamp is accepted when it is at most 6000 seconds (100 minutes) old. Timestamps in the future are not rejected.
Error handling
Every error is returned with HTTP 200. Do not branch on the status code - always read the status field, which is false on failure.
Authentication errors, identical to getBalance except for the permission checked:
code | message | Cause |
|---|---|---|
| (none) | Invalid key | key is not a 32-character hexadecimal string |
| (none) | Api key does not exist! | No API key matches key |
BAD_CHECKSUM | Invalid key! | checksum is not a 64-character hexadecimal string. Despite the wording, this is a checksum problem. |
BAD_TIMESTAMP | Bad timestamp! | timestamp is more than 6000 seconds in the past |
BAD_CHECKSUM | Bad checksum! | The computed checksum does not match the one supplied |
USAGE_NOT_AUTHORIZED | Function is not allowed! | The direct_settlement permission is not enabled for this API key |
Payout-specific errors:
code | message | Cause |
|---|---|---|
INCORRECT_CURRENCY | Currency not in service. (INCORRECT_CURRENCY) | currencyCode is outside PLN, EUR, CZK, USD |
LOW_BALANCE | Not enough funds. (LOW_BALANCE) | Available balance is lower than amount plus the 0.20 PLN fee |
SERVICE_NOT_FOUND | No active payment service found. (SERVICE_NOT_FOUND) | service names a Payment Point that is not active or does not belong to your client - or your client has no active Payment Point at all |
CURRENCY_NOT_ENABLED | This currency is not enabled in the payment shop. (CURRENCY_NOT_ENABLED) | The currency is valid but not enabled on the selected Payment Point |
NEGATIVE_AMOUNT | Amount cannot be negative. (NEGATIVE_AMOUNT) | amount is below zero |
Validation errors on the request body (missing nrb, title, receiverName, receiverAddress or amount, or a non-numeric nrb) are returned as a standard HTTP 422 with Laravel's { message, errors } envelope - these are the only errors on this endpoint that do not use HTTP 200.
Request
Responses
- 200
- 422
Payout result or an error - both share HTTP 200. Check the status field to tell them apart.
Request body validation failed (missing or malformed nrb, title, receiverName, receiverAddress or amount).