DTC PSD2 TPP OpenAPI Documentation

Version: 1.0 · Berlin Group NextGenPSD2 · 2026-05-15

This document describes the DTC Open API endpoints for DTC acting as a Third Party Provider (TPP) under the EU PSD2 directive. The surface implements two of the three TPP sub-roles defined by Berlin Group NextGenPSD2:

• AISP — Account Information Service Provider (read accounts, balances, transactions)
• PISP — Payment Initiation Service Provider (initiate SEPA / SCT Inst / TARGET2 / cross-border / periodic payments)

The shared Consent lifecycle endpoints and the unauthenticated SCA Callback endpoint are documented alongside.

1. Overview

1.1 PSD2 Roles & Glossary

1.2 End-to-end Flow

+-----+  HTTPS  +---------------+  HTTPS  +-----------+  PSD2  +-------+
| PSU | <-----> |  DTC Wallet   | <-----> |  DTC TPP  | <----> | ASPSP |
|     |         |  (Client App) |         |  (this)   |        | (Bank)|
+-----+         +---------------+         +-----------+        +-------+
  ^                                            |                  ^
  |             SCA redirect / poll            |                  |
  +--------------------------------------------+------------------+
      (PSU is redirected to the ASPSP for SCA, then back to DTC)

Every business call goes through DTC: the wallet client authenticates to DTC with OAuth 2.0 + HMAC-SHA512 signature; DTC translates that into a Berlin Group request to the ASPSP. The SCA itself is delegated to the ASPSP — the PSU never enters bank credentials in the DTC UI.

1.3 Security Standards

The PSD2 TPP Open API provides four layers of security:

• HTTPS: TLS 1.2+ — mandatory.
• IP Whitelist: optional, configured in the API Key Management page.
• OAuth 2.0: session management; an access_token in every business call.
• HMAC-SHA512 Signature: tamper protection on selected high-risk endpoints (e.g. PISP payment initiation).

2. Quick Start

2.1 Disclaimer

2.2 Before Integration

1. Request for account registration on the DTC Wallet platform.
2. Log in with the username and password issued by the DTC team and go to the API Key Management page.
3. Click + Create to open the dialog.
4. Enter the Name and IP Whitelist, then submit.
5. The API Key, API Secret, and Sign Key will be generated and shown one time only. Save them safely before closing the dialog.
6. Request the PSD2 auth modules to be granted on your client: PSD2_AIS, PSD2_PIS.

2.3 OAuth 2.0 Authentication

2.3.1 Usage

To use OAuth 2.0, first call Fetch Access Token. Then add the header Authorization: Bearer {access_token} to every PSD2 Open API request.

If the access token expires you can re-fetch it or use the Fetch Access Token by Refresh Token API. We recommend fetching a new access token before the previous one expires.

2.3.2 Fetch Access Token

curl -X "POST" "https://{host}/openapi/auth/oauth2/token" \
     -H 'Content-Type: multipart/form-data; charset=utf-8; boundary=__X_PAW_BOUNDARY__' \
     -F "client_id=xxx" \
     -F "client_secret=xxx" \
     -F "grant_type=client_credentials"

{
    "access_token":  "CkppLkyiqEUKITGdtCZRUZBl",
    "expires_in":    21600,
    "refresh_token": "CpCAhcCRtLU4kPjs54omWW3A",
    "rt_expires_in": 43200,
    "token_type":    "bearer"
}

2.3.3 Fetch Access Token by Refresh Token

curl -X "POST" "https://{host}/openapi/auth/oauth2/token" \
     -H 'Content-Type: multipart/form-data; charset=utf-8; boundary=__X_PAW_BOUNDARY__' \
     -F "refresh_token=CpCAhcCRtLU4kPjs54omWW3A" \
     -F "grant_type=refresh_token"

{
    "access_token":  "CE2ZgMjcgcfOvzY0jcS7csYe",
    "expires_in":    21600,
    "refresh_token": "CdugTgyDDa05uURhK6n6GYiW",
    "rt_expires_in": 43200,
    "token_type":    "bearer"
}

2.4 Request Signature

For high-risk PSD2 endpoints (notably POST /openapi/psd2/pisp/v1/payments/{paymentProduct}), an HMAC-SHA512 signature is mandatory in the request headers. You may also apply the same scheme to every PSD2 request — DTC will validate when present.

