dorshay6 commented 4 years ago

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

Once a user is created on locomotion an update will be sent to the billing service.
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.
Before the user makes a ride, Locomotion will check if the user is permitted to book from the billing standpoint.
Balance, billing alerts and billing info will be visible to the user via a webview that will be accessible from the app.
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",
    }

OmerTz commented 4 years ago

who should call this method? /api/v1/users/:userId/rides/:rideId/billing locomotion app? or proxy service?

dorshay6 commented 4 years ago

who should call this method? /api/v1/users/:userId/rides/:rideId/billing locomotion app? or proxy service?

This will be a call from EBS to locomotion, I will make it clear

Respace commented 4 years ago

Thanks for this explanation. This helps us a lot. Anyway we have a few questions regarding the API communication with the planned MOD Payment Service:

What is HBS?
Where is the price of a ride calculated? Does this happen in the EBS?
What is the charing type? Is that meant to seperate the transport of persons or goods?
Is there always one transaction per ride?
Are all the calls on the MoD Paymentservice from the locomotion service or are there direct calls from the app?
Will the price of the ride be in the body of "Ride has final state" ? It has to be, because our payment service will get the final price at least when the final state (= charging) of the ride is reached

Thanks for your help! Theresia

dorshay6 commented 4 years ago

Thanks for this explanation. This helps us a lot. Anyway we have a few questions regarding the API communication with the planned MOD Payment Service:

What is HBS?

Mistype, fixed.

Where is the price of a ride calculated? Does this happen in the EBS?

The price will be calculated in autofleet as it is right now.

What is the charing type? Is that meant to seperate the transport of persons or goods?

Charge type will be one of credit-card, Paypal, apple pay...

Is there always one transaction per ride?

Yes, in case of refunds or changes the transaction should be updated in locomotion with the relevant docs.

Are all the calls on the MoD Paymentservice from the locomotion service or are there direct calls from the app?

No requests will be sent from app for security reasons.

Will the price of the ride be in the body of "Ride has final state" ? It has to be, because our payment service will get the final price at least when the final state (= charging) of the ride is reached That's right, the final price will available on the ride end.

Thanks for your help! Theresia

Respace commented 4 years ago

Thanks for your reply. This leads us to two more questions:

"Ride reached a final state" = For us this is the point in the ride, where the user is charged, when he can't cancel anymore. Did we get this right?
Where is the account balance of the customer stored? We want the account balance to be only stored in our payment service. The response of "Check user ability to book a ride" contains the "balance". But it should contain just the price of the ride, because the balance is checked in the MoD Payment Service?

luxn commented 4 years ago

Hi there,

I'm Max, currently working on the implementation of the payment service (EBS) here at MoD.

I got a few questions regarding the proposal you describes here:

[Post] /api/v1/users

will there be mandatory fields? Currently I have implemented it that way, so that the id and the phoneNumber Field are mandatory ( to check wether it is an upsert or an insert)

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

I understand that there is a good reason why the billing is based per ride (i.e. linked to a ride id). Currently the EBS has no information about rides being processed, so that endpoint will behave kinda equivalent to an insert/upsert behaviour. Currently the RequestBody is yet TBD, so I would propose that we need at least a field for the status of the ride and the price to charge, when the ride is in final state, to process the billing. When I received a call on this endpoint with price information and a final state then I will create a request to [Patch] /api/v1/users/:userId/rides/:rideId/billing as suggested.

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

is there a specific reason why this should be a PATCH instead of a GET Request? I have implemented a payment flow via Paypal inside a webview. I navigate through different html pages via window.location.href in JavaScript. Navigate to a main payment overview page as a patch request looks a bit complicated to me due to the fact that I think it is not really necessary to have a patch method with no body information.

Autofleet / locomotion