Aligment in "transactionOperationStatus" transitions and potential need of new Exception PAYMENT_DENIED

[PedroDiez]

Problem description

It has been detected that in 2-STEP Payment there may be conditions where a given payment can be denied, e.g. User phone_number is blocked for any reason in the OB.

To deal with scenarios an exception is needed. The proposal is to be HTTP 403 CARRIER_BILLING.PAYMENT_DENIED

Related to this, think is important we can have alignment in the understanding of "transactionOperationStatus" so maybe other impacts are required and take advantage of this to reflect appropiate documentation in the context of Issue#106

Then:

1-STEP PAYMENT

• SYNC Process: paymentId is created, transactionOperationStatus is succeeded. It may also makes sense here PAYMENT_DENIED (even paymentId is not created)?

• ASYNC Process: paymentId is created, transactionOperationStatus is processing. Next steps would be:

  If Payment OK, then transactionOperationStatus is succeeded If Payment NOK, then transactionOperationStatus is denied. Therefore I think new event type "PAYMENT_DENIED" would be needed (it would also apply for 2-STEP, but see also relevant in 1-STEP)

2-STEP PAYMENT

• SYNC Process:

  preparePayment: paymentId is created, transactionOperationStatus is reserved. It may also makes sense here PAYMENT_DENIED (even paymentId is not created)? confirmPayment: At this point, If Payment OK, then transactionOperationStatus is succeeded or If Payment NOK, then transactionOperationStatus is denied. cancelPayment: paymentId is created, transactionOperationStatus is cancelled

• ASYNC Process:

  preparePayment: paymentId is created, transactionOperationStatus is processing. It may also makes sense here PAYMENT_DENIED (even paymentId is not created)? confirmPayment: At this point, 202 Accepted and If Payment OK, then transactionOperationStatus is succeeded (indicated by event) or If Payment NOK, then transactionOperationStatus is denied (indicated by event)
  cancelPayment: paymentId is created, transactionOperationStatus is cancelled

cc @bigludo7

Possible evolution

Once aligned behaviour. 1) Document this "transactionOperationStatus" information associated to the track of Improving Documentation Issue#106 2) Consider new event type "PAYMENT_DENIED" (aligned with Commonalities Notifications Design) 3) Add new exception 403 "CARRIER_BILLING.PAYMENT_DENIED" in several methods:

• confirmPayment
• Based on aligment it may also apply to createPayment and preparePayment

Additional context N/A

[bigludo7]

Hello @PedroDiez

1. yes sure. We have crafted the lifecycle here: https://github.com/camaraproject/CarrierBillingCheckOut/blob/main/documentation/API_documentation/resources/Carrier_Billing_State_Engine.JPG and perhaps this one needs to be reworked.

2. I guess we need to think the event type defined for this API. Do we want to have one generic event for all transactionOperationStatus change or do we want to introduce specific event type per status? We can also have both.

3. For the new exception, to be sure to understand, you want it for POST/payments, POST/payments/prepare & POST/Payments/{paymentId}/confirm correct? I tend to think that payment denied should exist as REST resource and query-able. I make a distinction between payment request failing to pass 'surface' control, from the one which are good from a technical perspective but fail business check and get denied. The former are not created as REST resource while the later should be. But if we doing that I'm not sure about proposed 403 usage. Another topic for thinking: when the payment is denied, we probably needs to indicate why.

Happy to continue the discussion...

[PedroDiez]

@PedroDiez comment here the transitions in 1-STEP, 2-STEP before taking API Spec decisions

[PedroDiez]

1. Regarding Transactions (also considering the topic indicated in Issue#116).

For the analysis here, "waiting for validation" will be named as "pending_validation" Will draft image tomorrow (within Issue#116)

1-STEP

• If createPayment is SYNC process in BE. Response contains PaymentId and status=succeeded
• If create Payment is ASYNC process in BE. Response contains PaymentId and status=processing. After completion:

  If payment is OK then status=succeeded. If payment is NOK (any reason) then status=denied

2-STEP (validation is optional depending Business Scenario)

FIRST STEP

• If preparePayment is SYNC process in BE.

  And no validationInfo is present in response. Response contains PaymentId and status=reserved And validationInfo is present in response. Response contains PaymentId and status=pending_validation

• If preparePayment is ASYNC process in BE

  And no validationInfo is present in response. Response contains PaymentId and status=processing

  • After preparePayment Completion status=reserved OR denied And validationInfo is present in response. Response contains PaymentId and status=processing
  • After preparePayment Completion status=pending_validation OR denied

VALIDATE (OPTIONAL)

• After validatePayment status=reserved OR denied (if validation finally failed)

SECOND STEP

• After confirmPayment -> status= succeeded OR denied
• After cancelPayment -> status = cancelled.

[PedroDiez]

2. In the current PR (we can follow that scheme so far in that PR, until output of this iteration which will be a second PR), we have different events, but basically the same model for all of them.

[PedroDiez]

3. Mainly based on Point 1. Proposal would be:

• Have a new event type "denied". In description can be indicated denied reason or adding a metadata to that event.
• Have a new event type "pending_validation" (In the context of Issue#116)
• Have new exception CARRIER_BILLING.PAYMENT_DENIED for (what you mention Ludovic, the situation could happen in each of them, indeed with this we could also cover Issue#117 and avoid adding other exception):

  POST/payments POST/payments/prepare POST/Payments/{paymentId}/confirm

With regards to the use of HTTP 403 is to remark a scenario where API consumer have right Access Token to invoke procedure, but there is a situation where the user is not allowed to perform the payment so it is forbidden.

[PedroDiez]

Hi @bigludo7 analysis completed

[PedroDiez]

Commented during meeting 21/NOV and aligned to be considered in the next PR.

Also agreed to add "deny_reason" optional field for "denied" event model.