Better documentation of prices in the TOMP API endpoints /bookings and /payment

[zerwuff]

Is your feature request related to a problem? Please describe.

As a TO, i want to have a clear understanding of the difference pricing endpoints.

under booking/ there is pricing information as well as under payment/journal-entry

Urgency

Major

Additional context

As a TO, i want to submit the final price with all fees of the booking to the MP, so the MP can initiate b2b payment processes to the TO.

Describe the solution you'd like

Documentation, were to show price information

• before the ride
• during the ride
• after the ride
  and where a final price between TO and MP shall be communicated.

Describe alternatives you've considered

Possible Implementation

Add documentation or use cases when to use the booking api or the payment api when exchanging price information between TO and MP

[edwinvandenbelt]

Ok! We hope we can address all requirements.

1. before the ride, you can obtain detailed information about the trip using the /inquiries or /offers. In each option, you'll see the 'princing' field, containing a Fare. This might be a fixed price, a price per distance/time, even in tiers. Or a combination of them (the FareParts).

• (v1): it's in the 'pricing' field of the offers [POST /planning/inquiries or POST /planning/offers]
• (v2): you'll only retrieve the price (amount of money) in the offers [POST /processes/search-offers/execution], and an (optional) link to the fares endpoint, explaining the pricing rules [GET /collections/fares/items?product={{product}}].

2. This is a nice one. I don't think we had this request before, but the pricing rules are open.

• (v1): you'll find them directly in the offer ('pricing'-field) [POST /planning/inquiries or POST /planning/offers]
• (v2): you have to fetch them from the GET /collections/fares/items?product={{product}} endpoint. Alternatively, if this one is not facilitated, you can retrieve it from the GET /collections/payments/items?package={{packageId}} endpoint. Hopefully, the implementation returns the unfinished entries as well. If it is, you'll also have the advantage of getting information about the used time and traveled distance.

3. after the ride, you always have to fetch the information using

• (v1): GET /payment/journal-entries?id={{bookingId}}
• (v2): GET /collections/payments/items?package={{packageId}}

4. when the price is final...

• (v1): no facility
• (v2): I've just added 'PRICE_FINAL' notification in the MP module, so the TO can send a notification to the MP that a specific package (booking) has obtained its final price.

[zerwuff]

Hi @edwinvandenbelt thanks for looking into this. That explains it a bit better :)

What is the intend behind TO : get Bookings/{Id}/.pricing :
Is this endpoint used for one of the stages 1-4 your described or for which use case is this right one ?
I would assume, this might be right for bookings that might not have the final price, but the MP wants to show an estimated price the TO can calculate so far (e.g. maybe for carsharing ?)

I found it pretty useful to have this explanation find its way to the wiki, either under payment or under booking ? what do you think ?

[edwinvandenbelt]

We'll add it to the wiki! Thanks for the remark! Can I close this issue after documenting it on the wiki?

[zerwuff]

Hi @edwinvandenbelt yes, that should be fine - close after documentation, cheers :)