Custom integrations

# Introduction

If you want to access the Ponto data of one organization (for account information services – AIS –, and payment initiation services – PIS –) through your bespoke software or self-hosted solution, you should configure a custom integration via the Ponto dashboard this organization. You can easily test your custom integration in the sandbox environment of the organization (refer to our step-by-step guide and to our sandbox documentation).

Creating a custom integration in live or in the sandbox is easy as a walk in a park. On the “Integrations” page of the Ponto dashboard, click to add a custom integration; choose a descriptive name, your desired scope (AIS only or AIS & PIS), and the bank accounts the integration will be authorized to access. Don’t worry, bank accounts can be added and removed at any time from the Integrations overview. 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. See the installation link section for details.

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

# Services

# Account information

Ponto provides you with consolidated information about one or more payment accounts held by your organization with one or more banks. Through a custom integration, you can collect your organization’s account information (account details, balances, transactions history) from your Ponto account and trigger the synchronization of account data.

# Step 1

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.

# Step 2 (optional)

Ponto automatically synchronizes all account details and transactions 4 times per day. So only if your integration requires more up to date information, you can trigger a manual synchronization for a specific account using the Create account data synchronizations API endpoint. This will retrieve the account’s latest balance/transactions in the background. You might want to record the identifier of these synchronization objects to check the status later.

If a synchronization of the same subtype has recently been created for the account (by any integration), the data is considered up to date and an error will be returned. For most financial institutions, the synchronization will be refused if one has been created in the past 5 minutes. In the sandbox, the limit is only 10 seconds to facilitate development.

Poll Ponto Connect to monitor the status of your synchronization. Once the synchronization is completed, you can move to step 3.

Note that manual synchronizations must always be created in the presence of the Ponto user. For this reason the API call requires the real IP address of the currently present customer. Using a fake IP address or executing this call without the presence of the customer is considered as an infringement of our Terms and Conditions and may lead to the blocking of your integrations/organizations.

# Step 3

Collect your organization’s updated account information in Ponto, such as the list of accounts and their balances. In the future we will support webhooks in addition to polling.

Note that Ponto’s API always responds with the data resulting from the execution of the latest successful synchronization of the relevant type for a given bank account. The timestamp of this synchronization is provided in the response.

Remark about pending transactions:

If the bank supports it (refer to attribute the pending_transactions_available in the Financial Institution object), you can list the pending transactions of an account. This option gives you visibility on transactions that have not been entirely processed by the bank yet, but that are already impacting the available balance of the account (positively or negatively). Pending transactions are particularly useful when your software recalculates the balance of the account based on the transaction history.

Tips:

1. The pending transactions are provided only for information purposes. You shall not consider them in your bookkeeping.
2. After processing by the bank, a pending transaction disappears from the list and is converted into a booked transaction, with a different identifier. It is not possible to link a pending transaction with the corresponding booked transaction.
3. You should delete the pending transactions stored in your system each time you list them again for an account. These transactions are volatile, and you should therefore reset your list every time.
4. The execution date of a pending transaction might be NULL if the bank has not yet planned its processing.

# Payment initiation

Ponto allows you to initiate single and bulk payments from payment accounts held by your organization.

You can create payments from a custom integration if you created it with the optional payment initiation scope. Another condition is that the concerned bank supports (bulk) payment initiation through its PSD2 interface. You can verify that condition upfront by checking the value of the paymentsEnabled and bulkPaymentsEnabled parameters for this financial institution in our API.

You must sign each single and bulk payment with the relevant bank from Ponto to complete the payment initiation flow. Note that, except for the sandbox, payment signature will only be enabled in Ponto after Isabel has verified the details of your organization with official sources. When you request payments in Ponto you will be requested to provide details about your organization’s legal representatives and beneficial owners, if relevant.

# Some remarks about bulk payments

• A bulk payment is a single payment instruction that includes multiple payments that are processed together by your bank.
• We currently support SEPA bulk payments only. Which means that the currency of your ordering account must be EUR, that the currency of each payment in your bulk must be EUR, and that the creditor account of each payment in your bulk must be a valid IBAN in the SEPA.
• You can add up to a thousand (1000) single payments in a bulk.
• You can set the batchBookingPreferred attribute to request a batch entry for the sum of the amounts of all payments in your bulk. Otherwise, your bank will create a single entry per payment in the bulk.

We also invite you to carefully check the payment attribute requirements in our API reference, for single and bulk payments.

# Step A

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.

# Step B

Create a payment or bulk payment via the API.

• Option 1: Create a single or a bulk payment without a redirection URI

  You must log in to the Ponto dashboard to sign the single or bulk payment that you have created through the API. You might want to record the identifier of this payment object to check its status later.

• Option 2: Create a single or a bulk payment with a redirection URI

  If you provide the optional redirectUri attribute when you create the single or bulk payment, you will receive a redirect link to Ponto’s authorization portal in the API response. You will also receive the identifier of this payment object, which you can use to check the status of your payment later. You should use Ponto’s authorization portal URI to start the payment authentication flow immediately in Ponto. At the end of the payment authentication flow with the bank, we will redirect you to the redirectUri that you specified in your request.

  This option will only be available after you have requested payments in Ponto and, except for the sandbox, Isabel has verified the details of your organization with official sources.

  Note: Single or bulk payments with redirection URI that are not yet signed are not shown in the user’s dashboard. They should only be signed by redirecting the user. Once the status of the payment changes, it will be visible in the user’s payment history.

