Inbound PayShap Negative Outcomes
As shown in the message flows on the success page, you will always receive a PaymentStatusReport from Electrum at the conclusion of a clearing transaction.
In the case of negative or failed transactions, the PaymentStatusReport will contain a reason code and message detailing the reason for the error. This page provides an overview of common reason codes you may encounter.
Messages between BankservAfrica and Electrum fall under a different API and may contain different reason codes, or reason code meanings, to what you would see in the PaymentStatusReport that Electrum sends you.
Electrum maps the BankservAfrica reason codes to Electrum’s before sending the final message to you.
You can search for and investigate specific failed messages from the Electrum Console or Kibana dashboards.
The sections below describe in more detail the error scenarios you might encounter during an inbound PayShap transaction during the proxy resolution, request-to-pay, or clearing phases.
Proxy Resolution Negative Flows
No Response from Bank
The scenario below may be applicable if you do not use the Electrum Account Mirror.
If Electrum does not receive a response to an inboundIdentifierDeterminationRequest message then a timeout will occur at Electrum. Electrum will send a negative proxyResolutionResponse message with a status code of AB01 to BankservAfrica. The payer will be informed of the failed transaction. No further message processing is required.
Functional or System Error at Bank
The scenario below may be applicable if you do not use the Electrum Account Mirror.
If a functional or system error occurs on your system, then you will return a negative inboundIdentifierDeterminationResponse to Electrum with the relevant reason code (see this page. Electrum sends a negative proxyResolutionResponse message with the BankservAfrica error code to BankservAfrica. The payer will be informed of the failed transaction. No further message processing is required.
Functional or System Error at Electrum
If a functional or system error occurs at Electrum either before or after processing the proxy resolution step with you, then Electrum will return a negative proxyResolutionResponse to BankservAfrica with the relevant error code. The payer will be informed of the failed transaction. No further message processing is required.
If a functional or system error occurs at Electrum while Electrum is processing the proxy resolution request using the Account Mirror (i.e., without your involvement), then Electrum will simply reject the request back to BankservAfrica. You will not receive a message from Electrum informing you of the proxy resolution attempt.
Request-To-Pay Negative Flows
No Status Report from BankservAfrica
If Electrum does not receive a response from BankservAfrica within the timeout period, then Electrum initiates statusReportRequest messages to query the status of the RTP. Electrum continues to send statusReportRequest messages until BankservAfrica returns a response containing a relevant RTP status code.
If the statusReport contains a status code RJCT, then it means the RTP was rejected. Electrum then sends an outboundRequestToPayResponse to you, with the RJCT status code, and the payee is informed of the failed RTP. The outboundRequestToPayResponse is also forwarded to the Electrum RTP Store and the RTP status is updated to REJECTED in the store. If the RTP was accepted, then the clearing leg of the transaction will be initiated.
BankservAfrica Cancels the RTP
BankservAfrica responds to a creditorPaymentActivationRequest with a statusReport including a status of RJCT and a status reason code ofAB01 to cancel the RTP, then Electrum sends an outboundRequestToPayResponse with a REJECTED status to you. The outboundRequestToPayResponse is also sent to the Electrum RTP Store to update the status of the RTP to REJECTED.
Timeout at Bank
If Electrum does not receive an HTTP acknowledgement from you in response to an outboundRequestToPayResponse, then Electrum will send the outboundRequestToPayResponse to you up to 3 times (i.e., 2 retries), or until you return an HTTP 202 response, before stopping.
Since you essentially have not received an outboundRequestToPayResponse from Electrum within a set period, a timeout occurs at your end. You may send status requests via a getRequestToPayWithPOST message (RequestToPayStatusRequest schema) to the Electrum RTP Store after the timeout and receive a RequestToPayStatusResponse with the latest RTP status.
Error at Bank
If a system error or failure occurs on your system after receiving an outboundRequestToPayResponse from Electrum, then you return a negative acknowledgement (NACK) to Electrum. Electrum will send the outboundRequestToPayResponse 3 times (i.e., 2 retries) or until you return an HTTP 202 response, before stopping.
Since you essentially have not received an outboundRequestToPayResponse from Electrum within a set period, a timeout occurs at your end. You may send status requests via a getRequestToPayWithPOST message (RequestToPayStatusRequest schema) to the Electrum RTP Store after the timeout and receive a RequestToPayStatusResponse with the latest RTP status.
RTP Expires in RTP Store
If no clearing transaction is received from industry and the RTP reaches expiration, the RTP Store will update the RTP status to EXPIRED. The Electrum RTP Store forwards an outboundRequestToPayResponse to you to inform you of the RTP expiration.
Clearing Negative Flows
If the inbound payment was based on an outbound request-to-pay then it is assumed that the RTP status must be updated in the RTP Store where applicable during the full transaction flow.
Failed Account Validation at Bank
If a functional or system error occurs in your system while attempting to validate the beneficiary’s account, then you will return a negative creditTransferAuthorisationResponse to Electrum with the relevant error code. Electrum will send a negative paymentStatusReport to BankservAfrica, meaning that clearing will not happen.
No Response to Credit Transfer Authorisation Request
If Electrum does not receive an HTTP acknowledgement from you in response to an inboundCreditTransferAuthorisation, then Electrum will send a negative PaymentStatusReport to you, which will inform you of the need to cancel the payment in your records.
Cancelled Payment
If BankservAfrica cancels the transaction, then Electrum will receive a paymentCancellation message with the reason for the cancellation. Electrum sends a negative inboundCreditTransferCompletion message to you.
BankservAfrica could cancel the transaction for the following reasons:
- BankservAfrica did not receive a
paymentStatusReportfrom Electrum and timed out. - BankservAfrica did receive the
paymentStatusReportfrom Electrum, but experienced internal issues and could not complete the payment.
No Acknowledgment of Payment Status Report from BankservAfrica
If Electrum does not receive an acknowledgement (ACK, HTTP 202) or negative acknowledgement (NACK, HTTP 5xx or retryable HTTP 4xx) from BankservAfrica in response to a paymentStatusReport, then Electrum will retry the message.
If Electrum still does not receive an HTTP response within a specified period, then Electrum will send paymentStatusRequests indefinitely until BankservAfrica responds with a deliveryStatusReport or a paymentCancellation to confirm the final status of the transaction. Depending on whether BankservAfrica’s response is positive or negative, Electrum will send either a positive or negative inboundCreditTransferCompletion to you.
Note: If Electrum does not receive a response from BankservAfrica after multiple paymentStatusRequest messages and a transaction is stuck in a pending state, then alerts will be raised internally for manual investigation. However, Electrum will continue to send paymentStatusRequest messages until BankservAfrica returns a response.
No Delivery Report from BankservAfrica
If Electrum does not receive a deliveryStatusReport or paymentCancellation within a certain period after sending a paymentStatusReport to BankservAfrica, then Electrum sends a paymentStatusRequest to BankservAfrica to determine the outcome of the payment.
Electrum will continue sending the paymentStatusRequest messages indefinitely until BankservAfrica responds with a deliveryStatusReport or a paymentCancellation to confirm the final status of the transaction. Depending on whether BankservAfrica’s response is positive or negative, Electrum will send either a positive or negative inboundCreditTransferCompletion to you.
Note: If Electrum does not receive a response from BankservAfrica after multiple paymentStatusRequest messages and a transaction is stuck in a pending state, then alerts will be raised internally for manual investigation. However, Electrum will continue to send the paymentStatusRequest until BankservAfrica returns a response.
No Response from Bank after Credit Transfer Completion
If Electrum does not receive an acknowledgement (ACK, HTTP 2xx) or negative acknowledgement (NACK, HTTP 5xx or retryable 4xx) from you in response to an inboundCreditTransferCompletion, then Electrum will continue to send the message to you via a store-and-forward (SAF) queue. If there is still no response, and the message is stuck in the SAF queue, then alerts will be raised internally for manual investigation.
Negative Acknowledgement from Bank after Credit Transfer Completion
If Electrum receives a negative acknowledgement (NACK, HTTP 5xx or retryable 4xx) in response to an inboundCreditTransferCompletion, then Electrum will continue to send the message to you via a store-and-forward (SAF) queue. If there is still no response, and the message is stuck in the SAF queue, or if a non-retryable HTTP 4xx response is received, then alerts will be raised internally for manual investigation.