### Dashboard API - Getting Started

Source: https://documentation.myponto.com/developers/dashboard-api

Guide on how to get started with the Ponto Dashboard API, including account creation, sandbox environment setup, and creating a custom integration.

```APIDOC
## Getting started

If you haven’t already, create a Ponto account. It is not necessary to enter any billing information or to add live bank accounts to your organization to test your software in the sandbox environment.

Read more to understand how our sandbox works.

In the Ponto dashboard, click the toggle button to switch to your sandbox environment. Go to the integrations page and click the button to add an integration.
  1. Enter an integration name
  2. Select **dashboard** as the allowed scope.
  3. **Optional:** Add IP filtering to the integration for additional security.

Submit the form and take note of your client credentials (client ID and client secret). You will use these in your software to access the Ponto API.

You are ready to implement the workflows described in our service documentation.
```

--------------------------------

### Dashboard API - Introduction

Source: https://documentation.myponto.com/developers/dashboard-api

Introduction to the Ponto Dashboard API, explaining how to set up custom integrations for accessing organization data and the client credentials grant flow for authentication.

```APIDOC
## Introduction

If you want to manage and access your Ponto data of **one** organization through your bespoke software or self-hosted solution, you should configure a custom integration via the Ponto dashboard for this organization. You can easily test your custom integration in the sandbox environment of the organization.

Creating a custom integration in live or in the sandbox is easy. On the “Integrations” page of the Ponto dashboard, click to add a custom integration; choose a descriptive name, select scope **dashboard** and optionally configure IP filtering for additional security. Once your custom integration is created, the OAuth 2 credentials you need to configure your software (client ID and client secret) will be shown.

**Remarks:**
  * The client secret is only shown once but can be regenerated at any time.
  * We use the client credentials grant flow to deliver access tokens to your software.
  * You can use an installation link to facilitate the creation of a custom integration with a specific name.

Read more in our step-by-step guide and create your first custom integration to test your software.
```

--------------------------------

### Payment Initiation

Source: https://documentation.myponto.com/developers/custom-integrations

Initiate single and bulk payments from your organization's payment accounts. Requires the payment initiation scope and bank support.

```APIDOC
## POST /websites/myponto/payments

### Description
Initiates a single or bulk payment from a specified account. This endpoint requires the payment initiation scope and verification that the bank supports payment initiation via its PSD2 interface.

### Method
POST

### Endpoint
/websites/myponto/payments

### Parameters
#### Request Body
- **paymentDetails** (object) - Required - Details of the payment(s) to be initiated.
  - **fromAccountId** (string) - Required - The account from which the payment will be made.
  - **payments** (array) - Required - A list of individual payment instructions.
    - **toAccount** (string) - Required - The recipient's account identifier (e.g., IBAN).
    - **amount** (number) - Required - The amount of the payment.
    - **currency** (string) - Required - The currency of the payment (must be EUR for SEPA bulk payments).
    - **description** (string) - Optional - A description for the payment.
  - **batchBookingPreferred** (boolean) - Optional - If true, requests a batch entry for the sum of all payments in a bulk. Defaults to false.

### Request Example
```json
{
  "paymentDetails": {
    "fromAccountId": "acc_67890",
    "payments": [
      {
        "toAccount": "IBAN_RECIPIENT_1",
        "amount": 100.00,
        "currency": "EUR",
        "description": "Invoice Payment"
      },
      {
        "toAccount": "IBAN_RECIPIENT_2",
        "amount": 50.00,
        "currency": "EUR",
        "description": "Service Fee"
      }
    ],
    "batchBookingPreferred": true
  }
}
```

### Response
#### Success Response (201 Created)
- **paymentId** (string) - The unique identifier for the initiated payment batch.
- **status** (string) - The status of the payment initiation (e.g., "PENDING_SIGNATURE").

#### Response Example
```json
{
  "paymentId": "pay_abcdef",
  "status": "PENDING_SIGNATURE"
}
```
```

--------------------------------

### Create Account Data Synchronizations API

Source: https://documentation.myponto.com/developers/custom-integrations

This endpoint allows you to manually trigger the synchronization of account data for a specific account. This is useful if you need more up-to-date information than the automatic 4-times-daily synchronization.