Note that in both cases, the (bulk) payment has the status unsigned until the signature flow is initiated in Ponto.

# Step C

Poll Ponto to monitor the status of your (bulk) payment. The possible statuses are listed below:

# Development resources

Our main objective at Ponto is to facilitate your implementation of our APIs. For that purpose, we offer a series of assets that you can leverage to speed up the development of your application.

# Comprehensive documentation

On our documentation website, we guide you step by step and deliver advice to help you optimize your Ponto implementation.

# Sandbox

Your sandbox is the environment where you can test your application and experiment in an ongoing way without impacting your operations. It is your virtual space dedicated to testing, which simulates the behavior of a live environment. Your sandbox will accompany you during the entire development life cycle, even after the go live when you want to add functionalities to your software.

The next drawing helps you understand how you can leverage your sandbox to experiment with your software before going live with Ponto API and accessing the financial data of your organization.

In the above drawing:

• Software to manage sandbox data is software you may develop that integrates the Ponto sandbox configuration API.
• Ponto sandbox configuration API is the interface you use to configure your personalized test data in the sandbox.
• Test software is your application running locally or in your testing environment, connecting to Ponto API with sandbox credentials.
• Live software is the production version of your application that connects to Ponto API with live credentials.
• Ponto API is the interface you use to collect account information or initiate payments. It is the same interface for addressing both sandbox and live data sources.
• Financial institution is the data source for Ponto.
• Organization is the client of a financial institution and has one or several bank accounts. The organization has personalized security credentials (e.g., card reader, card, login, password, pin code…) to authenticate with the financial institution and authorize access to their bank accounts.

1. Your testing journey starts with the creation of a Ponto account and of a sandbox custom integration (read more in our getting started guide).

2. Financial institutions are the source of the account data, either in real life or in the sandbox. The credentials used by your software to authenticate with Ponto will determine whether your software connects to real financial institutions or fake ones in the sandbox. With sandbox credentials, you can retrieve the list of fake financial institutions through our API. The sandbox of an organization is pre-provisioned with fake bank accounts linked to our fake financial institutions. Each bank account contains randomly created fake transactions.

3. With sandbox credentials, you can retrieve the list of the pre-provisioned fake accounts and transactions for an organization. It will be useful for defining your test scenarios for example. You can also create and update transactions in the organization sandbox to test many use cases (it is not possible to delete transactions).

4. Your application’s testers and organizations are data consumers who create sandbox or live custom integrations between your software and Ponto, in order to access the bank account information of their organization from your software or initiate payments. In the sandbox environment, your tester will typically add a subset of the organization’s fake bank accounts to the scope of their sandbox integration to test different use cases.

   Remember that there is no difference between the sandbox and the live environment in terms of coding your application (e.g., when retrieving the bank accounts and transactions added to the scope of an integration). As explained above, the routing to sandbox or live is based on the credentials used by your software and the syntax of your requests is the same in both cases. Therefore, you can easily move your software from the sandbox to live when it is ready.

Remarks:

• The Ponto sandbox can only access sandbox data in Ponto (hint: the digipass response is always “123456” when adding new sandbox bank accounts).

• You will see that the payment initiation service is enabled by default in the sandbox. As for the account information service, the digipass response is always “123456” when signing a single or a bulk payment in the sandbox. Heads-up: the payments you create and sign in your sandbox are not yet added automatically to your sandbox account’s transaction history.

• If you want to test our Ponto for representatives feature in the sandbox, you must create two separate organizations in two different Ponto accounts. It is not possible to give a mandate to your own organizations. In the sandbox, you can grant the representative role to your organization yourself via the organization settings (click to receive an invitation link that you can use to receive sandbox mandates).

# Librairies

You can consult and use our open-source client libraries to construct your client application.

# Support

We offer various support channels through which you can directly interact with our development team to receive technical advice.

# 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 Accounts page and click the button to add an account.

Select a sandbox financial institution and follow the authorization flow to link fake bank accounts to your Ponto organization (hint: the digipass response is always “123456” when adding new fake bank accounts).

Go to the Integrations page and click to add a custom integration. Select a name for your sandbox integration and specify your scope of choice. At this point you can select the fake bank accounts that you want to access through this sandbox integration.

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.

# Installation link

To facilitate the creation of a custom integration, we provide a custom integration “installation link”. When you go to https://dashboard.myponto.com/new-custom-integration?customIntegrationName=Fake TPP you will be directly taken to the form to create a new custom integration with the name prefilled to your choosing. You can share this link with someone to make the setup of a custom integration easier.

This installation link will take you to the following page. Clicking continue will take you to the pre-filled form.

Note that you can test this link in sandbox by adding the flavor: https://dashboard.myponto.com/sandbox/new-custom-integration?customIntegrationName=Fake TPP

# Go live

Once your software is ready and has been tested in the sandbox, the next step is to kick off your operations with your live bank accounts. First, make sure you are in the “live” tab of the Integrations page on the dashboard. Now, just as you did for the sandbox in Getting started, create a new integration and add bank accounts.

Update your software configuration with the client credentials for your live integration. You don’t need to make any other changes to your code. Now when you call the Ponto API, you will automatically receive the account information corresponding to your organization’s live accounts. Switching your application over to your live Ponto environment is as easy as updating your client credentials. All of the Ponto API endpoints work the same way as in the sandbox, but now with real connections to your live Ponto accounts.

You are ready to go live. Enjoy the open banking revolution!