Open APIs

 View Only
  • 1.  Create Payment TMF 676

    Posted Nov 02, 2020 05:34

    We need clarity on below mentioned points for the sample request given in specification document of Create Payment API .Please find the below comments added by us on each point.

     

    {

       "name":"Example",

       "description":"a payment example",

       "@type":"Payment",

       "amount":{

          "unit":"EUR",

          "value":10

       },

       "taxAmount":{

          "unit":"EUR",

          "value":1.6

       },

       "totalAmount":{

          "unit":"EUR",

          "value":11.6

       },

       "channel":{

          "id":"channel1",

          "name":"WEB Portal"

       },

       "account":{

          "id":"15463151",

          "href":"https://host:port/accountManagement/v4/account/15463151",

          "name":"Telco fusion account",

          "description":"Jean Pontus's telco account",

          "@referredType":"PartyAccount"

       },

       "paymentItem":[

          {

             "id":"1",

             "amount":{

                "unit":"EUR",

                "value":6

             },

             "taxAmount":{

                "unit":"EUR",

                "value":0.96

             },

             "totalAmount":{

                "unit":"EUR",

                "value":6.96

             },

             "item":{

                "id":"1234",

                "href":"https://host:port/customerBillManagement/v4/customerBill/1234",

                "@referredType":"CustomerBill"

             }

          },

          {

             "id":"2",

             "amount":{

                "unit":"EUR",

                "value":4

             },

             "taxAmount":{

                "unit":"EUR",

                "value":0.64

             },

             "totalAmount":{

                "unit":"EUR",

                "value":4.64

             },

             "item":{

                "id":"666",

                "href":"https://host:port/productOrdering/v4/productOrder/666",

                "@referredType":"ProductOrder"

             }

          }

       ],

       "paymentMethod":{

          "@type":"Check",

          "description":"Check payment",

          "code":"56564655165446",

          "drawer":"Jean Pontus",

          "payee":"TMF Telco",

          "bank":"National Bank",

          "date":"2020-02-01T00:00:00.000Z"

       },

       "payer":{

          "id":"3333333333333",

          "href":"https://host:port/partyManagement/v4/individual/3333333333333",

          "name":"Jean Pontus",

          "role":"payer",

          "@referredType":"Individual"

       }

    }

     

     

    1. As per the sample request array of paymentItem is given on the basis of item type.

     We are assuming that if one paymentItem is failed then whole request will be rollback and gives failure response

     

    1. TotalAmount is inclusive of taxAmount and amount is exclusive of taxAmount in the given sample request.

    We are assuming that taxamount will be given by consumer.  i.e whoever will consume this API will give us the taxAmount which we will use in a request of create payment API .As there is no need to calculate the tax amount at our end.

     

    1. We are not able to understand the flow between PaymentMethodRefOrValue and AccountRef. As one to many relationship is given between PaymentMethodRefOrValue and AccountRef

     Our understanding is that there is should be one to many relationship from AccountRef to PaymentMethodRefOrValue not from PaymentMethodRefOrValue to AccountRef.For example: For single account there can be multiple payment methods like Paytm ,Gpay.

     

    Please confirm on the above assumption given by us on each point.

    ------------------------------
    Akansha Agarwal
    Comviva
    ------------------------------


  • 2.  RE: Create Payment TMF 676

    Posted Nov 03, 2020 03:39
    Hi All,

    We were going through the payment resource and we found that there are few fields having data type Money . Please find the below highlighted fields of data type on the E-R diagram. We are not able to understand this datatype.







    Please help us on the same



    ------------------------------
    Akansha Agarwal
    Comviva
    ------------------------------



  • 3.  RE: Create Payment TMF 676

    TM Forum Member
    Posted Nov 03, 2020 04:30
    Hello Akansha,

    Please note that currently the team is working both on payment API and payment method API (under the leadership of @Daniel Rodic, @Anh Tuan and @Dominic Oyeniran). They can jump in and provide comments.

    for 1/ your question is related to the ​​use of a payment resource itself - is it to log a payment done (successfully or not) or to trigger a payment? My view is curentltly the former - so if a payment is falied a rollback has been done and we use the API to log a failed payment. The team is working to introduct specif resource to manage the payment processing (authorize, initate, reverse)
    2/ For me all amounts will be provided by the API consumer side and not calculated during the payment storing processing (Daniel/Anh Tuân please provide your view).
    3/ If i'm not wrong, today in partyAccount or billingAccount you have the capability to define several paymentMethod by defining several paymentPlan for a account. From the payment method itself probaly Dominic is better placed than me to elaborate.

    Hope it helps

    Ludovic

    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------



  • 4.  RE: Create Payment TMF 676

    TM Forum Member
    Posted Nov 03, 2020 05:22

    Thanks Ludovic

    A few additional points, and also answering the question about Money data type. Hope it helps.
    1. In my view, there is no relevance to failure of a payment item. The payment as a whole will either work or won't work, obviously depending on the payment means being used. For instance, the payment in the example will fail if the payment means is a credit card and the credit limit on the card is less than 11.6 Euro. The items are simply pointers to the things for which the payment is being made.
    2. I think Ludovic is correct about tax - the tax is expected to be calculated externally (by the consumer of the API) and passed in, since the data in the Payment API payload is not sufficient for calculation of tax (no tax codes, no exemptions, etc.).
    3. There is one direct relationship from PartyAccount to PaymentMethod, and one indirect relationship:
       * Direct: defaultPaymentMethod 0..1 - this is the payment method that will be used by default when payments need to be made for obligations on the account. For example, automatic monthly bill payment. There can only be one of these, since otherwise the system will not know which payment method to use.
       * Indirect: paymentPlan.paymentMethod - a PartyAccount account can have multiple payment plans, but each plan has exactly one payment method. The purpose of the payment plan is to deal with Dunning/Collection, to allow a customer to pay off debts that accrued on the account.
    Payment methods used to make ad-hoc payments on the account , not by the default payment method,are not recorded on the account.

    The reverse direction, from PaymentMethod to Account, has two completely different meanings:
    * From the base PaymentMethod class to account, means, as per the documentation, accounts that use this payment method (as in the bullets above). The reason for this is that if a payment method is modified or removed, you will want to know which accounts are affected, and make alternative arrangements if necessary.
    * In principle, an account itself can be a payment method for a payment, whereby a debit was made from one account to satisfy a debt on the other account.

    Payment is a complex data type, not a true entity - we generally don't show complex data types explicitly in diagrams (since it causes clutter). But the swagger and the user guide should contain the definition of all elements in the model, including complex data types.
    But for your reference, the type is basically a currency (unit) and a monetary amount (value):
    "properties": {
      "unit": {
        "type": "string",
        "description": "Currency (ISO4217 norm uses 3 letters to define the currency)"
      },
      "value": {
        "type": "number",
        "format": "float",
        "description": "A positive floating point number"
      }
    }



    ------------------------------
    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.
    ------------------------------



  • 5.  RE: Create Payment TMF 676

    Posted Nov 03, 2020 05:46
    Hi Jonathan,

    Thanks for the response.

    I have still doubt on 1 point currently our product doest follow the payment for multiple products/items so we have decided to create a wrapper of tm forum payment API over our payment API so that we can hit our payment API for different payment item as a single request of tm forum create payment api.So in that scenario there is a possibility of getting the failure response from any of the item.
    For instance: There are two paymentItems in single request one for customer bill and other one for product in this case we will hit our payment API twice and process the consolidated response and wrap it into tm forum response , in that case there could be a possibility that one paymentitem could get the failure response from our api.


    Also for the Money data type of all types of amount, not got clarity .
    Request you to please explain the same again.

    ------------------------------
    Akansha Agarwal
    Comviva
    ------------------------------



  • 6.  RE: Create Payment TMF 676

    Posted Nov 03, 2020 06:06
    Adding one more point for our confirmation , i.e. for dates in document datatype is dateTime but we use Date i.e. java.util.Date

    So please confirm that what is DateTime datatype used  for multiple date variables in tm forum document



    ------------------------------
    Akansha Agarwal
    Comviva
    ------------------------------



  • 7.  RE: Create Payment TMF 676

    TM Forum Member
    Posted Nov 03, 2020 06:42
    To be absolutely accurate, date/time/timestamp fields are represented in the TMF Open API model using the JSON schema semantic, see here for example.
    i.e. the field is "type": "string", "format": "date-time", looking like this: 2018-11-13T20:20:39+00:00 .
    It's up to you (or more accurately your JSON <=> Java translation layer) to translate between this string representation and the internal Java representation.

    We have a dedicated complex data type for a time period, called (well) TimePeriod, that has a start date and an end date. This type is used in many entities to represent a validity period for the entity.
    We have a different complex data type for a time duration, called Duration, which doesn't have a specific date but rather represents the passage of a certain number of time units (seconds, days, etc.).

    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.
    ------------------------------



  • 8.  RE: Create Payment TMF 676

    Posted Nov 03, 2020 06:46
    Hi Jonathan,

    Thanks for the response.

    I have still doubt on 1 point currently our product doest follow the payment for multiple products/items so we have decided to create a wrapper of tm forum payment API over our payment API so that we can hit our payment API for different payment item as a single request of tm forum create payment api.So in that scenario there is a possibility of getting the failure response from any of the item.
    For instance: There are two paymentItems in single request one for customer bill and other one for product in this case we will hit our payment API twice and process the consolidated response and wrap it into tm forum response , in that case there could be a possibility that one paymentitem could get the failure response from our api.


    Also for the Money data type of all types of amount, not got clarity .
    Request you to please explain the same again.

    ------------------------------
    Akansha Agarwal
    Comviva
    ------------------------------

    ------------------------------
    Akansha Agarwal
    Comviva
    ------------------------------