Payment Terminal Integration

About

On this page we are outlining how you, as a Payment Terminal provider, can integrate with Monta via our Partner API.

Pre-requisites

During Development

During Development you will need an operator account at Monta with access to Partner API. Your contact at Monta will help you setting it up.

While we have an OCPP Emulator to emulate charge points it is strongly recommended to connect your own, physical charge point, to Monta for testing your integration and develop against the Partner API.

Integration with other Partners

Since your API credentials only work for your own assets at Monta, you need to ask a partner that wants to use your payment solution with their Charge Points to create API credentials for you on their operator account. With these credentials you will be able to perform operations on their behalf as outlined below.

Required Scopes

Depending on the level of integration you are going to need access to these scopes:

Scope	Description	Required
`charge-points:read`	Gives you read-access to all charge points within your operator. You can use this to query for charge points or sites. Since you might have a copy of this already this is optional.	❌
`charge-transactions:read`	This gives you access to read charge transaction within your operator. Charge transactions are created whenever a charge was started. Once the state changed to `completed` they are immutable.	✅
`control-charging:write`	This gives you access to manage charges within Monta. You need this to start/stop charges once your customers have successfully paid.	✅

💡
Read more about Scopes here: https://docs.partner-api.monta.com/reference/ref-authentication#scopes

Example: Charge Flow

Starting a Charge

Given you have:

Access to the charge point,
Permissions to manage charges,
Reserved payment (optionally, how you implement this is up to you)

you can initiate a charge using the POST /charges API. Here we expect the following parameters:

chargePointId: identifies the Charge Point where a charge should be started [mandatory]
payingTeamId: identifies the team that is paying for a charge. Technically we do not collect payments (other than maybe fees) here, but your partner might still want to link these charges to a specific team. [mandatory]
partnerExternalId: an external id that you can use to identify this charge session. Managed by you - we never change or use this field. We recommend setting this on every charge; this allows you to find and identify a started charge even when the start charge call timed out or your service weren't able to capture the charge id or similar. [optional]
genericPaymentSession: this object is specific for payment terminal integrations; we expect you to provide data that makes it possible for users to find a receipt in Monta for a charge initiated by you:
- provider: add a slug that identifies you as provider, should be consistent for your integration. Examples: logos, windcave, ... [mandatory]
- externalId: an identifier that can be used to identify a charging session; ideally something you are displaying to the users. Allows retrieving receipts via receipt.monta.com by using date and externalId or cardLast4. [mandatory]
- partnerExternalId: an external id that you can use to identify this payment session. Managed by you - we never change or use this field. [optional]
- cardBrand: The brand of the card used for the payment session, ie. visa, mastercard [optional]
- cardLast4: The last 4 digits of the card used for the payment session. Allows retrieving receipts via receipt.monta.com by using date and externalId or cardLast4. [optional]

💡
If you know the price model of the charge point you can also limit the charge max kWhs by setting a value for kwhLimit.

Monitoring a Charge

To monitor a charge we recommend making use of our webhooks system. You can find more details here:

As a fallback you can use the Rest API to retrieve information about a charge. If you know the charge.id, make use of GET /charges/{chargeId}, if you weren't able to capture it but you set a partnerExternalId when starting a charge, make use of GET /charges?partnerExternalId={yourPartnerExternalId}.

Since all API consumers are rate-limited, we strongly suggest making use of webhooks though!

Either way, via webhooks or Rest API, you will receive the up-to-date charge object (also known as charge transaction) which provides you with helpful information to manage everything on your end. Most important fields to monitor consumption and state are:

consumedKwh: Consumed kWh during this charge session
state: Indicates the state of the charge session, ie. starting, charging, stopped, released, completed, ...

Stopping a Charge

A charge can be stopped for various reasons:

A user might stop it via the vehicle (by unplugging the cable)
A user might stop it via the Charge Point
A user might stop it via an App, RFID card or other connected solutions
You might stop it via API once the reserved amount (payment) would be exceeded by charging more

To monitor stopped charges not initiated by you, follow the state field on a charge object. If it changed to completed you can use the information on the charge transaction to bill the user.

If you want to stop a charge yourself, make use of the GET /charges/{chargeId}/stop API.