Receive PayShap with Partner-Auth

Overview

The payment authorisation step requests that the corporate client verify that a requested payment can be made to a particular proxy.

It is important to note that a successfully authorised (approved) payment does not necessarily mean that the payment is final. The funds may not yet have been applied to the customer's account (or wallet or record) at the time of authorisation. However, after approving a transaction, the corporate client may not revoke the payment. The client will be obliged to make the payment to the customer's account once a completion is sent from BankservAfrica (the scheme operator), unless the payment is subsequently cancelled by BankservAfrica itself.

When participating in authorisation of a payment, the corporate client may take the following into account:

• Whether the account/wallet/record corresponding to the given proxy exists and is valid.
• Whether any payment limits that may be relevant to the client are exceeded or not. Note that Electrum validates that PayShap transaction amounts do not exceed the scheme limit. Hence, this does not need to be validated by the corporate client.
• Whether an invoice linked to the given proxy is still valid or has expired.

The diagram below describes the complete transaction journey for a successful proxy-based PayShap payment that you will receive. The clearing phase consists of payment authorisation and payment finalisation.

Proxy Resolution

The proxy resolution phase aims to determine that the proxy identifier is valid and returns the details of the associated customer record in your system. The end-user that initiated the payment from their banking app can then confirm the details before initiating a credit transfer to the proxy.

1. Electrum sends you an inboundSynchronousIdentifierDetermination request via the /identifiers/inbound/identifier-determination-sync endpoint (IdentifierDeterminationRequest schema; below).

No content

2. You identify the customer proxy and verify the related customer record.

3. You return an IdentifierDeterminationResponse to Electrum (see schema below).

{
  "schema": "IdentifierDeterminationResponse",
  "messageIdentifiers": {
    "messageIdentification": "9fd51c1234ba4819bbheyde296a68e1da",
    "creationDateTime": "2022-05-04T03:22:11Z"
  },
  "originalMessageIdentifiers": {
    "messageIdentification": "8fd51c7124ba4819b9253e296a68e1da",
    "creationDateTime": "2022-05-04T03:02:01Z"
  },
  "report": {
    "originalUetr": "f27a34ad-c5ab-4b70-a3f9-946d743eaeaa",
    "originalVerificationIdentification": "1001",
    "schema": "ZA_RPP",
    "reportInformation": { … },
    "instructedAgent": { … },
    "instructingAgent": { … },
    "originalRequestor": { … }
  },
  "supplementaryData": {
    "customData1": "My custom data 1",
    "customData2": "My custom data 2"
  }
}

Handling Duplicate or Multiple Proxy Resolution Requests

You may sometimes receive more than one proxy resolution request for the same payment. Here is an example of how this may happen:

A payer wishes to make a payment to you, and their sending bank sends you a proxy resolution request via Electrum. You return a positive proxy resolution response, and this is presented to the payer. The payer takes some time to confirm the payment (perhaps they wish to confirm some payment detail, for example). Once the payer does confirm the payment, the bank sends you another proxy resolution before initiating the clearing step. This second resolution is not presented to the payer. It is simply used as an internal safety check between bank and corporate client, to ensure that nothing has changed in between the times when the payer saw the proxy resolution results and confirmed that they wished to pay.

You need to know the following:

• A proxy resolution can be considered as a type of lookup, an independent transaction which has no financial impact. It does not have to be followed by a clearing step.
• You may receive multiple proxy resolution requests for the same payment.
• Each new proxy resolution will contain a different UETR. Therefore, do not try to match a specific payment completion step to a specific UETR. The clearing message will contain all necessary payment details, including the UETR of the proxy on which the payment is based.

Error Handing

Technical Error

If you experience a technical error and are unable to process the request, then respond with an appropriate failure response as described in the Error Handling and Failure Responses section.

Negative Outcome

If you are able to process the request, but the result is negative, then respond with IdentifierDeterminationResponse that includes appropriate values for report.reportInformation.outcome and report.reportInformation.reasonCode. The table below indicates the possible reasonCode values in different scenarios. Electrum will respond to the scheme that the transaction was unsuccessful. No further action from you is required for this transaction.

{
  "schema": "IdentifierDeterminationResponse",
  "messageIdentifiers": {
    "messageIdentification": "9fd51c1234ba4819bbheyde296a68e1da",
    "creationDateTime": "2022-05-04T03:22:11Z"
  },
  "originalMessageIdentifiers": {
    "messageIdentification": "8fd51c7124ba4819b9253e296a68e1da",
    "creationDateTime": "2022-05-04T03:02:01Z"
  },
  "report": {
    "originalUetr": "f27a34ad-c5ab-4b70-a3f9-946d743eaeaa",
    "originalVerificationIdentification": "1001",
    "schema": "ZA_RPP",
    "reportInformation": { … },
    "instructedAgent": { … },
    "instructingAgent": { … },
    "originalRequestor": { … }
  },
  "supplementaryData": {
    "customData1": "My custom data 1",
    "customData2": "My custom data 2"
  }
}