1. Components of the signature, in order:
   • HTTP Method — in uppercase (GET / POST / DELETE).
   • Timestamp — millisecond epoch in Singapore timezone. Requests are rejected if the timestamp drifts by more than 2 minutes.
   • URL — request URL without the scheme and host (e.g. /openapi/psd2/pisp/v1/payments/sepa-credit-transfers).
   • Querystring — in-URL parameters without the leading ?, unencoded; empty string when there are none.
   • Request Body — the exact raw body string, including invisible characters. Empty string for GET / DELETE without a body.
2. Concatenate them with no separator. Example strings to sign:

   GET1636360576641/openapi/psd2/aisp/v1/accounts/details
   POST1636360661729/openapi/psd2/pisp/v1/payments/sepa-credit-transfers{"query":{"endToEndId":"INV-001"}}

3. Hash the string with HMAC-SHA512 using your Sign Key, then Base64-encode.

   Sign Key   : aR2822Y6XbehWMclnB0Y2NJK
   String     : POST1636360661729/openapi/test{"a":"124"}
   Signature  : MxrYnCm9Q7JOAvOrISf8+T2kuTW1d/w0at8aaPaoiX08VWfun3XPokVlIx1TkHXdcitls09wzfUGtXQZq23xdg==

4. Append the four DTC custom headers to your request (see §2.5).

2.5 Common Headers

3. Common Conventions

3.1 Request / Response Envelope

All PSD2 business endpoints share the standard DTC Open API envelope.

{
    "query":  { ...endpoint-specific fields... },
    "page":   { "current": 1, "size": 50 }
}

{
    "header": {
        "success": true,
        "errCode": null,
        "errMsg":  null
    },
    "result": { ...endpoint-specific fields... }
}

3.2 PSD2 Error Codes

4. Consent Lifecycle Endpoints

Base path: /openapi/psd2/v1/consent · Required scope: PSD2_AIS

These endpoints manage the AIS consent lifecycle. A PIS consent is created implicitly when initiating a payment — there is no separate "create PIS consent" endpoint.

{
    "query": {
        "scope":              "AIS",
        "aspspId":            "SOMEBANK_DE",
        "psuId":              "psu-001@example.com",
        "ibans":              ["DE00000000000000000001"],
        "validUntilDays":     90,
        "recurringIndicator": true,
        "frequencyPerDay":    4,
        "tppRedirectUri":     "https://wallet.dtcpay.com/openapi/psd2/sca/callback"
    }
}

{
    "header": { "success": true },
    "result": {
        "consentId":          "CSNT_A1B2C3D4",
        "scope":              "AIS",
        "aspspId":            "SOMEBANK_DE",
        "consentStatus":      "RECEIVED",
        "scaApproach":        "REDIRECT",
        "scaRedirectUri":     "https://psd2.somebank.example.com/sca?consentId=CSNT_A1B2C3D4&state=...",
        "ibans":              ["DE00000000000000000001"],
        "validUntil":         "2026-08-13T10:32:11",
        "recurringIndicator": true,
        "frequencyPerDay":    4
    }
}

{
    "header": { "success": true },
    "result": {
        "consentId":          "CSNT_A1B2C3D4",
        "scope":              "AIS",
        "aspspId":            "SOMEBANK_DE",
        "consentStatus":      "VALID",
        "scaApproach":        "REDIRECT",
        "scaRedirectUri":     "https://psd2.somebank.example.com/sca?consentId=...",
        "ibans":              ["DE00000000000000000001"],
        "validUntil":         "2026-08-13T10:32:11",
        "recurringIndicator": true,
        "frequencyPerDay":    4
    }
}

{
    "header": { "success": true },
    "result": {
        "consentStatus": "VALID"
    }
}

Possible consentStatus values: RECEIVED, VALID, EXPIRED, REVOKED_BY_PSU, REJECTED, TERMINATED_BY_TPP.

{
    "header": { "success": true },
    "result": {
        "consentStatus": "REVOKED_BY_PSU"
    }
}

5. AISP Endpoints

Base path: /openapi/psd2/aisp/v1 · Required scope: PSD2_AIS

All AISP endpoints require a VALID AIS consent. Refer to §4 for how to obtain one.

{
    "query": {
        "consentId":   "CSNT_K8M3X9P2",
        "withBalance": false
    }
}

