Payment Links
Every eDRV connector now natively supports driver payments collection integrated with session management. Payment Links make it easy for developers to integrate driver payment within their charging applications. Your application kicks off the flow and eDRV's session intelligence takes care of the rest.
eDRV payment links currently support Stripe as the payment provider. We are planning to add more payment processors in the future.
The conditions necessary to start a session with a payment_link
are listed below.
- Admins must define the amount required to authorize a session. This amount will be on hold as a pre-auth on the user's specified payment card.
- The amounts specified (in every API call request and response) are in Cents (100¢ = 1 USD).
- Users can run a session up to the authorized amount. Once the amount has been used, eDRV will attempt to auto-terminate the charging session.
- Currently, the eDRV Payment Links and Wallets support USD (US Dollars) as the default currency. We will add support for other currencies in the near future.
1. Create a Session
POST a new session with the following property:
{
"user": "60e7116e15f9305d44e9d4d5",
"connector": "60e7116e15f9305d44e9d4d5",
"type": "payment_link"
}
The above API call will return the response below. The session.created
and session.payment.created
webhook events will be triggered with the same object.
{
"_id": "60e7116e15f9305d44e9d4d5",
"user": "60e7116e15f9305d44e9d4d5",
"chargestation": "60e7116e15f9305d44e9d4d5",
"connector": "60e7116e15f9305d44e9d4d5",
"status": "created",
"rate": "603763d392204c0c840578be",
"target": {},
"cost": {},
"type" : "payment_link",
"payment": {
"_id": "60376bfbfea89630df8a9f94",
"session": "60e7116e15f9305d44e9d4d5",
"url": "payment_url",
"currency": "usd",
"authorized_amount": 1800,
"type": "anonymous",
"stripe": {
"intent_id": "pi_3MH7kHRJPNC5bQnz19evLjur"
},
"status": "created",
"createdAt": "2021-07-21T12:50:36.660Z",
"updatedAt": "2021-07-21T12:50:36.660Z"
},
"createdAt": "2021-07-21T12:50:36.660Z",
"updatedAt": "2021-07-21T12:50:36.660Z"
}
The session object will have a new entity called payment
with the following schema:
{
"_id": "60376bfbfea89630df8a9f94",
"session": "60e7116e15f9305d44e9d4d5",
"url": "payment_url",
"currency": "usd",
"authorized_amount": 1800,
"type": "anonymous",
"stripe": {
"intent_id": "pi_3MH7kHRJPNC5bQnz19evLjur"
},
"status": "created",
"createdAt": "2021-07-21T12:50:36.660Z",
"updatedAt": "2021-07-21T12:50:36.660Z"
}
Session Minimum Authorized Amount
By default, all payment links will be created with the
payment.authorized_amount = organization.minumum_amount_to_start_session
. This property is set at an organization level and can be updated by the admins from the admin panel.
2. Capturing the Payment
Your application must redirect the user to the session.payment_url
property returned by the session object. This is a payments page powered and secured via the payment processor (Stripe) for collecting the payment/credit card details from the user.
Note: eDRV and your application NEVER collect credit card information. We rely on the security infrastructure of the payment provider for compliance.
The user will have 5 minutes (by default) to enter their card details successfully before the link automatically expires. The expiry time is configurable at the organization level, or can be set at the time of creating a session by using
target.payment_expiry_time
.
Multiple outcomes are possible at this point.
2.1 Payment Success
If the user enters the correct credit card details and the system can process it, a successful session.payment.authorized
webhook event will be triggered.
2.2 Payment Failure or Time Expiry
If the user does not enter the correct credit card details or the system cannot process payment before the expiry time the session.payment.expired
webhook event will be triggered. If the user cancels the payment by clicking the cancel button, the session.canceled
webhook event will be triggered.
3. Starting a Session
When eDRV detects a successful authorization, it will try to start the session on the connector defined in the session object. The system will make multiple attempts to start a session within the remaining time.
- If the session is started, a
session.started
webhook event will be triggered. - If the session cannot be started, a
session.canceled
webhook event will be triggered, the authorized amount will be refunded, and asession.payment.canceled
webhook will be triggered.
5 Minutes Expiry Time
After successfully entering the credit card details, eDRV will expect the session to start within 5 minutes (by default), including entering the correct credit card details and plugging the cable into the vehicle. If this does not happen, the
session.canceled
andsession.payment.canceled
webhook events will be triggered.
4. Pausing a Session
Developers can pause or resume an ongoing session by calling the following APIs. (All OCPP-compliant chargestations ought to support this feature).
- The
GET /sessions/:id/pause
API will stop the energy flow and trigger asession.paused
webhook event. - The
GET /sessions/:id/resume
API will start the energy flow and trigger asession.resumed
webhook event.
5. Session Ends
There is no API to stop a session when the rate attached to a session has a PARKING_TIME component in which case, it can only be stopped in the following two scenarios.
- The user/driver detaches the cable from the charging station.
- When the
session.cost.amount
is about to exceedpayment.authorized_amount
eDRV's session intelligence will attempt to stop an ongoing session to ensure theauthorized_amount
is never exceeded.
If the session does not have a PARKING_TIME rate component, it can be stopped by calling the sessions/:id/stop
API.
Once the session ends (as reported by the charging station):
- A
session.ended
webhook event will be triggered which will have the final cost of the session. - The system will try to capture the final cost from the authorized amount and refund the remaining balance. It will also send a
session.payment.captured
webhook event.
No Session Stops via API when using Overstay Rates
If a session is running on a Rate that has a PARKING_TIME component then you cannot use the Stop API.
In order to accurately calculate the amount of time a driver "overstayed", the session must not be stopped via the API (in this case, the driver removing the connector triggers the charge station to stop the session).
Updated 9 months ago