PayShap Outbound Identifier Determination

Important

This step only applies to the PayShap scheme.

Important

For proxy-based outbound PayShap payments, it is mandatory that you implement the identifier determination step for the processing of proxy resolution.

The identifier determination step is optional for you to implement in the case of outbound account-based PayShap payments, in which case it can be used to request account resolution from the payee bank.

Overview

The initial phase of an outbound PayShap payment involves resolving the beneficiary's proxy identifier or account number to the associated beneficiary account. 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 PayInc, the name of the accountholder must be presented to the sender for verification. Once the sender has confirmed that the known-as name of the beneficiary is correct, and the sender has selected to proceed with the payment, then the credit transfer can be initiated.

The implementation of the operations is described below.

Important

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.

Send Outbound Identifier Determination Request

Send Request

Send an outboundSynchronousIdentifierDetermination request (IdentifierDeterminationRequest schema) to Electrum's /identifiers/identifier-determination endpoint.

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

requestobject(DeterminationRequest)required

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.namespace field is required.
If the identifier schema is GENERIC, account resolution will be performed. In this case, the accountAgent.bicfi field is required.

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

request.accountAgentobject(InstitutionIdentification)

request.identifierany(ZaRppIdentifier)required

request.identifier.namespacestring[ 1 .. 40 ] characters

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

request.identifier.schemastringrequired

Indicates the schema of the identifier, e.g. MOBILE, CUSTOM.

Discriminator

request.identifier.valuestring[ 1 .. 2048 ] charactersrequired

request.instructedAgentobject(InstitutionIdentification)

request.instructingAgentobject(InstitutionIdentification)

request.requestorobject(ZaRppRequestor)

request.uetrstring(UUID)required

Universally unique identifier to provide an end-to-end reference. This identifier remains the same for all messages related to the same transaction.

request.verificationIdentificationstring[ 1 .. 35 ] charactersrequired

Unique identifier for this specific verification request.

schemastringrequired

Value"IdentifierDeterminationRequest"

Example Payload

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

The operation and message schema used are the same for both proxy resolution and account resolution; however, you must populate the message differently in each case.

For proxy resolution:
- Populate the request.identifier.schema with CUSTOM or MOBILE.
- Populate the request.identifier.namespace field.
For account resolution:
- Populate the request.identifier.schema with GENERIC.
- Populate the request.accountAgent.bicfi field.

Receive Identifier Determination Report

Receive Outcome

Once Electrum has received a response from PayInc, Electrum will forward the outcome to you in an IdentifierDeterminationResponse message.

IdentifierDeterminationResponse 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

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

A description of the reason that the identification request failed.

report.reportInformation.transactionLimitobject(Amount)

schemastringrequired

Value"IdentifierDeterminationResponse"

The message should be populated as shown in the table below.

Field	How the Field is Populated
`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. In the case of a mobile proxy that the customer has linked to their customer record, the schema is `MOBILE`. In the case of a custom proxy where a proxy is automatically assigned by the bank, the schema is `CUSTOM`.
`report.reportInformation.accountInformation.traditionalIdentifier`	The number of the account to which the proxy or account number was resolved.
`report.reportInformation.accountOwner.knownAsName`	This field is included so that it can be verified by the end-user using their banking app.
`report.reportInformation.accountOwner.legalName`	The legal name of the accountholder.
`report.reportInformation.outcome`	`SUCCESSFUL` if proxy/account resolution has passed.

Note that, if the beneficiary bank was unable to resolve the proxy or account number to a valid beneficiary account, or if any other error occurred, the response message that you will receive will include:

Field	How the Field is Populated
`report.reportInformation.outcome`	`FAILED` if proxy/account resolution has failed.
`report.reportInformation.reasonCode`	A code representing the reason for the failure.

Respond With A Successful Resolution

If the identifier determination step has yielded a successful outcome, then retrieve the resolved beneficiary name from the report.reportInformation.Owner.knownAsName 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.

PayShap Outbound Identifier Determination

Overview

Send Outbound Identifier Determination Request

Send Request

Receive Identifier Determination Report

Receive Outcome

Respond With A Successful Resolution

Was this page helpful?