Step 0: PayShap Outbound Proxy Resolution

Important

This step only applies to the PayShap scheme.

Overview

The initial phase of an outbound PayShap payment involves resolving the beneficiary's proxy identifier to the name of the beneficiary accountholder. This requires sending a request to the scheme operator, who will route the request to the beneficiary institution.

After a response has been received from the scheme, the name of the accountholder must be presented to the sender for verification. Once the sender has confirmed that the name of the beneficiary is correct, then the credit transfer can be initiated.

The proxy resolution request is made via a pair of asynchronous API operations. The implementation of the operations is described below.

Send Outbound Identifier Request

Send Request

Send an outboundIdentifierDetermination request to Electrum's /identifiers/identifier-determination endpoint.

The full message schema can be found in the API reference documentation. Code and payload samples are shown below.

curl -i -X POST \
  https://example.com/path/payments/api/v1/identifiers/outbound/identifier-determination \
  -H 'Content-Type: application/json' \
  -H 'traceparent: string' \
  -H 'tracestate: string' \
  -d '{
    "messageIdentifiers": {
      "messageIdentification": "8fd51c7124ba4819b9253e296a68e1da",
      "creationDateTime": "2022-05-04T03:02:01Z"
    },
    "schema": "IdentifierDeterminationRequest",
    "request": {
      "schema": "ZA_RPP",
      "instructedAgent": {
        "bicfi": "RY8PEG0L",
        "memberId": "AmazingBankId",
        "name": "Amazing Bank Inc",
        "branch": {
          "identification": 210514,
          "name": "ABC Plettenberg Bay",
          "address": {
            "addressType": "ADDR",
            "department": "Department of Mysteries",
            "streetName": "Street of Mysteries",
            "buildingNumber": 42,
            "buildingName": "Mysterious Building",
            "floor": 42,
            "postBox": 1024,
            "postCode": 4242,
            "townName": "Mysty Town",
            "townLocationName": "Mysty Location",
            "districtName": "Mysty District",
            "countrySubDivision": "Mysterious Cape",
            "country": "ZA",
            "addressLine": [
              "16A",
              "New market street",
              "Foreshore",
              "Cape Town",
              "ZA",
              8001
            ]
          }
        }
      },
      "instructingAgent": {
        "bicfi": "RY8PEG0L",
        "memberId": "AmazingBankId",
        "name": "Amazing Bank Inc",
        "branch": {
          "identification": 210514,
          "name": "ABC Plettenberg Bay",
          "address": {
            "addressType": "ADDR",
            "department": "Department of Mysteries",
            "streetName": "Street of Mysteries",
            "buildingNumber": 42,
            "buildingName": "Mysterious Building",
            "floor": 42,
            "postBox": 1024,
            "postCode": 4242,
            "townName": "Mysty Town",
            "townLocationName": "Mysty Location",
            "districtName": "Mysty District",
            "countrySubDivision": "Mysterious Cape",
            "country": "ZA",
            "addressLine": [
              "16A",
              "New market street",
              "Foreshore",
              "Cape Town",
              "ZA",
              8001
            ]
          }
        }
      },
      "requestor": {
        "schema": "INSTITUTION_IDENTIFICATION",
        "bicfi": "RY8PEG0L",
        "memberId": "AmazingBankId",
        "domain": "ADomain",
        "name": "Amazing Bank Inc"
      },
      "identifier": {
        "namespace": "AnotherDomain",
        "schema": "MOBILE",
        "value": "+27-0214620000"
      },
      "uetr": "f27a34ad-c5ab-4b70-a3f9-946d743eaeaa",
      "verificationIdentification": "e3360de097fe42a195cc53251d0ec839"
    },
    "supplementaryData": {
      "customData1": "My custom data 1",
      "customData2": "My custom data 2"
    }
  }'

Response

No content

Receive Acknowledgement

Electrum will respond with an HTTP 202 status if the request can be processed successfully, or an error response if a problem occurs.

Receive Identifier Information Report

Receive Outcome

Once Electrum has received a response from the scheme, the outcome is sent to you in an outboundIdentifierDeterminationReport message. The request will conform to the following schema:

messageIdentifiersobject(MessageIdentifiers)required

Holds a point-to-point unique message identification string as well as a message's creation date time.

messageIdentifiers.creationDateTimestring(date-time)required

The date and time at which the message was created, in senders local timezone or UTC. The date must be formatted as defined by date-time in RFC3339

messageIdentifiers.messageIdentificationstring<= 35 charactersrequired

A reference used to unambiguously identify the message between the sending and receiving party. Take note that this uniquely identifies a single message in a potentially multi-message exchange to complete a payment.

supplementaryDataobject(SupplementaryData)

A list of key-value pairs to support adding any supplementary/additional data to an Electrum Regulated Payments API message.

originalMessageIdentifiersobject(MessageIdentifiers)required

Holds a point-to-point unique message identification string as well as a message's creation date time.