{
    "header": { "success": true },
    "result": {
        "accounts": [
            {
                "resourceId":      "ACC_001",
                "iban":            "DE00000000000000000001",
                "bic":             "SBNKDEFFXXX",
                "currency":        "EUR",
                "name":            "Sample User Main",
                "product":         "Current Account",
                "cashAccountType": "CACC",
                "status":          "enabled"
            },
            {
                "resourceId":      "ACC_002",
                "iban":            "DE00000000000000000002",
                "bic":             "SBNKDEFFXXX",
                "currency":        "EUR",
                "name":            "Sample User Savings",
                "product":         "Savings Account",
                "cashAccountType": "SVGS",
                "status":          "enabled"
            }
        ]
    }
}

{
    "query": {
        "consentId":   "CSNT_K8M3X9P2",
        "accountId":   "ACC_001",
        "withBalance": true
    }
}

{
    "header": { "success": true },
    "result": {
        "account": {
            "resourceId":      "ACC_001",
            "iban":            "DE00000000000000000001",
            "bic":             "SBNKDEFFXXX",
            "currency":        "EUR",
            "name":            "Sample User Main",
            "product":         "Current Account",
            "cashAccountType": "CACC",
            "status":          "enabled"
        },
        "balances": [
            { "balanceType": "closingBooked",    "amount": "1024.50", "currency": "EUR", "referenceDate": "2026-05-15", "lastChangeDateTime": "2026-05-15T10:32:11" },
            { "balanceType": "expected",         "amount": "1010.50", "currency": "EUR", "referenceDate": "2026-05-15", "lastChangeDateTime": "2026-05-15T10:32:11" },
            { "balanceType": "interimAvailable", "amount": "1024.50", "currency": "EUR", "referenceDate": "2026-05-15", "lastChangeDateTime": "2026-05-15T10:32:11" }
        ]
    }
}

{
    "query": {
        "consentId": "CSNT_K8M3X9P2",
        "accountId": "ACC_001"
    }
}

{
    "header": { "success": true },
    "result": {
        "accountId": "ACC_001",
        "balances": [
            { "balanceType": "closingBooked",    "amount": "1024.50", "currency": "EUR", "referenceDate": "2026-05-15", "lastChangeDateTime": "2026-05-15T10:32:11" },
            { "balanceType": "expected",         "amount": "1010.50", "currency": "EUR", "referenceDate": "2026-05-15", "lastChangeDateTime": "2026-05-15T10:32:11" },
            { "balanceType": "interimAvailable", "amount": "1024.50", "currency": "EUR", "referenceDate": "2026-05-15", "lastChangeDateTime": "2026-05-15T10:32:11" }
        ]
    }
}

{
    "query": {
        "consentId":     "CSNT_K8M3X9P2",
        "accountId":     "ACC_001",
        "bookingStatus": "BOOKED",
        "dateFrom":      "2026-04-01",
        "dateTo":        "2026-05-15",
        "pageIndex":     1,
        "pageSize":      50
    }
}

{
    "header": { "success": true },
    "result": {
        "accountId": "ACC_001",
        "booked": [
            {
                "transactionId":  "TXN_20260514_001",
                "endToEndId":     "INV-2026-04-321",
                "bookingStatus":  "BOOKED",
                "bookingDate":    "2026-05-14",
                "valueDate":      "2026-05-14",
                "amount":         "-150.00",
                "currency":       "EUR",
                "creditorIban":   "DE00000000000000000002",
                "creditorName":   "Sample Creditor Co",
                "remittanceInfo": "Invoice 2026-04-321"
            },
            {
                "transactionId":  "TXN_20260512_002",
                "endToEndId":     "SAL-2026-05",
                "bookingStatus":  "BOOKED",
                "bookingDate":    "2026-05-12",
                "valueDate":      "2026-05-12",
                "amount":         "3200.00",
                "currency":       "EUR",
                "debtorIban":     "DE00000000000000000003",
                "remittanceInfo": "Salary May 2026"
            }
        ],
        "pending":   [],
        "total":     2,
        "pageIndex": 1,
        "pageSize":  50
    }
}

curl -X GET "https://{host}/openapi/psd2/aisp/v1/accounts/ACC_001/transactions/TXN_20260514_001" \
     -H "Authorization: Bearer {access_token}" \
     -H "Consent-ID: CSNT_K8M3X9P2" \
     -H "D-REQUEST-ID: 9b7c4d2a-..."

