refund_proposal_and_payment_aligment

[PedroDiez]

What type of PR is this?

• enhancement/feature

What this PR does / why we need it:

This PR covers proposal for refund functionality.

• It provides a design for both total and partial refunds, allowing for asynchronous model in business proceesing
• Events Model covered
• Exceptions Model covered
• Some alignment within commonalities included
• Considering remainingAmount not refunded in Payment resource (i.e. API)
• Considering amount (minimum:0.001) and taxAmount (minimum: 0) to be non-negative
• PhoneNumber aligment in Carrier billing. Exceptions added (draft input to check the whole model after).
• merchantIdentifier model, 422 exceptions and more description for refund
• polimorphic model for refund
• new proposal for remaining payment amount

Which issue(s) this PR fixes:

Initial Proposal - Baseline for:

Fixes #104
Fixes #158

2024-05-15

Fixes #153 (commit 7b224ea)
Rename status to paymentStatus and refundStatus. Also cover amount (minimum:0.001) and taxAmount (minimum: 0) to be non-negative in refunds (commit d12b4cf)

2024-05-24/25

PhoneNumber aligment in Carrier Billing (commit bb99437)
merchantIdentifier model in Carrier Billing Refund, 422 Exceptions, more description (commit 659b2aa)
polymorphic refund model (commit 08837a8)
new proposal for remaining payment amount (commit efe2444)

2024-06-10/11/12

Alignment with Commonalities PR#214 (x-camara-commonalities header) and Notifications CloudEvent Model (commit 4d03b24)
Inclusion of paymentItemId concept ( commit 9c723cd)
fixing some typos and missings in error exceptions (commits e2be576, 8d079e3 and a647dea)

2024-06-19

Description enhancements and description.info alignment with Commonalities ICM output (# Authorization and authentication section) (commit 85a008a)
Semantic enhancements (denied refund in ASYNC context, remainingAmount behaviour, based on Ludovic comments/suggestions) (commit 9377d6c)

2024-06-21
Fixes #154

Commonalities alignment errors (#154) and endpoint versions (commit 8c230ba)

2024-06-27

Fix typo un refund-completed event (paymentDate should read refundDate) (commit 8cfe775)

Special notes for reviewers:

[github-actions]

🦙 MegaLinter status: ✅ SUCCESS

Descriptor	Linter	Files	Fixed	Errors	Elapsed time
✅ ACTION	actionlint	2		0	0.03s
✅ OPENAPI	spectral	2		0	3.95s
✅ REPOSITORY	git_diff	yes		no	0.05s
✅ REPOSITORY	secretlint	yes		no	0.95s
✅ YAML	yamllint	2		0	0.9s

See detailed report in MegaLinter reports

MegaLinter is graciously provided by

[bigludo7]

Hello @PedroDiez

I begun the review and few comments to share with you. Most of this points are not request for change but question I got when I did this review.

• Are we sure to manage refund_in_progress, totally_refunded, partially_refunded as TransactionOperationStatus ? my point is that a payment could have been Succeeded and then refunded. Both state are valid. Need to be sure we did not need to tackle that in a specific refundStatus.
• I'm still not sure if refund should be managed in a separate yaml or same yaml that payment. Have you @PedroDiez good rationale to make them separate?
• Are we sure that refundAmount should be mandatory ? if type is total this could be source of unnecessary error (what about a request with type:total and amount inconsistent btw the payment and the refund?).
• If requester fill refundDetails do we need to make check vs payment item? I guess yes.
• In payment we require a referenceCode in the request - do we need one here for the refund?

[bigludo7]

One quick question.... what is the correlation between refundDetails.refundItem and paymentDetail.paymentItem ? I guess we expect a strong correlation meaning that if I have 3 payment item I could have a refund only for the second item right?
As such in order to have this correlation I'm wondering if we should not add a paymentItem.id in paymentItem and refer this in refundItem.
Perhaps this is 'too much' but got this comment in looking in refundItem and how to use it.

[bigludo7]

Hi @PedroDiez
We're almost there. We have changed the authorization sentences in ICM for the documentation.
also we have probably to have a rule for the remaining amount regarding processing refund.
nothing big here.

[bigludo7]

LGTM/

[bigludo7]

LGTM/

[PedroDiez]

Merging it as commenting in Meeting minutes. Initial wip proposal