Receive PayShap with Auto-Auth

The diagram below describes the complete transaction journey for a successful proxy-based PayShap payment that you will receive.

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).

{
  "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"
  }
}

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"
  }
}

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 Handling

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. 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.

Clearing

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.

No content

2. You respond with an acknowledgement (ACK) in the form of an HTTP 202 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.