Open APIs

 View Only
  • 1.  Connecting payments and product orders via TMF TMF676_Payment Management API and TMF622 Product Ordering ManagementAPI

    Posted Apr 29, 2021 11:18
    Hello experts.

    I am trying to add Payment to ProductOrder using TMF676 Payment Management API (v4.0.0) and TMF622 Product Ordering Management API (R19.0). I have the following scenario. User creates product order using Product Ordering Management POST product order and he would like to pay for the order using different payment methods (TMF670_Payment_Methods_API_REST_Specification_R17.5.0).

    Detailed use case:
    Customer has product order in amount of 20 EUR and I wants to pay it with Voucher (10 EUR) and with Credit Card (remainder in amount 10 EUR). How should we store such scenario in TMF models?

    Model analysis:
    If I look at the resource model of TMF622 Product Ordering Management API I can see PaymentRef entity with the following explanation: A list of payment references (PaymentRef [*]). If an immediate payment has been done at the product order submission, the payment information are captured and stored (as a reference) in the order.

    Then I look at the TMF676 Payment Management API. There we have the following connections:
    Payment<->(0..n)<->PaymentItem<-(1..1)<->EntityRef

    If I look at model connection from Payment to PaymentMethod (TMF670_Payment_Methods_API_REST_Specification_R17.5.0), I can see that PaymentMethod is in fact payment instance: e.g. credit cart, voucher, cash, ...

    Questions:
    1) What entity should be stored as EntityRef in Payment Management module (ProductOrder, ProductOrderItem, both, ...)?
    2) What is the real life representation of PaymentItem?
    3) If I have product order (productOrderId=5) in amount of 20 EUR and I want to pay with Voucher (10 EUR) and with Credit Card (remainder in amount 10 EUR), should I create two Payment entities each with one PaymentItem that both point to EntityRef ProductOrder (productOrderId=5) and each to its own PaymentMethod?
    4) Why are there amount, taxAmount and totalAmount in Payment and PaymentItem? If I pay 10 EUR with voucher, I do not have any information how to divide the payment between net price and vat.
    5) How to store in the model if the product order was only partially paid (e.g. remaining amount)?
    6) What is the meaning of PaymentMethod.validFor for specific types of payment (e.g. Cash)?
    7) Payment has field paymentDate but PaymentItem doesn't have any filed paymentDate. Is this logical?

    Model inconsistencies: 
    1) If I look at the TMF670_Payment_Methods_API_REST_Specification_R17.5.0, there is field PaymentMethod.description. Voucher extends PaymentMethod and it has duplicated field name: Voucher.description.
    2) If I look at the TMF670_Payment_Methods_API_REST_Specification_R17.5.0, there is field PaymentMethod.preferred, but if I look at the TMF676 Payment Management API (v4.0.0) there is field PaymentMethod.isPreferred.

    Thanks for any clarifications.

    ------------------------------
    Gaber Terseglav
    TO BE VERIFIED
    ------------------------------


  • 2.  RE: Connecting payments and product orders via TMF TMF676_Payment Management API and TMF622 Product Ordering ManagementAPI

    Posted Apr 30, 2021 12:54
    Hello Gaber,

    Just my point of view for some of your questions; I'm sure there are others able to provide a more complete and accurate answer:

    ad 1) In your particular case, I'd use ProductOrder unless the mentioned Voucher is restricted to be used just for specific Product Offers.

    ad 2) As far as I understand it, this refers to CustomerPaymentItem in SID. Imagine that you have three bills due and you get one payment (e.g. one bank transfer, or one payment card charge, etc.) covering all these three bills either completely, or at least partially. Now you need to show that the payment covered the first two bills completely and e.g. the third one just partially. This means that the overall Payment must be split into three PaymentItems with different EntityRefs, each specifying particular amount covered in this item.

    ad 3) Yes, I'd say so.

    ad 4) See point 2 above - if the PaymentItem covers a particular bill, the tax and net amount come from that bill. Moreover, depending on the local legislation, e.g. the voucher may already include a tax as well (imagine a Christmas gift voucher usable for buying a new phone - the person purchasing the voucher didn't want to select the particular phone type, but wanted to make it more "tangible" than just a few banknotes).​
    ad 5) I believe that you may either create a Payment and just use the status to show that it isn't finished yet (e.g. you may want to do that if the payment method is already known and you want to document it - as e.g. in case of using Cash on Delivery for the remainder), or to delay creating it until the payment for the remainder is really made (i.e. the total of amounts from received payments wouldn't cover the full amount from the product order).

    ad 6) validFor may not have a meaning for cash, but the situation would be different for e.g. a voucher or a credit card.

    ad 7) Yes, I believe it is logical. As mentioned above, individual PaymentItems are just parts of one particular Payment made / received. As such, these items may not have different dates.

    Hope it helps

    ------------------------------
    Tomas Hajny
    CD - Telematika
    ------------------------------



  • 3.  RE: Connecting payments and product orders via TMF TMF676_Payment Management API and TMF622 Product Ordering ManagementAPI

    Posted Apr 30, 2021 18:57
    Thanks for your detailed explanation Tomas.

    This is how it could be done, based on my understanding:
    Let us say that we have only one purchaseOrder [id=1] with one net, tax and total amount (e.g. net=50 EUR, tax=5 EUR, total=55 EUR). Customer received voucher for 10 EUR and he would like to use the voucher and pay the rest with cash on delivery. My assumption is that first tax amount is payed and only then net price. Options:
    V1) payment amount of the first payment instrument (voucher) covers entire order tax amount, but only partially order net amount: second payment instrument is needed for the remainder of net amount,
    V2) payment amount of the first payment instrument (voucher) covers entire order tax amount and entire order total amount: second payment instrument not needed,
    V3) payment amount of the first payment instrument (voucher) covers portion of order tax amount: second payment instrument is needed for the remainder of tax amount and entire net amount;

    Data model for the described scenario would look like this (option V1):
    Payment1: [paymentMethod=Voucher, tax=5 EUR, net=5 EUR, total=10 EUR],
    ** paymentItem 1 [tax=5 EUR, net=5 EUR, total=10 EUR]
    ** entityRef 1 [purchaseOrderId=1]
    Payment1: [paymentMethod=Cash on delivery, tax=0 EUR, net=45 EUR, total=45 EUR],
    ** paymentItem 1 [tax=0 EUR, net=45 EUR, total=45 EUR]
    ** entityRef 2 [purchaseOrderId=1]

    ------------------------------
    Gaber Terseglav
    TO BE VERIFIED
    ------------------------------



  • 4.  RE: Connecting payments and product orders via TMF TMF676_Payment Management API and TMF622 Product Ordering ManagementAPI

    Posted Apr 30, 2021 20:15
    ‎You're welcome. :-)

    As far as the split between the tax and the net amount between the two payments is concerned, it probably depends on the local tax legislation rather than anything else. If a prepayment is not taxable in your case, then there may be no tax included in the voucher payment. If it is taxable, I'd assume that the ratio between the tax and net ‎amount would be the same for the two payments. But again, ask your financial specialists.

    Tomas Hajny
    CD - Telematika

    Od: Gaber Terseglav via TM Forum Community
    Odesláno: sobota, 1. května 2021 0:59
    Předmět: RE: Open APIs : Connecting payments and product orders via TMF TMF676_Payment Management API and TMF622 Product Ordering ManagementAPI

    Thanks for your detailed explanation Tomas. This is how it could be done, based on my understanding: Let us say that we have only one... -posted to the "Open APIs" community
    TM Forum Community

    Open APIs

    Post New Message
    Re: Connecting payments and product orders via TMF TMF676_Payment Management API and TMF622 Product Ordering ManagementAPI
    Reply to Group Reply to Sender
    Apr 30, 2021 6:57 PM
    Gaber Terseglav
    Thanks for your detailed explanation Tomas.

    This is how it could be done, based on my understanding:
    Let us say that we have only one purchaseOrder [id=1] with one net, tax and total amount (e.g. net=50 EUR, tax=5 EUR, total=55 EUR). Customer received voucher for 10 EUR and he would like to use the voucher and pay the rest with cash on delivery. My assumption is that first tax amount is payed and only then net price. Options:
    V1) payment amount of the first payment instrument (voucher) covers entire order tax amount, but only partially order net amount: second payment instrument is needed for the remainder of net amount,
    V2) payment amount of the first payment instrument (voucher) covers entire order tax amount and entire order total amount: second payment instrument not needed,
    V3) payment amount of the first payment instrument (voucher) covers portion of order tax amount: second payment instrument is needed for the remainder of tax amount and entire net amount;

    Data model for the described scenario would look like this (option V1):
    Payment1: [paymentMethod=Voucher, tax=5 EUR, net=5 EUR, total=10 EUR],
    ** paymentItem 1 [tax=5 EUR, net=5 EUR, total=10 EUR]
    ** entityRef 1 [purchaseOrderId=1]
    Payment1: [paymentMethod=Cash on delivery, tax=0 EUR, net=45 EUR, total=45 EUR],
    ** paymentItem 1 [tax=0 EUR, net=45 EUR, total=45 EUR]
    ** entityRef 2 [purchaseOrderId=1]

    ------------------------------
    Gaber Terseglav
    TO BE VERIFIED
    ------------------------------
      Reply to Group Online   View Thread   Recommend   Forward   Flag as Inappropriate  




     
    You are receiving this notification because you followed the 'Connecting payments and product orders via TMF TMF676_Payment Management API and TMF622 Product Ordering ManagementAPI' message thread. If you do not wish to follow this, please click here.

    Update your email preferences to choose the types of email you receive

    Unsubscribe from all participation emails





    Original Message:
    Sent: 4/30/2021 6:57:00 PM
    From: Gaber Terseglav
    Subject: RE: Connecting payments and product orders via TMF TMF676_Payment Management API and TMF622 Product Ordering ManagementAPI

    Thanks for your detailed explanation Tomas.

    This is how it could be done, based on my understanding:
    Let us say that we have only one purchaseOrder [id=1] with one net, tax and total amount (e.g. net=50 EUR, tax=5 EUR, total=55 EUR). Customer received voucher for 10 EUR and he would like to use the voucher and pay the rest with cash on delivery. My assumption is that first tax amount is payed and only then net price. Options:
    V1) payment amount of the first payment instrument (voucher) covers entire order tax amount, but only partially order net amount: second payment instrument is needed for the remainder of net amount,
    V2) payment amount of the first payment instrument (voucher) covers entire order tax amount and entire order total amount: second payment instrument not needed,
    V3) payment amount of the first payment instrument (voucher) covers portion of order tax amount: second payment instrument is needed for the remainder of tax amount and entire net amount;

    Data model for the described scenario would look like this (option V1):
    Payment1: [paymentMethod=Voucher, tax=5 EUR, net=5 EUR, total=10 EUR],
    ** paymentItem 1 [tax=5 EUR, net=5 EUR, total=10 EUR]
    ** entityRef 1 [purchaseOrderId=1]
    Payment1: [paymentMethod=Cash on delivery, tax=0 EUR, net=45 EUR, total=45 EUR],
    ** paymentItem 1 [tax=0 EUR, net=45 EUR, total=45 EUR]
    ** entityRef 2 [purchaseOrderId=1]

    ------------------------------
    Gaber Terseglav
    TO BE VERIFIED
    ------------------------------

    Original Message:
    Sent: Apr 30, 2021 12:24
    From: Tomáš Hajný
    Subject: Connecting payments and product orders via TMF TMF676_Payment Management API and TMF622 Product Ordering ManagementAPI

    Hello Gaber,

    Just my point of view for some of your questions; I'm sure there are others able to provide a more complete and accurate answer:

    ad 1) In your particular case, I'd use ProductOrder unless the mentioned Voucher is restricted to be used just for specific Product Offers.

    ad 2) As far as I understand it, this refers to CustomerPaymentItem in SID. Imagine that you have three bills due and you get one payment (e.g. one bank transfer, or one payment card charge, etc.) covering all these three bills either completely, or at least partially. Now you need to show that the payment covered the first two bills completely and e.g. the third one just partially. This means that the overall Payment must be split into three PaymentItems with different EntityRefs, each specifying particular amount covered in this item.

    ad 3) Yes, I'd say so.

    ad 4) See point 2 above - if the PaymentItem covers a particular bill, the tax and net amount come from that bill. Moreover, depending on the local legislation, e.g. the voucher may already include a tax as well (imagine a Christmas gift voucher usable for buying a new phone - the person purchasing the voucher didn't want to select the particular phone type, but wanted to make it more "tangible" than just a few banknotes).​
    ad 5) I believe that you may either create a Payment and just use the status to show that it isn't finished yet (e.g. you may want to do that if the payment method is already known and you want to document it - as e.g. in case of using Cash on Delivery for the remainder), or to delay creating it until the payment for the remainder is really made (i.e. the total of amounts from received payments wouldn't cover the full amount from the product order).

    ad 6) validFor may not have a meaning for cash, but the situation would be different for e.g. a voucher or a credit card.

    ad 7) Yes, I believe it is logical. As mentioned above, individual PaymentItems are just parts of one particular Payment made / received. As such, these items may not have different dates.

    Hope it helps

    ------------------------------
    Tomas Hajny
    CD - Telematika


  • 5.  RE: Connecting payments and product orders via TMF TMF676_Payment Management API and TMF622 Product Ordering ManagementAPI

    TM Forum Member
    Posted May 02, 2021 07:58
    Hi Gaber and Tomas
    I think Tomas has given a fairly complete explanation, many thanks for that. Just a few additions:
    • The payment method API is fairly old (17.5), a newer version is in preparation but I'm afraid I don't have visibility as to when it will be ready.
    • Specifically regarding the preferred/ispreferred inconsistency, newer API swaggers are generated from a single schema source. The PaymentMethod schema has isPreferred, so if and when the corresponding API assets are generated, they will have isPreferred.
    • Regarding overridden fields, JSON schema allows fields to be overridden in subclasses. In the Open API this allows us to provide more detailed descriptions in subclasses, where relevant. I believe that in the generated swagger, you will see only the field from the subclass.
    • The current definition of EntityRef allows you to refer only to a top-level managed entity, you can't reach into a sub-entity (at the moment, to the best of my understanding). So yes you would point to the ProductOrder for which the payment is being made. Perhaps this needs to be enhanced, since you may want to point to specific line items (e.g. order items, or even product order prices) within the order.
    Hope it helps

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------