Electrum Regulated Payments Partner API (26.1.1)

The Electrum Regulated Payments API is an asynchronous API that allows partners to participate in various nationally regulated payment schemes.

As the Regulated Payments API is asynchronous, partners have a choice of how to integrate with Electrum:

Webhooks: Electrum will send events to the partner containing inbound payments to action, or responses to outbound payment requests. Webhooks are defined in the Electrum Regulated Payments Partner API.
Partner API: Electrum will call operations exposed by the partner containing inbound payments to action, or responses to outbound payment requests. The operations are defined in this document.

Receiving transactional events via webhooks or API are equivalent, except that it may be more familiar or convenient to implement one style or the other.

This document describes the operations a partner must implement for Electrum to consume in order to complete the integration with the Electrum Regulated Payments API.

Download OpenAPI description

elpapi-partner.json

elpapi-partner.yaml

Overview

URL

https://electrum.co.za

Electrum Support

support@electrum.co.za

Servers

Partner API sandbox

https://example.com/path/payments/partner-api/v1/

transactional

Operations that participate in transaction processing, which may or may not have financial impact.

Operations

financial

Operations that participate in transaction processing and have financial impact.

Operations

credit-transfer

Operations related to credit transfer transactions.

Operations

direct-debit

Operations related to direct debit transactions.

Operations

payment-return

Operations related to payment returns.

Operations

identifier-determination

Operations used to retrieve additional information related to an identifier

Operations

funds-management

Operations related to the management of funds, including reservations, postings, and voiding of reservations.

Operations

risk-assessment

Operations related to the assessment and identification of risk in transactions.

Operations

fraud-assessment

Operations related to the processing of fraud assessments for payment transactions.

Operations

account-management

Operations that involve customer account information.

Operations

sanctions-assessment

Operations related to the processing of sanctions assessment for payment transactions.

Operations

mandate-management

Operations related to the lifecycle management of direct debit mandates.

Operations

Schema

MandateSuspensionReason

Provides details about the reason for a mandate suspension.

Field Usage Guidelines: reason: For South African Mandate Schemes the reason for the suspension is specified as one of the below PROPRIETARY values:

CTAM - Contract Amended.
CTCA - Contract Cancellation Initiated by Debtor.
CTEX - Contract Expired.
MCFC - Mandate Suspended - Final Collection.
MCOC - Mandate Suspended - Once off Collection.
MSUC - Mandate Suspended after seven consecutive unsuccessful Collections.
MASC - Mandate Suspended - Account not in a state for Collections.
MADO - Mandate suspended due to no collection for a period.

additionalInformationArray of strings

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

reasonobject(MandateSuspensionReasonChoice)required

Specifies the reason for the suspension request of a mandate.

reason.schemastringrequired

Identifies the value as being a pre-defined code. Always CODE.

Discriminator

reason.valuestringrequired

CTAM - Contract Amended.
CTCA - Contract Cancellation Initiated by Debtor.
CTEX - Contract Expired.
MCFC - Mandate Suspended - Final Collection.
MCOC - Mandate Suspended - Once off Collection.
MSUC - Mandate Suspended after seven consecutive unsuccessful Collections.

Enum"CTAM""CTCA""CTEX""MCFC""MCOC""MSUC"

{
  "additionalInformation": [
    "string"
  ],
  "originator": {
    "address": { … },
    "contactDetails": { … },
    "countryOfResidence": "string",
    "identification": { … },
    "knownAsName": "string",
    "legalName": "string"
  },
  "reason": {
    "schema": "string",
    "value": "CTAM"
  }
}

MandateSuspensionRequestIdentification

Suspension Request Identification A unique transaction identifier used to unambiguously identify the mandate suspension request to the clearing house.

Important: Usage of suspensionRequestIdentification**.

If the client is the host of the mandate register and is the source of truth for mandate state the client is required to always populate the suspensionRequestIdentification in the MandateSuspensionRequest. The format is validated and the provided suspensionRequestIdentification is used by Electrum.
If Electrum is the source of truth for mandate state the suspensionRequestIdentification should not be provided by the client when initiating new mandate suspension; Electrum will generate a compliant suspensionRequestIdentification automatically which will be echoed back to the client.

Lifecycle behaviour:

Mandate Suspension Request: The originating bank creates a new, unique suspensionRequestIdentification for the suspension request. If not provided by the client, Electrum generates one automatically.
Customer Payment Status Report: The suspensionRequestIdentification is echoed in CustomerPaymentStatusReports that confirm the outcome of a mandate suspension.

Structure (29 characters): The identifier is composed of 4 components separated by forward slashes (/), matching the pattern STP/<BankCode>/<Date>/<Sequence>:

Prefix (STP): Fixed string indicating a Suspension.
Bank Code (4 numeric): The 4-digit identifier of the initiating bank.
Date (10 alphanumeric): The date the suspension is generated in YYYY-MM-DD format.
Sequence Number (9 numeric): Mandate Suspension sequence number. Must be unique within the bank and date.

string(MandateSuspensionRequestIdentification)<= 35 characters^STP/\d{4}/20\d{2}-\d{2}-\d{2}/\d{9}$

Suspension Request Identification A unique transaction identifier used to unambiguously identify the mandate suspension request to the clearing house.

Important: Usage of suspensionRequestIdentification**.

