Last updated

Inbound PayShap Success

Note

The overall message flow for an inbound PayShap transaction will depend on the various options you have chosen to implement.

If the payment is due to a straight credit push from an industry bank, and your institution uses a non-Electrum customer account system for proxy resolution, then refer to flow 1.

If the payment is due to a straight credit push from an industry bank, and your institution uses the Electrum Account Mirror for proxy resolution, then refer to flow 2.

If the payment is a result of an outbound request-to-pay that you have sent, then refer to flow 3.

Important

The paymentTypeInformation.localInstrument field of the credit transfer message will be populated according to the type of PayShap transaction (note: this field must be set to PROPRIETARY):

Pay-by-account: PBA Pay-by-proxy: PBPX Request-to-pay pay-by-account: RTP-PBA Request-to-pay pay-by-proxy: RTP-PBPX

Flow 1: Inbound PayShap with Proxy Resolution

Synchronous and Asynchronous Messaging

Electrum’s standard flow makes use of both synchronous messaging (as in the case of the identifier determination step below) and asynchronous messaging.

Synchronous messaging (between Electrum and bank) is most commonly used for identifier determination processing, however, Electrum does support the use of asynchronous messaging for this purpose.

If your bank uses asynchronous messaging during identifier determination, then your standard flow would be slightly different to what is shown below.

Synchronous and Asynchronous Messaging

For pay-by-account transactions, the proxy resolution step is omitted, and the transaction flow begins where BankservAfrica initiates a clearing transaction (step 5). Also, the paymentTypeInformation.localInstrument field of the credit transfer message will be populated with PBA instead of PBPX.

inbound payshap success proxy res

  1. Electrum receives a proxy resolution request from BankservAfrica.
  2. Electrum forwards this as an inboundSynchronousIdentifierDetermination message (IdentifierDeterminationRequest schema) to you.
  3. You verify the proxy and return an IdentifierDeterminationResponse to Electrum.
  4. Electrum forwards the response to BankservAfrica.
  5. BankservAfrica sends an inbound clearing request to Electrum.
  6. Electrum sends an inboundCreditTransferAuthorisation (CreditTransfer schema) message to you. The paymentTypeInformation.localInstrument field will be populated with PBPX to indicate that this is a proxy-based transaction. You acknowledge with an HTTP response.
  7. You perform validation checks to determine whether the account is open and allows for incoming PayShap payments. You confirm authorisation of the payment by sending an inboundCreditTransferAuthorisationResponse (PaymentStatusReport schema). Electrum acknowledges this response with an HTTP response.
  8. Electrum sends the status report to BankservAfrica.
  9. BankservAfrica concludes the payment and sends a delivery status report to Electrum.
  10. Electrum sends an inboundCreditTransferCompletion (PaymentStatusReport schema) indicating that the payment was successfully concluded. You acknowledge this message with an HTTP response.
Note

A bank can use the inboundCreditTransferCompletion to complete all necessary processing within their systems, including the initiation of posting instructions to the core ledger system.

Alternatively, Electrum also offers the option of sending a Posting message in order to update the core ledger system.

Flow 2: Inbound PayShap with Account Mirror

The diagram below shows the expected message flow if you make use of the Electrum Account Mirror as a means of identifying a payment beneficiary.

In this scenario, your own systems will not participate in the proxy resolution phase directly; instead, Electrum’s systems will handle the incoming proxy resolution request from BankservAfrica without your involvement.

inbound payshap success account mirror

  1. Electrum receives a proxy resolution request from BankservAfrica.
  2. Electrum uses the account mirror to verify that the given proxy is linked to a certain account.
  3. Electrum forwards the response to BankservAfrica.
  4. BankservAfrica sends an inbound clearing request to Electrum.
  5. Electrum sends an inboundCreditTransferAuthorisation (CreditTransfer schema) message to you. The paymentTypeInformation.localInstrument field will be populated with PBPX to indicate that this is a proxy-based transaction. You acknowledge with an HTTP response.
  6. You perform validation checks to determine whether the account is open and allows for incoming PayShap payments. You confirm authorisation of the payment by sending an inboundCreditTransferAuthorisationResponse (PaymentStatusReport schema). Electrum acknowledges this response with an HTTP response.
  7. Electrum sends the status report to BankservAfrica.
  8. BankservAfrica concludes the payment and sends a delivery status report to Electrum.
  9. Electrum sends an inboundCreditTransferCompletion (PaymentStatusReport schema) indicating that the payment was successfully concluded. You acknowledge this message with an HTTP response.
