PeoPay API integration services (Bank Pekao / PolishAPI)

Deliverables checklist

• OpenAPI 3.1 specification for every exposed endpoint
• Protocol & auth flow report (OAuth2, SCA decoupled flow, eIDAS certificate handling)
• Runnable Python (FastAPI) and Node.js (Fastify) reference clients
• Postman collection plus pytest / vitest contract tests
• Sample MT940 / CAMT.053 / CSV exporters
• Compliance memo aligned with PSD2 RTS, PolishAPI 3.x and GDPR
• Deployment guide for Docker and AWS Fargate

Technical implementation — sample snippets

Below are three representative payloads exercised against our gateway. Field names mirror the PolishAPI 3.0 specification.

// 1) Initiate AIS consent (PolishAPI v3 style)
POST /v3_0/auth/authorize
Content-Type: application/json
X-Request-ID: 4c6f3a87-b1f2-4c3e-90e2-9b0d1e7c4a01

{
  "scope": "ais",
  "scopeDetails": {
    "consentId": "CNS-20260509-PEO-7741",
    "scopeUsageLimit": "multiple",
    "privilegeList": [
      {"accountList": [{"transactionHistory": true, "scaRequired": true}]}
    ]
  },
  "redirectUri": "https://client.example.com/cb"
}

// 200 OK
{
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "accessToken": "eyJhbGciOi..."
}

// 2) Statement query — PeoPay PLN account, last 30 days
POST /api/v1/peopay/statement
Authorization: Bearer <ACCESS_TOKEN>
X-Request-ID: 21a09b14-aa4c-4f5e-bb98-4dd4e8a2f9aa
Content-Type: application/json

{
  "accountIban": "PL61124000000000000000000000",
  "fromDate": "2026-04-09",
  "toDate":   "2026-05-09",
  "currency": "PLN",
  "channels": ["BLIK", "EXPRESS_ELIXIR", "CARD", "ATM"]
}

// 200 OK (truncated)
{
  "transactions": [
    {
      "transactionId": "TX-2026050912331",
      "bookingDate": "2026-05-08",
      "amount": {"value": -42.50, "currency": "PLN"},
      "channel": "BLIK",
      "counterparty": {"name": "BIEDRONKA 0421", "mcc": "5411"}
    }
  ],
  "pagination": {"nextCursor": "eyJ0Ij..."}
}

// 3) Webhook — BLIK request-for-transfer event
POST https://client.example.com/hooks/blik
X-Signature: sha256=2c4b...
Content-Type: application/json

{
  "event": "blik.request.completed",
  "occurredAt": "2026-05-09T11:42:18Z",
  "request": {
    "id": "REQ-9912",
    "amount": {"value": 120.00, "currency": "PLN"},
    "from": "+48555111222",
    "to": "+48555333444",
    "status": "ACCEPTED"
  }
}

// On signature failure return 401, on duplicate eventId return 200.

1. Accounting & ERP reconciliation

A Polish SME running on Comarch Optima or SAP Business One pulls its PeoPay business-account transactions every 30 minutes. We map each booking into a journal entry, normalise FX legs against NBP fixings, and push CAMT.053 files into the ERP. Endpoints involved: AIS account list, AIS transactions, plus a daily MT940 export.

2. Marketplace BLIK collection

A merchant marketplace generates a BLIK request-for-transfer per order. The buyer accepts in PeoPay, the funds settle in seconds, and our webhook informs the marketplace ledger. The OpenFinance pattern is PIS for outgoing refunds plus an event stream for incoming credits.

3. Multi-currency e-commerce payouts

Cross-border sellers using PeoPay's FX wallets settle in EUR, USD or GBP without round-tripping through PLN. The integration reads balance per currency, executes Express Elixir or SEPA payouts, and reconciles against the marketplace order book — fully covered by PSD2 PIS scopes.

4. Personal finance management (PFM)

A consumer-facing PFM aggregates PeoPay alongside other Polish banks. The AIS consent yields a 90-day transaction history that feeds the PFM's categorisation model; OpenData enrichment (MCC tables, NIP lookups) is layered on top to produce spending insights.

5. Investment dashboards (PekaoTFI)

Wealth-tech apps surface a unified portfolio view by combining PeoPay PekaoTFI fund holdings with brokerage positions held elsewhere. Daily NAV pulls plus event hooks on subscriptions and redemptions deliver intraday-fresh dashboards for retail investors.

Regulatory baseline

Poland implements PSD2 through the Act on Payment Services and the domestic PolishAPI standard alongside Berlin Group NextGenPSD2. Bank Pekao is supervised by the Polish Financial Supervision Authority (KNF). Our integrations register the client as a third-party provider (AISP / PISP / CBPII), use eIDAS QWAC and QSeal certificates, and apply Strong Customer Authentication via the decoupled or redirect flow as published on developer.pekao.com.pl. Since 17 January 2025 incident reporting falls under DORA — our compliance memo reflects this transition.

GDPR & data minimisation

Consent is captured per-scope with a unique consentId, stored encrypted at rest, and revocable at any time. We strip PAN data to last-four digits unless your legal basis demands otherwise, and we keep raw responses only for the audit window agreed in the SOW. By design, no personal data leaves the EEA without an Article 46 transfer mechanism in place.

• Consent records and audit logs ready for KNF inspection
• Data minimisation defaults: only fields requested are persisted
• Retention policies aligned with Polish AML statute (typically 5 years)
• Pen-test report available on request before go-live

Who we are

We are an independent technical studio focused on App interface integration, OpenData, OpenFinance and OpenBanking work. Our engineers come from commercial banks, payment gateways and protocol-analysis backgrounds, with hands-on experience of PolishAPI, Berlin Group NextGenPSD2, UK OBIE and the Brazilian Open Finance stack.

• Banking, payments, wealth-tech and cross-border clearing projects
• Protocol analysis, eIDAS certificate management and sandbox onboarding
• Custom Python / Node.js / Go SDKs, CI test harnesses, OpenAPI specs
• End-to-end pipeline: scoping → analysis → build → validation → compliance memo
• Source-code delivery from $300 — pay only on acceptance
• Pay-per-call API billing — usage-based, no upfront commitment

Contact

For quotes, sandbox-access questions or to submit a PeoPay-specific scope, open the contact page below. Provide the target app name, the data scopes you need (AIS, PIS, CBPII), the expected call volume and any existing TPP credentials. We respond within one business day.

Contact page

Engagement workflow

1. Scope confirmation: data scopes (AIS / PIS / CBPII), target accounts, expected call volume.
2. Protocol & sandbox analysis at developer.pekao.com.pl (2–5 business days).
3. Build phase: gateway, certificate handling, contract tests (3–8 business days).
4. Documentation, sample clients, compliance memo (1–2 business days).
5. Production cut-over with KNF-aligned audit logging; typical first delivery 5–15 business days.

FAQ

What data can be extracted from PeoPay through OpenBanking integration?

Do you use the official Bank Pekao developer portal?

How long does a typical PeoPay integration take?

Is the integration compliant with PSD2 and GDPR?