Skip to main content

Getting Started

🚀 Quick Start​

Getting Started with PSD2 Integration​

To begin using Paysera's Open Banking API:

  1. 📚 Read Documentation - Understand API structure and key concepts
  2. 📞 Contact Paysera - Register your certificates and get access
  3. ⚙️ Prepare Integration - Configure and test your system

Looking for Georgia Standard?

Integration Flows​

Payment Initiation Flow​

Use when no payer account information is available during initiation:

Requirements
  • Authentication: OAuth SCA flow
  • Certificate Role: PSP_PI (Payment Initiation)
  • Required in: eIDAS certificate qcStatement

Strong Customer Authentication​

The SCA approach is fixed​

Paysera supports exactly one SCA approach: redirect, carried out over OAuth 2.0. Decoupled and embedded approaches are not implemented, and the approach cannot be negotiated — every 201 response to a payment initiation or consent request carries the header ASPSP-SCA-Approach: REDIRECT. Preference headers defined by the standard, such as TPP-Redirect-Preferred, are not evaluated.

The authorisation resource is created for you​

Paysera creates the authorisation sub-resource implicitly, as part of creating the payment or consent. A TPP never creates one, so the standard's "start the authorisation process" endpoints are not needed and are not implemented. The same applies to the endpoints that update PSU data on an authorisation. Each of these paths is routed for GET only, so any other method returns:

RequestResponse
POST /v1/consents/{consentId}/authorisations405 SERVICE_INVALID
POST /v1/payments/{paymentProduct}/{paymentId}/authorisations405 SERVICE_INVALID
POST /v1/payments/{paymentProduct}/{paymentId}/cancellationAuthorisations405 SERVICE_INVALID
PUT /v1/consents/{consentId}/authorisations/{authorisationId}405 SERVICE_INVALID
PUT /v1/payments/{paymentProduct}/{paymentId}/authorisations/{authorisationId}405 SERVICE_INVALID

Only the single-payment form is routed. bulk-payments and periodic-payments are not payment services this API serves, so a request against one of those paths returns 404 SERVICE_INVALID rather than 405.

The cancellation authorisation resource is a different case. No route matches .../cancellationAuthorisations/{authorisationId} at all, so GET and PUT on it return 404 SERVICE_INVALID, not 405.

Payment cancellation itself is not supported either — DELETE on a payment returns 405 SERVICE_INVALID, and the cancellation authorisation list is always empty. These operations still have pages in the API reference because it is generated from the Berlin Group specification; the pages describe the standard, not what this API does.

The 201 response links straight to the resource that was created:

  • _links.scaOAuth — the OAuth 2.0 authorisation server metadata document. Start here: read it, then send the PSU through its authorization_endpoint. See Authentication for the full authorization-code-with-PKCE flow.
  • _links.scaStatus — the authorisation resource itself. Poll it to follow the SCA outcome.

SCA status values​

GET on the scaStatus link returns a single field:

{
  "scaStatus": "scaMethodSelected"
}
scaStatusScenario that produces itWhat the TPP should do
scaMethodSelectedThe authorisation resource has just been created, together with the payment or consent. Only one SCA method exists, so it is selected immediately.Send the PSU to the OAuth authorization_endpoint.
startedThe PSU has been redirected and is authenticating with Paysera.Keep polling.
finalisedThe PSU approved the operation and SCA completed. Final.Exchange the authorization code for a token, then read the payment or consent.
failedThe PSU rejected the operation, or the authorisation's validity period expired. Final.Stop polling. Create a new payment or consent to retry.
The list above is complete

The Berlin Group standard defines further values — received, psuIdentified, psuAuthenticated, unconfirmed and exempted. Paysera never returns them. Build your state machine against the four above; finalised and failed are terminal, so an authorisation never leaves either.

Authentication Setup​

🔑 QWAC Certificate Setup

Certificate Authentication Process​

  1. Obtain QWAC Certificate

    • Contact your National Competent Authority (NCA)
    • See NCA Register for your country

  2. Submit to Paysera

    • Send certificate to Paysera administrators
    • Include intended use case description

  3. Permission Setup

    • Paysera validates and approves certificate
    • Access granted based on certificate roles

Certificate Roles:

  • PSP_AI - Account Information access
  • PSP_PI - Payment Initiation
  • PSP_IC - Fund Confirmation (coming soon)
🔐 OAuth 2.0 Implementation

OAuth Configuration​

Discovery Endpoint:

One authorisation server serves both profiles, and it sits at the host root rather than under a versioned /xs2a/... path:

https://open-banking-api.paysera.com/.well-known/oauth-authorization-server

Implementation Steps​

Paysera registers your OAuth client from your QWAC: the client_id is the organisation identifier in the certificate, and there is no client secret. PKCE with S256 is required. The discovery document above lists the endpoint paths; they are relative to https://open-banking-api.paysera.com.

  1. Get Authorization Code

    GET https://open-banking-api.paysera.com/oauth/authorize?
      response_type=code&
      client_id={your-client-id}&
      redirect_uri={your-redirect}&
      scope=AIS:{consentId}&
      state={random-state}&
      code_challenge={pkce-challenge}&
      code_challenge_method=S256
    # scope=PIS:{paymentId} to authorise a payment

  2. Exchange for Access Token

    POST https://open-banking-api.paysera.com/oauth/token
    Content-Type: application/x-www-form-urlencoded

    grant_type=authorization_code&
    code={authorization-code}&
    client_id={your-client-id}&
    redirect_uri={your-redirect}&
    code_verifier={pkce-verifier}

  3. Use Access Token

    GET https://open-banking-api.paysera.com/xs2a/berlin/1.3/v1/accounts
    Authorization: Bearer {access-token}
    Consent-ID: {consentId}
    X-Request-ID: {uuid}

📖 Full details in Authentication Guide

NCA Registers​

🏛️ National Competent Authorities

European NCA Register​

Where to obtain PSD2 certificates:

CountryAuthorityRegister Link
🇩🇪 DEBaFinRegister
🇫🇷 FRACPRRegafi
🇮🇹 ITBanca d'ItaliaRegister
🇪🇸 ESBanco de EspañaRegister
🇳🇱 NLDNBRegister
🇧🇪 BENBBRegister
note

This list may be outdated. Verify with respective authorities for current information.

Next Steps​

📖 Documentation​

🔧 Implementation​

📚 Resources​

Support​

Need help with complex integrations?

Contact: tech_support@paysera.com