Timeout

If Electrum does not receive any response from you within the appropriate time limit then Electrum will respond to the scheme that the transaction was unsuccessful. No further action is required from you.

Payment Authorisation

1. Electrum sends an inboundCreditTransferAuthorisation request to you via the /transactions/inbound/credit-transfer-authorisation endpoint (CreditTransfer schema; see below). This is an asynchronous call.

No content

2. You respond with an acknowledgement (ACK) in the form of an HTTP 202 status code with no additional content.

3. You identify the customer record and determine whether the payment of the given amount as per the request message can be authorised for that customer record.

4. You return an inboundCreditTransferAuthorisationResponse message to Electrum via the /transactions-inbound/credit-transfer-authorisation endpoint (PaymentStatusReport schema; see below).

No content

5. Electrum responds with an acknowledgement (ACK) in the form of an HTTP 202 status code with no additional content.

Error Handling

Technical Error

If you experience a technical error and are unable to process the authorisation request, then respond with an appropriate failure response as described in the Error Handling and Failure Responses section. If Electrum receives a negative HTTP response, or no response at all, we may retry the request message. If the issue persists, a timeout will occur and Electrum will respond to the scheme that the transaction was unsuccessful. Your system will receive an inboundCreditTransferCompletion message with a status code of REJECTED or CANCELLED, to inform you of the attempted payment that has failed. Electrum will send the message to you repeatedly via a store-and-forward (SAF) queue until you acknowledge receipt with an HTTP response.

Negative Outcome

If you are able to process the authorisation request, but the result is negative, then respond with inboundCreditTransferAuthorisationResponse message (PaymentStatusReport schema) that includes appropriate values for status.outcome and status.reasonInfo.reason. The table below indicates the possible status.reasonInfo.reason values in different scenarios. Electrum will respond to the scheme that the transaction was unsuccessful. No further action from you is required.

Timeout at Electrum

If Electrum does not receive an inboundCreditTransferAuthorisationResponse from you within the appropriate time limit then Electrum will respond to the scheme that the transaction was unsuccessful. Your system will receive an inboundCreditTransferCompletion message (PaymentStatusReport schema) with a status code of REJECTED or CANCELLED, to inform you of the attempted payment that has failed. Electrum will send the message to you repeatedly via a store-and-forward (SAF) queue until you acknowledge receipt with an HTTP response.

Error at Electrum

If Electrum experiences a technical error and is unable to process the inboundCreditTransferAuthorisationResponse message, then we will respond to you with an appropriate failure response as described in the Error Handling and Failure Responses section. Electrum will respond to the scheme that the transaction was unsuccessful. Your system will receive an inboundCreditTransferCompletion message (PaymentStatusReport schema) with a status code of REJECTED or CANCELLED, to inform you that the attempted payment has failed. Electrum will send the inboundCreditTransferCompletion to you repeatedly via a store-and-forward (SAF) queue until you return an HTTP response to acknowledge receipt.

Payment Finalisation

After the clearing of an inbound payment has been completed (either successfully or unsuccessfully) at the sponsor bank, Electrum will send an inboundCreditTransferCompletion request to you to notify you of the payment. At this point you can update your own systems to reflect the payment.

1. Electrum sends you an inboundCreditTransferCompletion message, conforming to the PaymentStatusReport schema, that includes a status.outcome field with the final outcome of the payment.

Cannot find OpeAPI operation by operationId or pointer

2. You respond with an acknowledgement (ACK) in the form of an HTTP 2xx status code with no additional content.

Error Handling

No Response from Corporate Client

Electrum treats the inboundCreditTransferCompletion as a must-deliver message and will repeatedly send it to you via a store-and-forward (SAF) queue until you acknowledge receipt with an HTTP response.

If your solution includes the use of Electrum Finance for transaction reconciliation and Electrum does not receive an acknowledgement before the reconciliation window closes, the inboundCreditTransferCompletion transaction will be considered a reconciliation exception. The Electrum daily mark-off extract may contain a transaction which was not seen by your system, and subsequently was not included in your daily mark-off extract.

Testing Your Implementation

Follow the testing procedure described here to make sure you have implemented the functionality correctly.