🏦 PrivatBank Autoclient at a customer
Updated
How to connect PrivatBank statements on a project. Where to click — Import a bank statement. Why GET and a register, not a payment document — for the developer.
What's not there yet#
There is no Autoclient sandbox. The official HOST is one:
https://acp.privatbank.ua. The v3.0.0 API description has no second URL.
"МСБ-ТЕСТ ТОВ" in the sample JSON is data from the bank's documentation, not a cabinet you can log into.
PrivatBank does have a sandbox, but it is a different product: Open
Banking (XS2A) for payment-service providers with a QWAC certificate. It does
not belong on channel pb-statements. Do not put
dz-privatbank-xs2a…/SandboxAPI in UaBankConnection.
There is no outgoing payment (POST /api/proxy/payment/create + КЕП) in the
package. Diia is why it is separate. M.E.Doc is a
separate customer-side setup, a different dictionary.
The Environment field on the card (test / prod) is a label for humans.
It does not change the bank URL: both "test" and "prod" dial
acp.privatbank.ua.
What the customer must have#
- Privat24 for business on this legal entity.
- An API application: Privat24 → Accounting and reports → Integration
(Autoclient) → API, or Settings → API (sometimes labelled "ID i Token").
Copy the token. A separate
idheader is not required in official v3. Autoclient v3 sends thetokenheader, not an id+Token pair. - In the application's service limits: only "balances and transactions on accounts". Do not open payment create on this token.
- On the ZuloOne server:
Integration__Credentials__privatbank-merchant= that token. The value goes neither into git nor onto the card. - In outbound Allowed hosts —
acp.privatbank.ua. - A Core build with
OutboundHttpRequest(GET with no body). An old host attachesContent-Lengthon GET, the bank answers 400.
An agent on a PC is not needed: Autoclient is on the public internet, the ZuloOne server dials. Fill the agent tag only if the bank is reachable from LAN only.
The card in ZuloOne#
Ukraine → Settings → Bank connections (UaBankConnection).
| Field | What to put | Empty |
|---|---|---|
| Code | pb-romashka — the channel uses it as connectionRef |
will not save |
| Legal entity | the account's owner | nowhere to write statement rows |
| Base URL | https://acp.privatbank.ua/api |
will not save. Without trailing /api the path will not compose |
| Credential reference | privatbank-merchant |
GET goes out with no token → 401 |
| Account / IBAN | the IBAN from Privat24 | the bank returns all active accounts for this token |
| Disabled | no | a record with the box unticked works |
| Agent tag | empty | the server dials itself |
The PullUaBankStatements job is active, cron 20 6 * * * (06:20 UTC). It
pulls yesterday's operating day. Today's interim is not pulled in this
slice.
How to prove the statement arrived#
Do not invent JSON: a live answer is a transactions array with REF,
REFN, TRANTYPE, SUM, OSND from the Autoclient description.
Example. Yesterday account UA1234…567 had an incoming 0.01 ₴ (TRANTYPE=C,
REF=DNCHK0108B1WKX, REFN=1) and a reversal of 10 ₴ (PR_PR=t). After the
morning job the register Ukraine → Registers → PrivatBank statement lines
holds one row: key DNCHK0108B1WKX1, amount 0.01, type C. The reversal is not
written.
You can trigger the same job by hand before morning. CustomerPayment /
VendorPayment will not appear from that row — there is no EDRPOU match,
that would be somebody else's money on somebody else's contract.
If the register is empty — the table of reasons:
not WRK, work_balance=Y, 401, host not allowed, Core without GET-with-no-body.
What breaks if you wait for a sandbox#
Until there is a token from a real (or training) business cabinet, the channel
has nowhere to go. Pasting the Open Banking sandbox is a different contract,
different headers, a different error — not "almost Autoclient". The package
tests (UkraineBankStatementTest) parse a sample JSON and do not dial ACP.
Same topic for other readers: User · Developer