Inbound Returns

If an originating bank has previously initiated an outbound direct debit or outbound credit transfer that was unsuccessful, then it will receive an inbound payment return to reverse the original payment instruction. A payment return can either be:

An unpaid, where an unsuccessful payment at the homing bank has resulted in the automatic generation of an 'unpaid' which is sent to the homing bank.
A dispute, which usually happens when a debit payment has been erroneously taken from a consumer's bank account. The bank then initiates a return of the consumer's money.

In this case, the originating bank is receiving the inbound request. The response to this operation will indicate the success or failure of the return.

The following scenarios describe the payment return transaction flows between you as the originating bank (of the original payment) and Electrum.

Successful Return

The transaction journey of a successful unpaid or dispute transaction is indicated below.

inbound return success

Electrum receives a data file from BankservAfrica containing a number of transactions to be processed. These include normal debit and credit payments, but specifically also a number of inbound unpaid and/or dispute transactions.

Electrum parses the file, separating it into a number of transactions.

The payment return transactions are matched with existing outbound debits or credits previously processed. Once successfully matched, the unpaid/dispute transactions are either stored in the database or processed immediately.

Electrum sends an inboundPaymentReturn request to the inbound/payment-return endpoint (PaymentReturn schema). The message contains a reason for the return in the paymentScheme.schemeData.returnType field, e.g., DISPUTE or UNPAID.

PaymentReturn Schema

required	object (MessageIdentifiers) Holds a point-to-point unique message identification string as well as a message's creation date time.
	object (SupplementaryData) A list of key-value pairs to support adding any supplementary/additional data to an Electrum Regulated Payments API message.
required	object (TransactionIdentifiers) Holds a series of identifiers to identify the transaction or an individual message that is part of a transaction.
required	object (Party) This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.
	object (PaymentAccount) Representation of an account for payment purposes. Note that at least one of `identification` or `proxy` is expected to be present.
required	object (InstitutionIdentification)
required	object (Party) This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.
	object (PaymentAccount) Representation of an account for payment purposes. Note that at least one of `identification` or `proxy` is expected to be present.
required	object (InstitutionIdentification)
	object (InstitutionIdentification)
	object (InstitutionIdentification)
	object (MessageIdentifiers) Holds a point-to-point unique message identification string as well as a message's creation date time.
	object (OriginalTransactionData) Contains key elements related to the original transaction that is being referred to.
required	object (PaymentReturnPaymentScheme) Designates which scheme a payment return is associated with and describes scheme-specific information for the return.
	object (PaymentTypeInformation)
	Array of objects (ReturnReasonInfo) non-empty A list of `ReturnReasonInfo` values providing detailed reason information for the return.
required	object (TransactionAmounts)
schema required	string Value: "PaymentReturn"
settlementDate	string <date> Date on which the amount of money ceases to be available to the agent that owes it and when the amount of money becomes available to the agent to which it is due.

The message is sent via an Electrum store-and-forward (SAF) queue which repeats the message until you return a positive response.

You respond with an HTTP status code of 202.

Once you have successfully processed the transaction, you send an inboundPaymentReturnResponse message to the inbound/payment-return-response endpoint (PaymentStatusReport schema).

PaymentStatusReport Schema

required	object (MessageIdentifiers) Holds a point-to-point unique message identification string as well as a message's creation date time.
	object (SupplementaryData) A list of key-value pairs to support adding any supplementary/additional data to an Electrum Regulated Payments API message.
required	object (MessageIdentifiers) Holds a point-to-point unique message identification string as well as a message's creation date time.
required	object (TransactionIdentifiers) Holds a series of identifiers to identify the transaction or an individual message that is part of a transaction.
	object (InstitutionIdentification)
	object (InstitutionIdentification)
	object (OriginalTransactionData) Contains key elements related to the original transaction that is being referred to.
required	object (PaymentStatusReportPaymentScheme) Designates which scheme a payment status report is associated with and describes scheme-specific information for the payment status report.
schema required	string Value: "PaymentStatusReport"
required	object (Status)

Electrum returns an HTTP status code of 202 to acknowledge receipt of the PaymentStatusReport.

Error Handling

No Acknowledgment File From Electrum to BankservAfrica

If Electrum does not respond to a file sent from BankservAfrica, BankservAfrica will notify you that a file has been sent. You will notify Electrum. The issue will be resolved between BankservAfrica and Electrum. BankservAfrica will resend the file and the transaction will then proceed as for a successful return.

Important

Electrum must ensure that the file is not processed twice.

No Acknowledgment from Bank

inbound return no http response from ob

If Electrum does not receive an HTTP message from you in response to a sent transaction, then Electrum will continue to send the transaction through a store-and-forward queue. If there still no response by the time the reconciliation window closes, then the transaction will be considered a reconciliation exception and must be handled as part of the Back Office/reconciliation process.

Negative Acknowledgement from Bank

inbound return nack from OB

If Electrum receives a negative acknowledgement (NACK, i.e., an HTTP 5xx or retryable HTTP 4xx) in response to a PaymentReturn, then Electrum will continue to send the message via a store-and-forward queue. If Electrum does not receive an acknowledgement (HTTP 202) before the reconciliation window, this transaction will be considered a reconciliation exception.

Note

Electrum will continue to send the message via a SAF queue for all HTTP 5xx and 4xx NACKs that are considered transient (i.e., recoverable). If Electrum receives an unrecoverable HTTP 4xx NACK, then Electrum will stop sending the message and the error will be resolved manually.

No HTTP Response from Electrum

inbound return no http from Electrum

If you send Electrum a PaymentStatusReport and do not receive an HTTP ACK or NACK from Electrum, then you can retry the transaction up to a set number of times before the transaction is considered failed. The failed transaction will be considered a reconciliation exception.