PayShap Inbound Identifier Determination
This step requires that you resolve a given proxy or account number to a customer bank account held at your institution, verify that the account is valid, and return certain details about the accountholder. This is to allow the payer to verify the accountholder before submitting their PayShap payment.
The proxy or account resolution step applies only to the PayShap scheme, and where the receiving participant is not making use of the Electrum Account Mirror service.
If your institution is making use of Electrum's Account Mirror, then this add-on service will process the proxy/account resolution on your behalf for all inbound requests from PayInc. Please refer to this section for more information on how to implement that solution.
It is mandatory that all banks implement the identifier determination step for inbound PayShap payments. This step enables the processing of proxy resolution or account resolution in the cases of proxy-based or account-based inbound payments, respectively.
Overview
If you are not using Electrum's Account Mirror service, then you will be required to perform the necessary proxy or account identifier functions for all inbound PayShap credit transfer requests.
When Electrum receives a request from PayInc to credit one of your customer's account, Electrum will request the following information from you:
- The accountholder name for the account linked to the given proxy or account number, so that this can be returned to the sender for verification.
- For proxy resolution only - the account number linked to the proxy, as this is required for processing of the payment itself.
The implementation of the operations is described below.
The section below describes the use of synchronous messaging for the identifier determination step between Electrum and your systems. This is generally the preferred option. As all proxy and account resolution processing with PayInc is asynchronous, Electrum provides translation capability for this step between synchronous processing with your systems and asynchronous processing with PayInc systems.
Electrum also supports asynchronous identifier determination. Speak to Electrum if you wish to implement asynchronous messaging for the identifier determination step.
Receive Inbound Identifier Determination Request
Receive Request
Electrum sends an inboundSynchronousIdentifierDetermination request to your API endpoint. The request will conform to the following schema:
IdentifierDeterminationRequest Schema
Holds a point-to-point unique message identification string as well as a message's creation date time.
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
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.
A list of key-value pairs to support adding any supplementary/additional data to an Electrum Regulated Payments API message.
A request providing information for the lookup of a proxy or account in the context of the ZA RPP Payment Scheme:
- If the identifier schema is either MOBILE or CUSTOM, proxy resolution will be performed. In this case, the
identifier.namespacefield is required. - If the identifier schema is GENERIC, account resolution will be performed. In this case, the
accountAgent.bicfifield is 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.
An identifier's namespace provides a context for the identifier to distinguish different identifiers which may have the same value but be intended to identify different accounts. For example, a bank may use the same MSISDN (identifier) with different namespaces to distinguish between a customer's cheque or savings accounts.
This may be used by the following schemes:
- ZA_RPP
Indicates the schema of the identifier, e.g. MOBILE, CUSTOM.
Universally unique identifier to provide an end-to-end reference. This identifier remains the same for all messages related to the same transaction.
Unique identifier for this specific verification request.
The operation and message schema used are the same for both proxy resolution and account resolution; however, the message will be populated differently in each case.
For proxy resolution:
- The
request.identifier.schemawill be populated withCUSTOMorMOBILE. - The
request.identifier.namespacewill be populated.
- The
For account resolution:
- The
request.identifier.schemawill be populated withGENERIC. - The
request.accountAgent.bicfiwill be populated.
- The
Send Outcome
Send Identifier Determination Report
Once you have matched the account number or proxy with the account record on your system, and verified that the account is in a valid state, then send an IdentiferDeterminationResponse to Electrum. Populate the message as shown in the table below.
IdentifierDeterminationResponse Schema
Holds a point-to-point unique message identification string as well as a message's creation date time.
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
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.
A list of key-value pairs to support adding any supplementary/additional data to an Electrum Regulated Payments API message.
Holds a point-to-point unique message identification string as well as a message's creation date time.
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
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.
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.
Further information related to the proxy resolution response, provided by the Operator, and intended for the creator agent.
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.
The request.verificationIdentification as provided in the original request.
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.knownAsNameaccountOwner.legalName
This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.
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 agentAC06: Account specified is blocked, prohibiting posting of transactions against itAG01: Transaction forbidden on this type of accountAG03: 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 incorrectAM02: Specific transaction/message amount is greater than allowed maximum (e.g. payee proxy participant service limit exceededCH21: 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 requestFF02: 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 grantedNOOR: Original SCT never receivedPD01: Domain not found or invalidPD02: Suspended Domain provided is suspended pending investigationBE23: Phone number or email address, or any other proxy, used as the account proxy is unknown or invalid.PX03: Proxy not found in central repositoryPX04: Format of proxy invalidRC05: 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 SequestrationAC17: Account in LiquidationAC04: Account ClosedAC01: Format of the account number specified is not correctMD07: Account Holder DeceasedNOCM: 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).
A description of the reason that the identification request failed.
| Field | Guidelines for Populating Field |
|---|---|
report.reportInformation.accountInformation.creationDate | The date on which the account linked to this proxy or account number was created. |
report.reportInformation.accountInformation.proxy.value (proxy resolution only) | The proxy value. This consists of a string of up to 2048 characters. |
report.reportInformation.accountInformation.proxy.schema (proxy resolution only) | The schema of the identifier.
|
report.reportInformation.accountInformation.traditionalIdentifier | The number of the account to which the proxy or account number was resolved. |
| This field is included so that it can be verified by the end-user using their banking app.
Any combination of fields available for use in this field is acceptable. |
report.reportInformation.accountOwner.legalName | The legal name of the accountholder. |
report.reportInformation.outcome | SUCCESSFUL if proxy/account resolution has passed. |
Respond With An Error
If you experience an error while handling the request and are unable to submit it for processing, then respond with an appropriate error response.