Electrum Regulated Payments API (34.1.0)

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

This document describes the operations exposed by Electrum for partners to consume in order to initiate outbound or respond to inbound payments.

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 this document.
  • 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 the Electrum Regulated Payments Partner API.

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. Partners may request the method of communication Electrum should use when selecting which payment schemes to participate in.

Download OpenAPI description
Overview
Languages
Servers
Payments API sandbox

https://example.com/path/payments/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

payment-cancellation

Operations related to the cancellation of prior payment instructions.

Operations

account-management

Operations that involve customer account information.

Operations

proxy

Operations that involve the management or processing of proxies

Operations

scheme-inquiry

Operations that are related to retrieving information from industry for a particular scheme.

Operations

identifier-determination

Operations used to retrieve additional information related to an identifier

Operations

identifier-verification

Operations used to verify information relating to an account identifier

Operations

request-to-pay

Operations which pertain to a request for payment from a creditor to a debtor

Operations

funds-management

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

Operations

refund

Operations related to the refund of a prior successful financial transaction.

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

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

MandateClassification

schemastringrequired

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

Discriminator
valuestring(ExternalMandateClassificationCode)required

Classification of the mandate based on how the collection amount is determined. In the ZA_AC scheme this is the mandate's Debit Value Type, and it dictates strict interbank validation rules for how collection amounts are calculated, capped, and adjusted over the life of the mandate.

The rules for each value are:

  • FIXE (Fixed): Used for contracts where an upfront, calculated Instalment Amount is the basis for normal collections. Regular collections are strictly validated and cannot exceed this Instalment Amount. The Adjustment Category (adjustment.category) for a fixed mandate must strictly be NEVR (Never).
  • VARI (Variable): Used for contracts where an upfront Instalment Amount is calculated but can be amended by the Creditor based on pre-agreed variables, such as annual increases or interest rate changes. Regular collections cannot exceed the currently active Instalment Amount.
  • USGB (Usage-based): Used for contracts where the collection amount fluctuates depending on the Payer's usage of a product or service during the payment cycle. Unlike fixed and variable mandates, the regular Instalment Amount (collectionAmount) is optional, and interbank validation is instead performed strictly against a mandatory Maximum Collection Amount (maximumAmount).
Enum"FIXE""USGB""VARI"
{ "schema": "CODE", "value": "FIXE" }

MandateTypeInformation

Provides details on the type of mandate.

categoryPurposeobject(CategoryPurpose)
classificationobject(MandateClassification)
localInstrumentobject(LocalInstrumentType)
serviceLevelobject(ServiceLevel)
{ "categoryPurpose": { "schema": "string", "value": "BONU" }, "classification": { "schema": "string", "value": "FIXE" }, "localInstrument": { "schema": "string", "value": "0000" }, "serviceLevel": { "schema": "string", "value": "BKTR" } }

Mandate

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

adjustmentobject(MandateAdjustmentRules)

Defines adjustment rules for mandate amounts.

authenticationobject(MandateAuthentication)

Identifies the specific mechanism or channel that the Paying Bank (Debtor Bank) uses to communicate with the Payer (Debtor) to obtain their authorisation for a mandate. This field may be missing on mandate initiation/amendment and should be populated by the debtor bank upon acceptance of the mandate

