[Optional] validate Payment procedure in 2-STEP

[PedroDiez]

Problem description There can be the business scenario of 2-STEP payment where a specific payment needs to be validated. In TEF we have this scenario in ES and DE Telcos so far.

It is also understood this situation cannot (be) exists in other Telcos/countries, so we propose a way to have this feature as an optional one, so it does not compromise/impose additional logic to a Telco/Country that does not use/require it.

Possible evolution Proposal is the following:

Some Basis for the proposal: 1) Not needed in 1-STEP.

• In this way, we can also remove validationURL from 1-STEP.

2) Only used in 2-STEP Payment when the validation information is provided. So optional due to Business Requirements In preparePayment response, define new param “validationInfo” (name open, maybe be also for instance otpValidation or paymentValidation), with two variants:

• action: open

  validationURL -> indicates a public URL where the OTP can be input and validated. This is a Backend generated URL so no customizable by the merchant

• action: validate

  authorizationId -> the identifier for this payment authorization -> This is the case where merchant builds the UI related to the paymentValidation so an endpoint is needed for the merchant to invoke the validation

NEW validatePayment endpoint which would have as inputs: o code: OTP received out-of-band o authorizationId, as provided by API en preparePayment

Then validatePayment would look something like on this style:

Request

Response

Additional Points: confirmPayment we would need and extra Exception for the case the payment is not validated yet

• paymentId is not validated yet ("code": "CARRIER_BILLING.PAYMENT_NOT_VALIDATED","message": "Payment has not been validated").

• Probably we may need an extra state "waiting for confirmation" (name in API TBD) to cover with this optional process Some initial input

• If preparePayment is SYNC and no validationInfo is present -> state is “reserved” • If preparePayment is SYNC and validationInfo is present -> state is “waiting for validation” -> when validated it transitions to “reserved” • If preparePayment is ASYNC and no validationInfo is present -> status is “processing” -> when process ends it transitions to “reserved” • If preparePayment is ASYNC and validationInfo is present -> state is “waiting for validation” -> when validated it transitions to “reserved”

Additional context N/A

[PedroDiez]

Please @bigludo7, @rartych, @mohamedsaeedstc take a look to it, in order for the next meeting, any initial doubt/comment is welcome

[bigludo7]

@PedroDiez The state update seems to be correct but probably good for our next meeting to have an updated version of https://github.com/camaraproject/CarrierBillingCheckOut/blob/main/documentation/API_documentation/resources/Carrier_Billing_State_Engine.JPG to be shown (source here: https://github.com/camaraproject/CarrierBillingCheckOut/blob/main/documentation/API_documentation/resources/Carrier%20Billing%20lifecycle%20source.puml). That will be easier to validate - WDYT?

[PedroDiez]

Hi @bigludo7,

Yes, i will try to provide and updated version on Monday EoB

[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]

Source Code:

`@startuml Payment lifecycle

state fork <> state choice <> state end <>

[*] --> choice note left of choice: Business response is provided\nsynchronously or asynchronously

choice --> Processing : Async Processing: Payment request\nis initialised

choice --> fork : Sync Processing --> fork note right of fork: Distinction between 1 step (1S)\nor 2 steps (2S) payment fork: separation between one or stwo steps payment

fork -right-> Succeeded : (1S) Payment\nsuccessfully executed fork -left-> Denied : (1S)/(2S) Payment request\ndenied by carrier

fork --> Pending_Validation : (2S) [Optional] Payment\n validation required fork --> Reserved : (2S) Payment reserved\nsuccessfully executed Pending_Validation -> Reserved: (2S) Payment validated Pending_Validation -> Denied: (2S) Payment not validated

Reserved -down-> Cancelled : (2S) Request to cancel payment\nsuccessfully executed\nor payment reservation expired Reserved -right-> Succeeded : (2S) Payment confirmation\nsuccessfully executed Reserved -left-> Denied : (2S) Confirmation request\ndenied by carrier

Succeeded --> [*] Cancelled --> [*] Denied -up-> end

Pending_Validation: Perform payment validation Reserved: Payment is prepared &\nready to be confirmed.\nAmount is reserved Denied: Payment request is denied\nby back-end payment server Succeeded: Amount has been charged\non customer line Cancelled: Payment is cancelled\nAmount is released

@enduml`

[PedroDiez]

[PedroDiez]

@bigludo7 full analysis done

[PedroDiez]

Let's check tomorrow this comment:

• (1STEP/2STEP) should be added in all transitions (missing on the first 2).

[PedroDiez]

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

A prior PR will be handled to update "Payment Lifecycle" diagram

[PedroDiez]

Source Code: (Updated)

`@startuml Payment lifecycle

state fork <> state choice <> state end <>

[*] --> choice note left of choice: Business response is provided\nsynchronously or asynchronously

choice --> Processing : (1S)/(2S) Async Processing: Payment request\nis initialised

choice --> fork : (1S)/(2S) Sync Processing --> fork note right of fork: Distinction between 1 step (1S)\nor 2 steps (2S) payment fork: separation between one or stwo steps payment

fork -right-> Succeeded : (1S) Payment\nsuccessfully executed fork -left-> Denied : (1S)/(2S) Payment request\ndenied by carrier

fork --> Pending_Validation : (2S) [Optional] Payment\n validation required fork --> Reserved : (2S) Payment reserved\nsuccessfully executed Pending_Validation -> Reserved: (2S) Payment validated Pending_Validation -> Denied: (2S) Payment not validated

Reserved -down-> Cancelled : (2S) Request to cancel payment\nsuccessfully executed\nor payment reservation expired Reserved -right-> Succeeded : (2S) Payment confirmation\nsuccessfully executed Reserved -left-> Denied : (2S) Confirmation request\ndenied by carrier

Succeeded --> [*] Cancelled --> [*] Denied -up-> end

Pending_Validation: Perform payment validation Reserved: Payment is prepared &\nready to be confirmed.\nAmount is reserved Denied: Payment request is denied\nby back-end payment server Succeeded: Amount has been charged\non customer line Cancelled: Payment is cancelled\nAmount is released

@enduml`

[PedroDiez]

Sequence Updated:

[bigludo7]

Works for me. Thanks !