Note

A bank can use the inboundCreditTransferCompletion to complete all necessary processing within their systems, including the initiation of posting instructions to the core ledger system.

Alternatively, Electrum also offers the option of sending a Posting message in order to update the core ledger system.

Flow 3: Inbound PayShap as a Result of an Outbound Request-to-Pay (Using Electrum’s RTP Store)

Request-To-Pay

Electrum’s PayShap Request-To-Pay service allows your bank customers to make payment requests to customers at industry banks, prompting them to pay for goods or services rendered.

Request-to-pay messages must include the following information:

  • The amount requested. You may also opt to allow the payer to pay more or less than the specified amount.
  • The RTP expiry date.
  • The proxy or account number that should be used to make the payment. Therefore an RTP that has been accepted by the payer does not need to be followed by proxy resolution - the details are already included in the RTP request.

The request-to-pay status changes throughout the transaction life cycle, depending on the scenario. For example, a status of PRESENTED means only that the RTP has been presented to the payer, while a status of ACCEPTED means that the payer has accepted the request and elected to make the payment. You should be notified each time an RTP status is updated.

You will need to make use of an RTP Store, where the RTP status can be updated and stored as the transaction progresses. Electrum will retrieve or request the latest RTP status and information from the RTP Store at various points during the subsequent inbound payment transaction - for example, to verify that an RTP has not expired. See this page for a list of possible RTP statuses and what they mean.

The exact nature of the RTP messaging will depend on whether you use Electrum’s RTP Store or your own.

Once a customer at an industry bank receives the RTP, they can choose to accept the request (in which case their bank will initiate a payment to you) or they can decline the request (in which case no payment will be made).

inbound payshap success after rtp

  1. You send an outbound request-to-pay message (RTP) to Electrum, by performing an outboundRequestToPay operation (RequestToPay schema), requesting that someone at an industry bank makes a payment to a customer at your bank.
  2. Electrum logs the RTP in the RTP Store and assigns a status of PENDING.
  3. Electrum forwards the request to BankservAfrica. The request is sent on and presented to the payer at the industry bank.
  4. BankservAfrica sends a notification that the payer has been presented with the RTP.
  5. Electrum updates the RTP status in the RTP Store to PRESENTED. Electrum also sends you an outboundRequestToPayResponse message (RequestToPayResponse schema) with status PRESENTED, informing you that the payment request has been presented to the payer.
  6. If the payer accepts the RTP, then the industry bank sends an inbound clearing request via BankservAfrica to Electrum.
  7. Electrum will first check the status of the RTP in the RTP Store by using a getRequestToPaywithPOST operation. See this page for a list of valid RTP statuses - i.e., those that will allow for subsequent clearing.
  8. If the RTP status is still valid, Electrum sends an inboundCreditTransferAuthorisation (CreditTransfer schema) message to you. and you acknowledge with an HTTP response.
  9. You perform validation checks to determine whether the account is open and allows for incoming PayShap payments. You confirm authorisation of the payment by sending an inboundCreditTransferAuthorisationResponse (PaymentStatusReport schema). Electrum acknowledges this response with an HTTP response.
  10. Electrum sends the status report to BankservAfrica.
  11. BankservAfrica concludes the payment and sends a delivery status report to Electrum.
  12. Electrum sends an inboundCreditTransferCompletion (PaymentStatusReport schema) indicating that the payment was successfully concluded. You acknowledge this message with an HTTP response.
  13. Electrum updates the status of the RTP in the RTP Store to PAID.
Copyright 2025 | Electrum Payments (Pty) Ltd