Refund functionality for Payment requests

[anushkaekanayake]

Carrier billing API has provided APIs for performing add to bill functionality of both prepaid and postpaid users, under 1 step and 2 step payments. But most of the business cases are linked with refund related user cases as well. Currently, Carrier billing checkout API definition has not provided any direction on how to manage the refunding related operations. But considering the inter related use cases with the core functionality, can you provide guidelines/support for ,

1. Introduce Refund handling API alone with Carrier billing Camara API.
2. Introduce/enrich document with a proper way of handling Refund related use cases using same APIs with a guided parameter configurations.

Thanks,
Anushka

[PedroDiez]

@anushkaekanayake Thanks for raising this issue. Currently within the WG we are working in aligment API Specification with Commonalities guidelines and also some enhancements for making 1-STEP / 2-STEP Payments process more consistent.

Once covered that, refund feature is expected to be covered and we will use this issue to move forward discussion

[PedroDiez]

As commented in 20/DEC meeting:

• Every Operator to check internally priority of this feature
• Also welcome Use Cases to understand requirements

[PedroDiez]

Feedback so far:

• Telefonica priority is refund
• Ericsson also considers Refund as probably most important one of the features proposed.

@bigludo7, @rartych, @msaeedhassan, please check internally about

• refund
• reversal
• recurrent payments

In order to drive the prioritization of new features

[mohamedsaeedstc]

STC priority is refund (Full / Partial).

[PedroDiez]

Compiling guring this week the high level requirements for TEF Business. I will reflect here within the issue, prior to elaborate a technical proposal

[PedroDiez]

From Ericsson side it is also required refund (Full / Partial).

[PedroDiez]

Summary of the business requirements for Telefonica side:

• Use Case:

A customer complains (whatever reason) to the commerce/merchant where he/she has performed a payment
It is the commerce/merchant the one that triggers the refund (B2B mode). NOTE: a merchant only can trigger refunds for payments performed by it.

• Requirements:

1. Support for Total (understood as final) and Partial refunds. Total refunds can indicate monetary amount or not (in this latter case can be of the whole payment or a limit amount, taking out comissions). Several Partial Refunds can be performed, even not the usual case. And it has to be controlled that the sum of amounts do not exceed payment amount. Partial + Total refund can be also an scenario.

2. Asynchronous procedure, usually the commitment of a refund takes some time, so modelling a procedure with notifications (implicit mode). Main keys:

• refund in progress
• refund failed (system process)
• refund denied (business process)
• refund completed/committed
• refund applied (to inform availability in bill)

3. Management of Idempotency

4. Functionality to get information about the "balance" status of a given payment (i.e. to be able to identify whole amount refunded)

[PedroDiez]

High-Level API Proposal

1) NEW API For Refunds

MAKING A REFUND

NOTE - Not Concluded: How to deal with several refunds per the same payment

REQ:

POST carrier-billing-refunds/{version}/refunds

{
	"paymentId": "qeryfvc27f2",
	"type": total|partial,
	"amountTransaction": 
	{
		"clientCorrelator": "54321",
		"paymentAmount": {
			"chargingInformation": 
			{
					"amount": "10",
					"currency": "EUR",
					"description": "xxxx",
					"isTaxIncluded": true|false
					"taxAmount": "xxxx"
			}
		},
		"referenceCode": "REF-12345"
	},
	"webhook": {
		"notificationURL: "https://merchant.payments/refunds",
		"notificationAuthToken": "kjvbewouvqbwruvbpqeur245g3ewqber"
	}
}

RES:

HTTP/1.1 201 Created

{
	"refundId": "c48g45Aichrf"
}

FETCHING REFUND(s) INFO

GET carrier-billing-refunds/{version}/refunds

#TO DO: Filter criteria, pagination,...

[
	{
		"refundId": "c48g45Aichrf",
		"paymentId": "qeryfvc27f2",
		"type": total|partial,
		"amountTransaction": 
		{
			"clientCorrelator": "54321",
			"paymentAmount": {
				"chargingInformation": 
				{
					"amount": "10",
					"currency": "EUR",
					"description": "xxxx",
					"isTaxIncluded": true|false
					"taxAmount": "xxxx"
				}
			},
			"referenceCode": "REF-12345",
			"transactionOperationStatus": "processing"
		},
		"refundCreationDate": "$date-time",
		"refundDate": "$date-time",
		"webhook": {
			"notificationURL: "https://merchant.payments/refunds",
			"notificationAuthToken": "kjvbewouvqbwruvbpqeur245g3ewqber"
		}	
	},
	....
]

GET carrier-billing-refunds/{version}/refunds/{refundId}

#TO DO: Filter criteria, pagination,...

{
	"refundId": "c48g45Aichrf",
	"paymentId": "qeryfvc27f2",
	"type": total|partial,
	"amountTransaction": 
	{
		"clientCorrelator": "54321",
		"paymentAmount": {
			"chargingInformation": 
			{
				"amount": "10",
				"currency": "EUR",
				"description": "xxxx",
				"isTaxIncluded": true|false
				"taxAmount": "xxxx"
			}
		},
		"referenceCode": "REF-12345",
		"transactionOperationStatus": "processing"
	},
	"refundCreationDate": "$date-time",
	"refundDate": "$date-time",
	"webhook": {
		"notificationURL: "https://merchant.payments/refunds",
		"notificationAuthToken": "kjvbewouvqbwruvbpqeur245g3ewqber"
	}	
}

2) IMPACT IN CARRIER BILLING API

Need to evaluate:

• new transactionOperationStatus for payment to align when the payment is refunded (refund in progress,...)
• check whether makes sense to indicate refund-type applied

[PedroDiez]

Baseline Draft version reviewed in Session 2024-04-03
refund_v0.1_draft.zip

cc @bigludo7 , @eragaji , @rartych

[PedroDiez]

Status on 15th MAY
COVERED:

• Initial proposal is delivered
• Aligned terminology: paymentStatus and refundStatus (also for query params). Manage to appear at root of resource level.
• Cover the fact of not supporting non-negative amount and taxAmount

AGREED:

• Total refund does not indicate amount (is total payment Amount)

MAIN POINTS PENDING:

• Point to check: To create a polymorphic model based on refund type, we can consider a baseline object where all info is the same except "amount" (not needed for total refund). The point here is that probably a better design for this is to move clientCorrelator and referenceCode to the root resource level, so amountTransaction is to be renamed "refundTransaction" and that would be the difference. To be coherent in payment Resource we should do the same. I will explain in the meeting

• Alignment of Error Exceptions/Codes

• Management of taxes in Partial Refunds

• Remaining Payment Amount not refunded

cc @bigludo7, @rartych, @eragaji, @mohamedsaeedstc