Apex Refund Interface

Deprecated feature

The Apex refund interface serves refunds of payments made via the payment page of the JustOn Self-Service Extension. JustOn no longer supports the Self-Service Extension. For refunds, JustOn recommends JustOn Cash Management, which handles them with dedicated refund records, see Configuring Refund Handling and Managing Refunds.

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.