{
    "header": { "success": true },
    "result": {
        "transactionId":  "TXN_20260514_001",
        "endToEndId":     "INV-2026-04-321",
        "bookingStatus":  "BOOKED",
        "bookingDate":    "2026-05-14",
        "valueDate":      "2026-05-14",
        "amount":         "-150.00",
        "currency":       "EUR",
        "creditorIban":   "DE00000000000000000002",
        "creditorName":   "Sample Creditor Co",
        "remittanceInfo": "Invoice 2026-04-321"
    }
}

6. PISP Endpoints

Base path: /openapi/psd2/pisp/v1 · Required scope: PSD2_PIS

6.1 Supported Payment Products

The {paymentProduct} URL path segment selects the payment scheme. Phase 0 supports:

{
    "query": {
        "referenceNo":     "INV-2026-04-321",
        "aspspId":         "SOMEBANK_DE",
        "psuId":           "psu-001@example.com",
        "debtorIban":      "DE00000000000000000001",
        "creditorIban":    "DE00000000000000000002",
        "creditorName":    "Sample Creditor Co",
        "currency":        "EUR",
        "amount":          "150.00",
        "remittanceInfo":  "Invoice 2026-04-321",
        "tppRedirectUri":  "https://wallet.dtcpay.com/openapi/psd2/sca/callback",
        "endToEndId":      "INV-2026-04-321"
    }
}

{
    "header": { "success": true },
    "result": {
        "paymentId":         "PAY_20260515_A1B2C3",
        "transactionStatus": "RCVD",
        "scaApproach":       "REDIRECT",
        "scaRedirectUri":    "https://psd2.somebank.example.com/sca?paymentId=PAY_20260515_A1B2C3&state=...",
        "psuMessage":        "Please complete authentication in your banking app."
    }
}

curl -X GET "https://{host}/openapi/psd2/pisp/v1/payments/sepa-credit-transfers/PAY_20260515_A1B2C3" \
     -H "Authorization: Bearer {access_token}" \
     -H "D-REQUEST-ID: 9b7c4d2a-..."

{
    "header": { "success": true },
    "result": {
        "paymentId":         "PAY_20260515_A1B2C3",
        "paymentProduct":    "sepa-credit-transfers",
        "transactionStatus": "ACTC",
        "debtorIban":        "DE00000000000000000001",
        "creditorIban":      "DE00000000000000000002",
        "creditorName":      "Sample Creditor Co",
        "creditorAgentBic":  null,
        "currency":          "EUR",
        "amount":            "150.00",
        "remittanceInfo":    "Invoice 2026-04-321",
        "endToEndId":        "INV-2026-04-321",
        "startDate":         null,
        "endDate":           null,
        "frequency":         null,
        "createdAt":         "2026-05-15T10:32:11"
    }
}

{
    "header": { "success": true },
    "result": {
        "paymentId":                "PAY_20260515_A1B2C3",
        "transactionStatus":        "ACSC",
        "rejectReasonCode":         null,
        "rejectReasonMessage":      null,
        "lastStatusChangeDateTime": "2026-05-15T10:34:22"
    }
}

{
    "header": { "success": true },
    "result": {
        "paymentId":                "PAY_20260515_A1B2C3",
        "transactionStatus":        "CANC",
        "rejectReasonCode":         null,
        "rejectReasonMessage":      null,
        "lastStatusChangeDateTime": "2026-05-15T10:36:00"
    }
}

{
    "header": {
        "success": false,
        "errCode": "PSD2_PAYMENT_NOT_CANCELLABLE",
        "errMsg":  "Payment is settled or being settled and cannot be cancelled"
    }
}

7. SCA Callback

Base path: /openapi/psd2/callback

GET /openapi/psd2/callback/sca?type=AIS&aspspId=SOMEBANK_DE&id=CSNT_A1B2C3D4&code=AUTH_CODE_xxx&state=2f4a8c9...

# Note: no Authorization header — public endpoint, ASPSP browser redirect.

{
    "success":       true,
    "consentId":     "CSNT_A1B2C3D4",
    "consentStatus": "VALID",
    "redirectTo":    "https://wallet.dtcpay.com/openapi/psd2/sca/callback"
}

{
    "success": false,
    "message": "consent not found or state mismatch",
    "id":      "CSNT_A1B2C3D4"
}