Billing Integration

Context:

In some cases Locomotion based apps need the ability to manage payments and charging transactions automatically.
As there is significant variability in how charging and billing flows are implemented, the approach is to define a specification that Locomotion app developers would be able to implement against.
This specification is called: External Billing Server API (EBS) and will be provided through a pull request on the public repo.

Requirements

1. Once a user is created on locomotion an update will be sent to the billing service.
2. Every ride that changes its state to one of the final states (completed, cancelled or failed) a request to EBS will be sent with the full ride details, price calculation and user id.
3. Before the user makes a ride, Locomotion will check if the user is permitted to book from the billing standpoint.
4. Balance, billing alerts and billing info will be visible to the user via a webview that will be accessible from the app.
5. Each billing change will be sent to Locomotion server via API, EBS will be able to update charging state, document list (urls) and charge total.

API Security Note

A secret will be defined in both Locomotion and EBS, each request will contain a header - Authorization (JWT bearer token) that will include a secret containing the user id.

    {
        "userId": "UUID"
    }

EBS API Methods Suggested (Locomotion -> EBS):

User Created / Updated (Upsert)

[Post] /api/v1/users

Body:

    {
        "id": "UUID",
        "firstName": "STRING",
        "lastName": "STRING",
        "email": "STRING",
        "phoneNumber": "STRING",
        "createdAt": "STRING",
    }

Response:

    {
        "status": "OK",
    }

Check user ability to book a ride

[Get] /api/v1/users/:userId/current-balance

Response:

    {
        "balance": 100,
        "currency": "USD",
        "currencySymbol": "$",
        "bookingLimitation": "none",
        "charingType": "per-ride",
    }

• bookingLimitation can be of

  • none
  • outstanding-balance
  • missing-payment-method
  • expired-billing-method
  • general-billing-issue

• charingType can be of

  • per-ride
  • top-up

Ride reached a final state

[Patch] /api/v1/users/:userId/rides/:rideId

This method can be called more then one time.

Body:

    TBD

Response:

    {
        "status": "ok",
    }

User billing management page

[Patch] /api/v1/users/:userId/webview

This url should return an HTML to be showed to the user in app after clinking "Billing" from the main menu.

Locomotion API (EBS -> Locomotion)

Update billing status per ride

[Patch] /api/v1/users/:userId/rides/:rideId/billing

This method can be called more then one time, every call will replace the last data saved.

Body:

    {
        "status": "done",
        "priceCharged": 20,
        "currency": "USD",
        "currencySymbol": "$",
        "documents": [
            {
                "name": "Receipt",
                "url": "https://ebs.com/documents/uuid/?token"
            }
        ]
    }

• status can be of
  • done
  • failed
  • processing
  • pending

Response:

    {
        "status": "ok",
    }