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 a session.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 and session.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 a session.paused webhook event.
• The GET /sessions/:id/resume API will start the energy flow and trigger a session.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.

1. The user/driver detaches the cable from the charging station.
2. When the session.cost.amount is about to exceed payment.authorized_amount eDRV's session intelligence will attempt to stop an ongoing session to ensure the authorized_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).