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.

application/json

{"messageIdentifiers": {"messageIdentification": "8fd51c7124ba4819b9253e296a68e1da",
"creationDateTime": "2022-05-04T03:02:01Z"
},
"schema": "IdentifierDeterminationRequest",
"request": {"schema": "ZA_RPP_PROXY_IDENTIFIER_DETERMINATION",
"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"
}
}

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:

Request Body schema: application/json

required	object (MessageIdentifiers) Holds a point-to-point unique message identification string as well as a message's creation date time.
	object (SupplementaryData) A list of key-value pairs to support adding any supplementary/additional data to an Electrum Regulated Payments API message.
required	object (MessageIdentifiers) Holds a point-to-point unique message identification string as well as a message's creation date time.
required	object (IdentifierDeterminationReport)
schema required	string Value: "IdentifierDeterminationResponse"

application/json

{"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_PROXY_IDENTIFIER_REPORT",
"reportInformation": {"outcome": "SUCCESSFUL",
"transactionLimit": {"value": 3000,
"currency": "ZAR"
},
"accountInformation": {"proxy": {"schema": "MOBILE",
"value": "+27-812456789"
},
"creationDate": "2021-01-01T09:55:45.015708Z"
},
"accountOwner": {"knownAsName": "Shaun",
"legalName": "Shaun John Smith"
}
},
"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
]
}
}
},
"originalRequestor": {"schema": "INSTITUTION_IDENTIFICATION",
"bicfi": "RY8PEG0L",
"memberId": "AmazingBankId",
"domain": "ADomain",
"name": "Amazing Bank Inc"
}
},
"supplementaryData": {"customData1": "My custom data 1",
"customData2": "My custom data 2"
}
}

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.