# Quick Start Guide
source: https://developer.mastercard.com/open-finance-data/documentation/quick-start-guide/index.md
Note: Onboarding for Open Finance Data is currently a manual process. [Contact us](https://www.mastercard.com/europe/en/business/open-finance/demo-request.html) to talk to our sales team who can walk you through the process of getting onboarded.
###### Time to Complete: **20 minutes** {#time-to-complete-20-minutes}
This guide walks you through accessing a customer's financial data in the
Sandbox environment, using a test bank. It uses FAPI 2.0 with DPoP
(Demonstration of Proof-of-Possession). By the end you will have:
* Exchanged a signed JSON Web Token (JWT) for a DPoP-bound access token
* Created a consent for a customer
* Triggered a managed flow for the customer to connect their bank
* Exchanged the returned authorization code for a consent-scoped token
* Retrieved the customer's accounts, balances, and account holder details
### Prerequisites {#prerequisites}
You need to be onboarded to the Sandbox environment by Mastercard staff before you start.
Refer to [Onboarding](https://developer.mastercard.com/open-finance-data/documentation/api-basics/index.md#onboarding) for
details.
You need:
* Your **Client ID**
* Your **Application ID**
* A **use case configuration ID**, for example for Account Opening
* An allowlisted **redirect URL** and **callback URL**
This guide uses FAPI 2.0 with DPoP. It assumes you can create a signed client
assertion (`private_key_jwt`) and the DPoP proofs that each request requires. To
learn how to generate and sign them, refer to
[Authentication](https://developer.mastercard.com/open-finance-data/documentation/api-basics/index.md#authentication).
Note: Every request in this guide needs its own DPoP proof. Each proof is a short-lived JWT signed with your DPoP key, with the `htm` and `htu` claims set to the method and URL of that request. For calls to the API, you also include an `ath` claim (the hash of your access token) and the `nonce` from the most recent `DPoP-Nonce` response header. Refer to [Authentication](https://developer.mastercard.com/open-finance-data/documentation/api-basics/index.md#authentication) for how to build each proof.
### Step 1 - Get an Access Token {#step-1---get-an-access-token}
Exchange your signed client assertion for a DPoP-bound access token. Send a DPoP
proof in the `DPoP` header and your `private_key_jwt` as the `client_assertion`.
Note: The base Sandbox URL for authentication is `https://mtf.auth.openfinance.mastercard.eu/`
* Sh
```sh
curl --location --request POST 'https://mtf.auth.openfinance.mastercard.eu/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'DPoP: ' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=' \
--data-urlencode 'scope=consent_create consent.flows_create' \
--data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
--data-urlencode 'client_assertion='
```
Set `scope` to the scopes assigned during your onboarding. This guide uses
`consent_create` to create the consent and `consent.flows_create` to create the
managed flow. You read account data later with a consent-scoped token, not this
partner token.
The response contains a DPoP-bound access token:
* JSON
```JSON
{
"access_token": "",
"token_type": "DPoP",
"expires_in": 899,
"scope": "consent_create consent.flows_create"
}
```
The `token_type` is `DPoP`, not `Bearer`. For every API request that follows,
send the access token in the `Authorization` header with the `DPoP` scheme, and
send a fresh DPoP proof in the `DPoP` header. The token is valid for the number
of seconds in `expires_in`.
Note: The first time you request a token, you do not have a nonce yet. The server responds with a `use_dpop_nonce` error and a `DPoP-Nonce` header. Take the nonce from that header, add it to a new DPoP proof, and send the request again. Refer to [Authentication](https://developer.mastercard.com/open-finance-data/documentation/api-basics/index.md#authentication) for details.
### Step 2 - Create a Consent {#step-2---create-a-consent}
A consent defines the scope and purpose for accessing a customer's financial
data. Call the Create consent endpoint with your access token, a DPoP proof, and
your `X-Application-Id` header.
Note: The base Sandbox URL for API calls is `https://mtf.api.openfinance.mastercard.eu/`
API Reference: `POST /consents`
Provide the `useCaseConfigurationId` from your onboarding data and an
`identifier` for the customer. The identifier is a reference you assign to the
customer, for example a UUID from your own system.
* Sh
```sh
curl --location --request POST 'https://mtf.api.openfinance.mastercard.eu/consents' \
--header 'Content-Type: application/json' \
--header 'Authorization: DPoP ' \
--header 'DPoP: ' \
--header 'X-Application-Id: ' \
--data-raw '{
"useCaseConfigurationId": "",
"endUsers": [
{
"identifier": "a1b2c3d4-0001-4abc-8def-1234567890ab"
}
]
}'
```
The response returns a `consentId` with a status of `PENDING`:
* JSON
```JSON
{
"consentId": "d4ed1ee2-bf8e-4611-8507-55f4c410ce25",
"endUsers": [
{
"identifier": "a1b2c3d4-0001-4abc-8def-1234567890ab"
}
],
"createdAt": "2026-06-26T00:00:00.0000000+00:00",
"status": {
"code": "PENDING",
"lastUpdatedAt": "2026-06-26T00:00:00.0000000+00:00"
}
}
```
Take a note of the `consentId` and the customer `identifier`. You use both in
the next step.
### Step 3 - Create a Managed Flow {#step-3---create-a-managed-flow}
A managed flow guides the customer through selecting their bank, authenticating,
and connecting their accounts to the consent. Mastercard hosts the screens.
Call the Create managed flow endpoint with the `consentId` from Step 2.
API Reference: `POST /consents/{consent_id}/managed-flows`
Set the `type` to `CONNECT_ACCOUNTS` and provide the same customer `identifier`
you used in Step 2. Provide two URLs, both allowlisted during onboarding:
* `redirectUrl` - where the customer's browser lands at the end of the flow. The platform appends `consent_id`, `flow_id`, and `success`.
* `callbackUrl` - where the platform delivers the OAuth 2.0 authorization `code`. FAPI 2.0 flows require this, and it must exactly match an allowlisted callback URL.
* Sh
```sh
curl --location --request POST 'https://mtf.api.openfinance.mastercard.eu/consents/d4ed1ee2-bf8e-4611-8507-55f4c410ce25/managed-flows' \
--header 'Content-Type: application/json' \
--header 'Authorization: DPoP ' \
--header 'DPoP: ' \
--data-raw '{
"type": "CONNECT_ACCOUNTS",
"endUser": {
"identifier": "a1b2c3d4-0001-4abc-8def-1234567890ab"
},
"redirectUrl": "https://your-site.example.com/return",
"callbackUrl": "https://your-site.example.com/callback",
"language": "en"
}'
```
The response returns a `flowId` and a `flowUrl`:
* JSON
```JSON
{
"flowId": "f1b182c4-a5d6-4830-920a-007652ccc56f",
"flowUrl": "https://app.openfinance.mastercard.eu/connect/flow/472e651e-5a1e-424d-8098-23858bf03ad7",
"flowUrlExpiresAt": "2026-06-28T20:37:19.8760968Z",
"language": "en",
"status": {
"code": "ACTIVE",
"lastUpdatedAt": "2026-06-26T20:37:19.963Z"
}
}
```
### Step 4 - Connect a Bank in the Test Bank {#step-4---connect-a-bank-in-the-test-bank}
In a live integration, you redirect the customer to the `flowUrl` to connect
their bank. In the Sandbox environment, you complete this step manually to
simulate the customer's authentication with a test bank.
1. Open the `flowUrl` from Step 3 in a browser.
2. When prompted to choose a bank, select the **Redirect Test Bank**.
3. Identify as the test user **john.smith**, whose accounts include balance and account holder information.
4. Complete the simulated authentication and confirm to share the data.
After the customer authenticates, the platform delivers an OAuth 2.0
authorization `code` to your `callbackUrl` and returns the customer's browser to
your `redirectUrl`. You need this `code` for the next step.
Note: The exact screens depend on the test provider and test user you select. For the available test banks, test users, and credentials, refer to [Testing](https://developer.mastercard.com/open-finance-data/documentation/testing-and-integration/testing/index.md).
### Step 5 - Exchange the Authorization Code {#step-5---exchange-the-authorization-code}
FAPI 2.0 does not use the consent ID to authorize data calls. Instead, you
exchange the `code` from Step 4 for a consent-scoped access token. Call the token
endpoint again with the `authorization_code` grant and a DPoP proof.
* Sh
```sh
curl --location --request POST 'https://mtf.auth.openfinance.mastercard.eu/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'DPoP: ' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_id=' \
--data-urlencode 'code=' \
--data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
--data-urlencode 'client_assertion='
```
The response contains a consent-scoped access token:
* JSON
```JSON
{
"access_token": "",
"token_type": "DPoP",
"expires_in": 899,
"scope": "ob_data"
}
```
Use this consent-scoped token, not the partner token from Step 1, for the data
call in the next step. To keep access after it expires, refresh it. Refer to
[Authentication](https://developer.mastercard.com/open-finance-data/documentation/api-basics/index.md#authentication)
for the authorization code exchange and refresh details.
### Step 6 - Get the Customer's Accounts {#step-6---get-the-customers-accounts}
Retrieve the connected accounts for the consent. Call the Get accounts endpoint
with the consent-scoped access token from Step 5 and a DPoP proof. FAPI 2.0 does
not use the `X-Consent-Id` header; the consent-scoped token authorizes the call.
API Reference: `GET /accounts`
Use the `include` query parameter to return optional data. This example requests
balances, account holders, and identifiers.
* Sh
```sh
curl --location --request GET 'https://mtf.api.openfinance.mastercard.eu/data/accounts?include=balances,holders,identifiers' \
--header 'Authorization: DPoP ' \
--header 'DPoP: '
```
The response returns the accounts, each with the requested data:
* JSON
```JSON
{
"count": 1,
"offset": 0,
"limit": 10,
"total": 1,
"items": [
{
"id": "59eddfd8-9d4e-4a9f-b7c0-336fc1e57ae9",
"name": "Checking Account",
"identifiers": [
{
"type": "IBAN",
"value": "DE89370400440532013000"
}
],
"balances": [
{
"balanceType": {
"type": "AVAILABLE"
},
"amount": 123.5,
"currency": "EUR"
}
],
"holders": [
{
"relationship": "PRINCIPAL",
"person": {
"fullName": "John L. Smith"
}
}
]
}
]
}
```
You have now retrieved the customer's bank-verified account data, including the
account holder name you can use to verify ownership.
Note: The customer may still be completing the flow when you call this endpoint. In a live integration, we recommend you use webhooks to learn when data is ready instead of polling. Refer to [Webhooks](https://developer.mastercard.com/open-finance-data/documentation/event-notifications/index.md) for details.
### Next Steps {#next-steps}
You have completed the core data-sharing flow in the Sandbox environment. To
continue your integration:
* Learn the full authentication flow, including DPoP proofs and nonce handling, in [API Basics](https://developer.mastercard.com/open-finance-data/documentation/api-basics/index.md#authentication).
* Learn how consent works across its lifecycle in [Consent
Management](https://developer.mastercard.com/open-finance-data/documentation/consent-management/index.md).
* Explore the scenarios you can build in [Use
Cases](https://developer.mastercard.com/open-finance-data/documentation/use-cases/index.md).
* Explore every endpoint in the [API
Reference](https://developer.mastercard.com/open-finance-data/documentation/api-reference/index.md).