If the client is the host of the mandate register and is the source of truth for mandate state the client is required to always populate the suspensionRequestIdentification in the MandateSuspensionRequest. The format is validated and the provided suspensionRequestIdentification is used by Electrum.
If Electrum is the source of truth for mandate state the suspensionRequestIdentification should not be provided by the client when initiating new mandate suspension; Electrum will generate a compliant suspensionRequestIdentification automatically which will be echoed back to the client.

Lifecycle behaviour:

Mandate Suspension Request: The originating bank creates a new, unique suspensionRequestIdentification for the suspension request. If not provided by the client, Electrum generates one automatically.
Customer Payment Status Report: The suspensionRequestIdentification is echoed in CustomerPaymentStatusReports that confirm the outcome of a mandate suspension.

Structure (29 characters): The identifier is composed of 4 components separated by forward slashes (/), matching the pattern STP/<BankCode>/<Date>/<Sequence>:

Prefix (STP): Fixed string indicating a Suspension.
Bank Code (4 numeric): The 4-digit identifier of the initiating bank.
Date (10 alphanumeric): The date the suspension is generated in YYYY-MM-DD format.
Sequence Number (9 numeric): Mandate Suspension sequence number. Must be unique within the bank and date.

"string"

UnderlyingSuspensionDetails

Contains the details of the mandate suspension including the reason and original mandate reference.

originalMandateobject(OriginalMandateReference)required

Reference to an original mandate. The partner may identify the mandate using any of the following identifiers, depending on the context of the request and the information available. At least one of originalMandateIdentification for the original mandate, or originalMandate must be provided.

For mandate amendment, cancellation and suspension requests, originalMandate is required and the originalMandateIdentification cannot be used as the sole reference.

originalMandate.originalMandateobject(Mandate)

Core mandate data structure containing all the details of a direct debit mandate.

originalMandate.originalMandateIdentificationstring<= 35 characters

Unique identification to unambiguously identify the original mandate. Can be the mandateIdentification as assigned by the creditor or the mandate reference number as assigned by the debtor agent

suspensionReasonobject(MandateSuspensionReason)required

Provides details about the reason for a mandate suspension.

Field Usage Guidelines: reason: For South African Mandate Schemes the reason for the suspension is specified as one of the below PROPRIETARY values:

CTAM - Contract Amended.
CTCA - Contract Cancellation Initiated by Debtor.
CTEX - Contract Expired.
MCFC - Mandate Suspended - Final Collection.
MCOC - Mandate Suspended - Once off Collection.
MSUC - Mandate Suspended after seven consecutive unsuccessful Collections.
MASC - Mandate Suspended - Account not in a state for Collections.
MADO - Mandate suspended due to no collection for a period.

suspensionReason.additionalInformationArray of strings

suspensionReason.originatorobject(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.

suspensionReason.reasonobject(MandateSuspensionReasonChoice)required

Specifies the reason for the suspension request of a mandate.

suspensionReason.reason.schemastringrequired

Identifies the value as being a pre-defined code. Always CODE.

Discriminator

suspensionReason.reason.valuestringrequired

CTAM - Contract Amended.
CTCA - Contract Cancellation Initiated by Debtor.
CTEX - Contract Expired.
MCFC - Mandate Suspended - Final Collection.
MCOC - Mandate Suspended - Once off Collection.
MSUC - Mandate Suspended after seven consecutive unsuccessful Collections.

Enum"CTAM""CTCA""CTEX""MCFC""MCOC""MSUC"

suspensionRequestIdentificationstring(MandateSuspensionRequestIdentification)<= 35 characters^STP/\d{4}/20\d{2}-\d{2}-\d{2}/\d{9}$

Suspension Request Identification A unique transaction identifier used to unambiguously identify the mandate suspension request to the clearing house.

Important: Usage of suspensionRequestIdentification**.

If the client is the host of the mandate register and is the source of truth for mandate state the client is required to always populate the suspensionRequestIdentification in the MandateSuspensionRequest. The format is validated and the provided suspensionRequestIdentification is used by Electrum.
If Electrum is the source of truth for mandate state the suspensionRequestIdentification should not be provided by the client when initiating new mandate suspension; Electrum will generate a compliant suspensionRequestIdentification automatically which will be echoed back to the client.

Lifecycle behaviour:

Mandate Suspension Request: The originating bank creates a new, unique suspensionRequestIdentification for the suspension request. If not provided by the client, Electrum generates one automatically.
Customer Payment Status Report: The suspensionRequestIdentification is echoed in CustomerPaymentStatusReports that confirm the outcome of a mandate suspension.

Structure (29 characters): The identifier is composed of 4 components separated by forward slashes (/), matching the pattern STP/<BankCode>/<Date>/<Sequence>:

Prefix (STP): Fixed string indicating a Suspension.
Bank Code (4 numeric): The 4-digit identifier of the initiating bank.
Date (10 alphanumeric): The date the suspension is generated in YYYY-MM-DD format.
Sequence Number (9 numeric): Mandate Suspension sequence number. Must be unique within the bank and date.

{
  "originalMandate": {
    "originalMandate": { … },
    "originalMandateIdentification": "string"
  },
  "suspensionReason": {
    "additionalInformation": [ … ],
    "originator": { … },
    "reason": { … }
  },
  "suspensionRequestIdentification": "string"
}

operational

Operations

bulk

Operations

request-to-pay

Operations

refund

Operations

account-verification

Operations