Apex Refund Interface

Using the payment page shipped with the (legacy) JustOn Self-Service Extension, businesses used to provide their customers the option to directly pay their invoices. To this end, the JustOn Self-Service Extension could integrate with payment service providers.

JustOn provides an API that allows for creating refunds for a set of related payment balances, like, for example, the payment balances that originate from a specific payment transaction made via a payment service provider.

Implementation Details

The API ONB2.RefundPaymentApi takes a list of related payment balances and creates refund balances for a specified refund amount. Be aware of the following implementation specifics:

The payment balances are not required to be linked to an invoice.
Draft or locked payment balances are ignored.
Both the created refund balances and the related payment balances are locked.
Locked balances are excluded from business processes like Balance Assignment.
Optionally, you can specify the lock reason, which is copied to the field LockedReason__c of the balance records.

Usually, you cannot refund an amount that is larger than the sum of the available payment balances. Optionally, however, you can call the method compensateOverRefund to overcome this limitation. In this case, JustOn will use an overrefund to indicate a missing payment balance, and create an additional payment balance to settle the refund amount. Note that this additional payment balance will be associated to the account, but it will not be linked to the invoice on which the original payment balances are based.

Note

Use the method compensateOverRefund with caution. The passed payment balances may not represent all available payment balances of a related payment. In this case, creating an additional payment balance to settle the refund may cause wrong behavior.

Generally, a refund operation involves the following steps:

A refund balance is created for each payment in the payment list until the refund amount is used up.
A payment balance is always refunded by a related refund balance with the same amount.
If the payment balance amount is larger than the remaining refund amount, the payment balance is split.
The created refund balances are not linked to an invoice. A refund operation does not change the status of an involved invoice.
The created refund balances and the related payment balances are locked. Locked balances are exempt from business processes like balance assignment.

Refund balances can, however, be assigned to open credits.

API Reference

The API ONB2.RefundPaymentApi takes a list of related payment balances and creates refund balances for a specified refund amount.

Method	Description	Required
`global ONB2.RefundPaymentApi setPaymentBalances(List<ONB2__Balance__c> paymentBalances)`	Sets the related payment balances. The payments are refunded in the order as specified by the passed list. Only balances of the type `Payment` or `Prepayment` that are not locked can be refunded.
`global ONB2.RefundPaymentApi setReason(String reason)`	Specifies the lock reason of the created refund balances and the related payment balances.
`global ONB2.RefundPaymentApi compensateOverRefund()`	Enables the creation of additional payment balances to settle a refund if the refund amount is larger than the sum of the amount of the passed payment balances.
`global ONB2.RefundPaymentApi refund(Decimal amount)`	Creates refund balances for the passed payment balances.

Data	Description
`global static String REASON_REFUND_BY_PAYMENT_PROVIDER`	Default reason string for refunds initiated via a payment provider

The refund methods throw an ONB2.Exceptions.ValidationException in the following cases:

Message	Description
`Cannot refund without an existing payment balance`	There have not been set any payment balances.
`Only payment or prepayment balances can be refunded`	The specified list of payment balances contains balances that are not of the type `Payment` or `Prepayment`.
`All payments balances to be refunded must be associated to the same account.`	The payment balances are related to multiple accounts.
`The refund amount of {0} exceeds the available payment amount of {1}.`	The specified refund amount is larger than the sum of the available payment balances, and `compensateOverRefund` has not been enabled.

Credit and Refund Workflows

The following sections illustrate likely business use cases that combine partial credit creation with payment refunds. The examples outline the involved steps and show their key results.

Refunding a payment without creating a credit

(1) Finalize invoice

(2) Register payment

(3) Refund payment

refund_uc1
Refunding a registered payment

For additional examples of complete or partial refunds, see Refund Handling Examples.

Refunding a payment with a credit issued before payment receipt

(1) Finalize invoice

(2) Create (partial) credit

(3) Register payment

(4) Refund payment

refund_uc1a
Refunding a registered payment for a partially cleared (reduced) invoice amount

Refunding a payment with a credit issued after payment receipt

(1) Finalize invoice

(2) Register payment

(3) Create (partial) credit

(4) Refund credited amount

(5) Finalize credit

refund_uc2
Refunding a registered payment after creating a (partial) credit

Refunding a payment with a credit issued after refund

(1) Finalize invoice

(2) Register payment

(3) (Partially) refund payment

(4) Create (partial) credit

(5) Finalize credit

refund_uc3
Refunding a registered payment before creating a (partial) credit

Refund Handling Examples

The following section summarizes some examples for the successful refund handling, illustrating its behavior.

Completely refund a single payment

Payment balances

Amount	Selected for Refund
`-100,00`

Resulting refund and payment balances

Type	Amount	Locked
Payment	`-100,00`
Refund	`100,00`

Partially refund a single payment

Payment balances

Amount	Selected for Refund
`-100,00`

Resulting refund and payment balances after refunding the amount of 25,00:

Type	Amount	Locked
Payment	`-75,00`
Payment	`-25,00`
Refund	`25,00`

Completely refund a split payment

Payment balances

Amount	Selected for Refund
`-75,00`
`-25,00`

Resulting refund and payment balances after refunding the amount of 25,00;

Type	Amount	Locked
Payment	`-75,00`
Payment	`-25,00`
Refund	`25,00`

Partially refund a split payment

Payment balances

Amount	Selected for Refund
`-75,00`
`-25,00`

Resulting refund and payment balances after refunding the amount of 40,00;

Type	Amount	Locked
Payment	`-60,00`
Payment	`-15,00`
Payment	`-25,00`
Refund	`25,00`
Refund	`15,00`

Refund amount is larger than original payment amount

Payment balances

Amount	Selected for Refund
`-75,00`

Resulting refund and payment balances after refunding the amount of 100,00;

Type	Amount	Locked
Payment	`-75,00`
Payment	`-25,00`
Refund	`75,00`
Refund	`25,00`