```APIDOC
## POST /api/v1/synchronizations/accounts

### Description
Manually trigger the synchronization of account details and transactions for a specific account. This is an optional step if real-time data is required, as Ponto automatically synchronizes data four times daily.

### Method
POST

### Endpoint
/api/v1/synchronizations/accounts

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **account_id** (string) - Required - The unique identifier of the account for which to synchronize data.
- **real_ip** (string) - Required - The real IP address of the customer currently present. This is mandatory for security and compliance reasons.

### Request Example
```json
{
  "account_id": "acc_12345abcde",
  "real_ip": "192.168.1.100"
}
```

### Response
#### Success Response (201 Created)
- **synchronization_id** (string) - The unique identifier for the created synchronization job.
- **status** (string) - The initial status of the synchronization job (e.g., "pending").

#### Response Example
```json
{
  "synchronization_id": "sync_abcdef12345",
  "status": "pending"
}
```

### Error Handling
- **400 Bad Request**: If required parameters are missing or invalid (e.g., invalid `account_id`, missing `real_ip`).
- **409 Conflict**: If a synchronization of the same subtype has recently been created for the account, and the data is considered up-to-date. The limit is 5 minutes for live environments and 10 seconds for sandbox environments.
- **403 Forbidden**: If the `real_ip` is not the actual IP address of the customer or if the call is made without the customer's presence, violating Terms and Conditions.
```

--------------------------------

### Create Payment

Source: https://documentation.myponto.com/developers/custom-integrations

Create a single or bulk payment. Payments can be created with or without a redirection URI. If a redirection URI is provided, the user will be redirected to Ponto's authorization portal.

```APIDOC
## POST /websites/myponto/payments

### Description
Creates a single or bulk payment. This endpoint supports creating payments with or without a redirection URI. If a `redirectUri` is provided, the API response will include a link to Ponto's authorization portal.

### Method
POST

### Endpoint
/websites/myponto/payments

### Parameters
#### Query Parameters
- **redirectUri** (string) - Optional - The URI to redirect the user to after payment authentication.

#### Request Body
- **paymentDetails** (object) - Required - Details of the payment to be created. This object should contain information such as amount, currency, recipient, etc.
  - **amount** (number) - Required - The payment amount.
  - **currency** (string) - Required - The currency of the payment (e.g., 'EUR').
  - **recipient** (object) - Required - Details of the payment recipient.
    - **iban** (string) - Required - The recipient's IBAN.
    - **name** (string) - Required - The recipient's name.
  - **remittanceInformation** (string) - Optional - Additional information for the payment.

### Request Example
```json
{
  "paymentDetails": {
    "amount": 100.50,
    "currency": "EUR",
    "recipient": {
      "iban": "NL91 ABNA 0123 4567 89",
      "name": "John Doe"
    },
    "remittanceInformation": "Invoice #12345"
  }
}
```

### Response
#### Success Response (201 Created)
- **paymentId** (string) - The unique identifier for the created payment.
- **status** (string) - The initial status of the payment (e.g., 'unsigned').
- **authorizationUrl** (string) - Optional - The URL to Ponto's authorization portal if `redirectUri` was provided.

#### Response Example
```json
{
  "paymentId": "pay_abc123xyz789",
  "status": "unsigned",
  "authorizationUrl": "https://auth.ponto.com/authorize?paymentId=pay_abc123xyz789"
}
```
```

--------------------------------

### Price Indexation Formula

Source: https://documentation.myponto.com/en/terms-and-conditions

This formula calculates the new fee amount (P1) based on the previous fee (P0) and the ratio of the current AGORIA index to the base index. It accounts for a fixed component (0.2) and a variable component (0.8) tied to indexation.

```text
P1 = P0 x (0,2 + 0,8 (Current Index / Base Index)
```

--------------------------------

### Authentication

Source: https://documentation.myponto.com/custom-integrations

Obtain an access token required for all Ponto API calls.

```APIDOC
## POST /oauth/token

### Description
Every call to the Ponto API requires a valid access token. You can create an access token using the client credentials that you received when creating the custom integration. Your access token has a life span of 30 minutes.

### Method
POST

### Endpoint
/oauth/token

### Request Body
- **grant_type** (string) - Required - Must be 'client_credentials'.
- **client_id** (string) - Required - Your client ID.
- **client_secret** (string) - Required - Your client secret.

### Request Example
```json
{
  "grant_type": "client_credentials",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}
```

### Response
#### Success Response (200)
- **access_token** (string) - The obtained access token.
- **token_type** (string) - The type of token (usually 'Bearer').
- **expires_in** (integer) - The lifetime of the token in seconds.

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 1800
}
```
```

--------------------------------

### Account Information and Pending Transactions

Source: https://documentation.myponto.com/custom-integrations

Retrieve updated account information, including balances and a list of pending transactions if supported by the financial institution.

```APIDOC
## GET /websites/myponto/accounts

### Description
Collect your organization’s updated account information in Ponto, such as the list of accounts and their balances. The API responds with data from the latest successful synchronization. It also provides an option to list pending transactions if the bank supports it, offering visibility into transactions impacting the available balance before they are fully processed.

### Method
GET

### Endpoint
/websites/myponto/accounts