collectionAmountobject(Amount)
creditorobject(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.

creditorAccountobject(PaymentAccount)

Representation of an account for payment purposes. Note that at least one of identification or proxy is expected to be present.

creditorAgentobject(InstitutionIdentification)
creditorSchemeIdentificationobject(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.

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

debtorAccountobject(PaymentAccount)

Representation of an account for payment purposes. Note that at least one of identification or proxy is expected to be present.

debtorAgentobject(InstitutionIdentification)
firstCollectionAmountobject(Amount)
mandateIdentificationstring<= 35 characters

Unique identification of the mandate, as assigned by the creditor. This field is used strictly by the Creditor for their own internal referencing and may be used to link collections to their related mandate. This is required for mandate initiations and cancellations.

mandateRequestIdentificationstring<= 35 characters

Unique identification of the mandate request, as assigned by the creditor to the debtor when the underlying contract is concluded between the two parties. This field represents the Contract Reference Number. It appears on the debtor's bank statement to help them identify the deductions. The Contract Reference must remain unchanged for the entire duration of the mandate, even in the event of cession or assignment. It can only be amended if no AC Payment Instruction has ever been presented against the Payer's account. This field is required for mandate initiations and mandate cancellations.

mandateStatusobject(MandateStatus)

Current status of a mandate.

maximumAmountobject(Amount)
occurrencesobject(MandateOccurrences)

Defines the frequency and duration of mandate collections.

reasonobject(MandateReason)

Specifies the reason for a mandate action (amendment, cancellation, rejection).

referredDocumentArray of objects(ReferredDocument)

Provides information to identify the underlying documents associated with the mandate

trackingIndicatorboolean

Indicates whether the mandate permits tracking for future collection instructions. Its exact meaning and relevance depend strictly on the mandate-management operation being performed:

1. Mandate Initiation & Amendment Requests

  • Required: Specifies whether tracking capabilities are permitted (true) or revoked (false) for future collections against this mandate.

2. Mandate Cancellation Requests

  • Required: Acts specifically as a Tracking Cancellation Indicator to manage collections that are already in-flight.
    • true: Instructs the clearing house to immediately cancel any active tracking records currently in the tracking queue for this mandate.
    • false: Instructs the clearing house NOT to cancel records in tracking, allowing them to finish their tracking cycle despite the mandate being cancelled.

3. Mandate Acceptance Reports

  • Required: Echoes the definitive tracking setting (true or false) that was successfully saved to the Debtor Bank's Mandate Register.

4. Mandate Suspensions & Information Requests

  • Not Applicable: This field is ignored for lookup and suspension operations.
typeobject(MandateTypeInformation)

Provides details on the type of mandate.

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

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

{ "adjustment": { "adjustmentAmount": { … }, "adjustmentRate": 0.1, "category": { … }, "dateAdjustmentRuleIndicator": true }, "authentication": { "channel": { … }, "date": "2019-08-24", "messageAuthenticationCode": "string" }, "collectionAmount": { "currency": "string", "value": 0.1 }, "creditor": { "address": { … }, "contactDetails": { … }, "countryOfResidence": "string", "identification": { … }, "knownAsName": "string", "legalName": "string" }, "creditorAccount": { "currency": "string", "identification": { … }, "name": "string", "proxy": { … }, "type": { … } }, "creditorAgent": { "additionalIdentifications": [ … ], "address": { … }, "bicfi": "string", "branch": { … }, "clearingSystemMemberId": { … }, "companyRegistration": "string", "lei": "string", "memberId": "string", "name": "string" }, "creditorSchemeIdentification": { "address": { … }, "contactDetails": { … }, "countryOfResidence": "string", "identification": { … }, "knownAsName": "string", "legalName": "string" }, "debtor": { "address": { … }, "contactDetails": { … }, "countryOfResidence": "string", "identification": { … }, "knownAsName": "string", "legalName": "string" }, "debtorAccount": { "currency": "string", "identification": { … }, "name": "string", "proxy": { … }, "type": { … } }, "debtorAgent": { "additionalIdentifications": [ … ], "address": { … }, "bicfi": "string", "branch": { … }, "clearingSystemMemberId": { … }, "companyRegistration": "string", "lei": "string", "memberId": "string", "name": "string" }, "firstCollectionAmount": { "currency": "string", "value": 0.1 }, "mandateIdentification": "string", "mandateRequestIdentification": "string", "mandateStatus": { "schema": "string", "value": "ACTV" }, "maximumAmount": { "currency": "string", "value": 0.1 }, "occurrences": { "finalCollectionDate": "2019-08-24", "firstCollectionDate": "2019-08-24", "frequency": { … }, "sequenceType": "FRST", "validFrom": "2019-08-24", "validTo": "2019-08-24" }, "reason": { "schema": "string", "value": "AC01" }, "referredDocument": [ { … } ], "trackingIndicator": true, "type": { "categoryPurpose": { … }, "classification": { … }, "localInstrument": { … }, "serviceLevel": { … } }, "ultimateCreditor": { "address": { … }, "contactDetails": { … }, "countryOfResidence": "string", "identification": { … }, "knownAsName": "string", "legalName": "string" }, "ultimateDebtor": { "address": { … }, "contactDetails": { … }, "countryOfResidence": "string", "identification": { … }, "knownAsName": "string", "legalName": "string" } }

operational

Operations

bulk

Operations

accounts

Operations

account-verification

Operations