originalMessageIdentifiers.creationDateTimestring(date-time)required

The date and time at which the message was created, in senders local timezone or UTC. The date must be formatted as defined by date-time in RFC3339

originalMessageIdentifiers.messageIdentificationstring<= 35 charactersrequired

reportobject(IdentifierDeterminationReport)required

report.schemastring(PaymentSchemeName)required

Identifies the scheme used for the payment

ZA_RTC: South African Realtime Clearing scheme.
ZA_RPP: South African Realtime Payments Platform scheme.
ZA_EFT: South African Electronic Funds Transfer scheme.
CBPR_PLUS: Cross-Border Payments and Reporting Plus.

Enum"ZA_RTC""ZA_RPP""ZA_EFT""CBPR_PLUS"

Discriminator

report.instructedAgentobject(InstitutionIdentification)

report.instructingAgentobject(InstitutionIdentification)

report.instructionForCreatorAgentArray of objects(CreditorAgentInstruction)>= 0 items

Further information related to the proxy resolution response, provided by the Operator, and intended for the creator agent.

report.originalRequestorobject(ZaRppRequestor)

report.originalUetrstring(UUID)required

The universally unique identifier provided in the original request as an end-to-end reference. This identifier remains the same for all messages related to the same transaction.

report.originalVerificationIdentificationstring[ 1 .. 35 ] charactersrequired

The request.verificationIdentification as provided in the original request.

report.reportInformationobject(ZaRppIdentificationReport)required

A report providing information from the lookup of a proxy in the context of the ZA RPP Payment Scheme.

This report returns information required to proceed with the clearing of funds through the use of the proxy (identifier) provided in the identifier determination request. Specifically, this report will provide the outcome of the lookup of said identifier, indication whether it is valid or not, as well as provide the name ("known as name") of the creditor, and the legal name of the creditor (both of these are mandatory in the ZA RPP Payment Scheme, despite not being mandatory in this API), namely:

accountOwner.knownAsName
accountOwner.legalName

report.reportInformation.accountAgentobject(InstitutionIdentification)

report.reportInformation.accountInformationobject(ZaRppAccountInformation)

report.reportInformation.accountOwnerobject(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.

report.reportInformation.outcomestringrequired

Enum"SUCCESSFUL""FAILED"

report.reportInformation.reasonCodestring[ 1 .. 4 ] characters

AB06 : Transaction stopped due to timeout at the Instructed Agent.
AB07 : Agent of message is not online. Generic usage if it cannot be determined who exactly is not online.
AB10 : An error occured at the instructed agent
AC06 : Account specified is blocked, prohibiting posting of transactions against it
AG01 : Transaction forbidden on this type of account
AG03 : Transaction type not supported/authorized on this account.
AG10 : Agent of message is suspended from the Real Time Payment system. Generic usage if it cannot be determined who exactly is suspended.
AGNT : Agent in the payment workflow is incorrect
AM02 : Specific transaction/message amount is greater than allowed maximum (e.g. payee proxy participant service limit exceeded
CH21 : Mandatory element is missing .
DT02 : Invalid creation date and time in Group Header (eg, historic date) .
DU03 : Transaction is not unique.
DUPL : Request is a duplicate of another request
FF02 : Syntax error reason is provided as narrative information in the additional reason information.
FF08 : End to End Id missing or invalid .
NAUT : Permission to be processed is not granted
NOOR : Original SCT never received
PD01 : Domain not found or invalid
PD02 : Suspended Domain provided is suspended pending investigation
BE23 : Phone number or email address, or any other proxy, used as the account proxy is unknown or invalid.
PX03 : Proxy not found in central repository
PX04 : Format of proxy invalid
RC05 : BIC identifier is invalid or missing.
RC08 : ClearingSystemMemberidentifier is invalid or missing. Generic usage if cannot specify between debit or credit account .
RR10 : Character set supplied not valid for the country and payment type.
RR12 : Invalid or missing identification required within a particular country or payment type.
RF01 : Transaction reference is not unique within the message.
AC16 : Account in Sequestration
AC17 : Account in Liquidation
AC04 : Account Closed
AC01 : Format of the account number specified is not correct
MD07 : Account Holder Deceased
NOCM : Customer account is not compliant with regulatory requirements, for example FICA (in South Africa) or any other regulatory requirements which render an account inactive for certain processing.
BE01 : Identification of end customer is not consistent with associated account number. (formerly CreditorConsistency).

report.reportInformation.transactionLimitobject(Amount)

schemastringrequired

Value"IdentifierDeterminationResponse"

Respond With An Error

If you experience an error while handling the request and are unable to submit it for asynchronous processing, then respond with an appropriate error response.

Respond With A Successful Resolution

Retrieve the resolved beneficiary name from the report.reportInformation.accountInformation.accountOwnerName field of the message and send this to the customer channel for verification. If the customer verifies that the beneficiary is correct, then proceed to initiate the credit transfer.