### Query Parameters
- **account_id** (string) - Optional - The ID of the specific account to retrieve information for.
- **include_pending_transactions** (boolean) - Optional - Set to `true` to include pending transactions if available.

### Response
#### Success Response (200)
- **accounts** (array) - A list of account objects.
  - **account_id** (string) - The unique identifier for the account.
  - **balance** (object) - The current balance of the account.
    - **currency** (string) - The currency of the balance.
    - **amount** (number) - The balance amount.
  - **pending_transactions** (array) - A list of pending transactions (if `include_pending_transactions` is true and supported).
    - **transaction_id** (string) - Unique identifier for the pending transaction.
    - **description** (string) - Description of the transaction.
    - **amount** (number) - The amount of the pending transaction.
    - **currency** (string) - The currency of the pending transaction.
    - **execution_date** (string) - The planned execution date (can be null).
- **synchronization_timestamp** (string) - The timestamp of the last successful synchronization.

#### Response Example
{
  "accounts": [
    {
      "account_id": "acc_12345",
      "balance": {
        "currency": "EUR",
        "amount": 1500.75
      },
      "pending_transactions": [
        {
          "transaction_id": "ptxn_abcde",
          "description": "Online Purchase",
          "amount": -75.50,
          "currency": "EUR",
          "execution_date": "2023-10-27T00:00:00Z"
        }
      ]
    }
  ],
  "synchronization_timestamp": "2023-10-26T10:00:00Z"
}
```

--------------------------------

### Dashboard API - Services

Source: https://documentation.myponto.com/developers/dashboard-api

Overview of the Ponto Dashboard API's services, including user management, organization representation requests, and mandate/organization management.

```APIDOC
## Services

Ponto’s Dashboard API is designed to help developers automate routine administrative tasks within their organizations, making daily operations more efficient and less time-consuming.

**Common uses cases:**
  1. _**User Management**_ : Add users to your organization and assign roles through the API, simplifying the process of onboarding new team members.
  2. _**Organization Representation Requests**_ : Automating the process of requesting access in order to represent other Ponto organizations.
  3. _**Mandate and Organization Management**_ : Manage represented organizations and their mandates.

#### Step A
To begin using the Dashboard API, you’ll need to create a custom integration with the scope **dashboard**. Once this scope is assigned, you can request an access token, which will grant you the necessary permissions to interact with the Dashboard API.

Every call to the Ponto API requires a valid access token. You can create an access token using the client credentials that you received when creating the custom integration. Your access token has a life span of 30 minutes. Ensure that the custom integration has the scope _‘dashboard’_ assigned.

#### Step B
Explore Our API Documentation
To get a comprehensive overview of all available Dashboard API calls and how to use them, visit our API documentation. There, you’ll find detailed information on the endpoints, parameters, and examples to help you fully utilize the Dashboard API’s capabilities.
```

--------------------------------

### Account Information and Pending Transactions

Source: https://documentation.myponto.com/developers/custom-integrations

Retrieve updated account information, including balances and pending transactions. Ponto's API returns data from the latest successful synchronization.

```APIDOC
## GET /websites/myponto/accounts

### Description
Retrieves a list of accounts and their balances, along with the timestamp of the last successful synchronization. Optionally, it can also retrieve pending transactions if supported by the financial institution.

### Method
GET

### Endpoint
/websites/myponto/accounts

### Parameters
#### Query Parameters
- **include_pending_transactions** (boolean) - Optional - If true, includes pending transactions for accounts where supported.

### Request Example
```
GET /websites/myponto/accounts?include_pending_transactions=true
```

### Response
#### Success Response (200)
- **accounts** (array) - A list of account objects.
  - **accountId** (string) - The unique identifier for the account.
  - **balance** (object) - The current balance of the account.
    - **amount** (number) - The balance amount.
    - **currency** (string) - The currency of the balance.
  - **lastSynchronization** (string) - The timestamp of the last successful synchronization.
- **pendingTransactions** (array) - (Optional) A list of pending transaction objects, only present if `include_pending_transactions` is true and supported.
  - **transactionId** (string) - The unique identifier for the pending transaction.
  - **description** (string) - A description of the transaction.
  - **amount** (number) - The transaction amount.
  - **currency** (string) - The currency of the transaction.
  - **executionDate** (string) - The planned execution date (can be null).

#### Response Example
```json
{
  "accounts": [
    {
      "accountId": "acc_12345",
      "balance": {
        "amount": 1500.75,
        "currency": "EUR"
      },
      "lastSynchronization": "2023-10-27T10:00:00Z"
    }
  ],
  "pendingTransactions": [
    {
      "transactionId": "pend_abcde",
      "description": "Online Purchase",
      "amount": -75.50,
      "currency": "EUR",
      "executionDate": "2023-10-28T00:00:00Z"
    }
  ]
}
```
```