Transaction Status Update

Introduced the ability to update the transactionStatus of mobile money transactions through a new API - PATCH /transactions/{transactionReference}. This supports a number of scenarios including:

  • Resolution of doubt transactions. Some mobile money providers will put transactions into ‘doubt’ where communication is interrupted. This may then require a subsequent API request from the client to inform the provider of the final outcome to the transaction.
  • Two stage transaction processing. Some systems require two steps to create a transaction:
    1. The client submits the request to the provider to create the transaction. The provider then performs necessary checks on the transaction and returns a response indicating that the transaction is pending confirmation.
    2. The client then must provide an explicit request to ‘confirm’ the transaction. Upon receiving the request, the provider will complete the transaction.

 

Bill Payment Without Bill Reference

New endpoints have been created to allow a bill payment to be accepted by a service provider without a bill reference:

  • POST /accounts/{identifierType}/{identifier}/bills/payments.
  • POST /accounts/{Account Identifiers}/bills/payments.

 

Retrieval of Bill Payments

Added new endpoints to allow API clients to retrieve a bill payment:

  • GET /accounts/{identifierType}/{identifier}/bills/{billReference}/payments.
  • GET /accounts/{Account Identifiers}/bills/{billReference}/payments.

Standard query string parameters and response headers have been included to enabled filtering of bill payments:

  • X-Records-Available-Count response header. Informs the client the number of records that can be returned.
  • X-Records-Returned-Count response header. Informs the client how many records have been returned.
  • limit query string. Used by the client to constrain the number of records returned.
  • offset query string. Used by the client to indicate the position from where records are to be returned.
  • fromdatetime query string. Used by the client to return records within a date range based on creationDate.
  • todatetime query string. Used by the client to return records within a date range based on creationDate.

 

Retrieval of Multiple Authorisation Codes

Allows multiple authorisation codes to be retrieved for a given account via the following new endpoints:

  • GET /accounts/{identifierType}/{identifier}/authorisationcodes.
  • GET /accounts/{Account Identifiers}/authorisationcodes.

Standard query string parameters and response headers have been included to enabled filtering of authorisation codes:

  • X-Records-Available-Count response header. Informs the client the number of records that can be returned.
  • X-Records-Returned-Count response header. Informs the client how many records have been returned.
  • limit query string. Used by the client to constrain the number of records returned.
  • offset query string. Used by the client to indicate the position from where records are to be returned.
  • fromdatetime query string. Used by the client to return records within a date range.
  • todatetime query string. Used by the client to return records within a date range.

Also added a ‘codestate’ filter to return authorisation codes for a given state.

 

Mobile Money Customer Account Creation

Added new endpoints and associated objects to allow account creation for mobile money customers:

  • POST /accounts/{identityType}. Allows for account creation. The identity type initially supports ‘individual’ only, but in future could be extended to support creation of other types such as ‘merchant’.
  • GET /accounts/{accountIdentifierType}/{identifier}. Allows for a specific account and associated identities to be retrieved for a given account.
  • GET /accounts/{Account Identifiers}. As per above, but supports identification of the account using one, two or three identifiers.

Mobile Money Customer Account Modification

Added new endpoints to enable the update of customer mobile money account and associated account identity information:

  • PATCH /accounts/{identifierType}/{identifier}. Allows account modification for a given account identifier/type.
  • PATCH /accounts/{Account Identifiers}. As per above, but supports identification of the account using one, two or three identifiers.
  • PATCH /accounts/{identifierType}/{identifier}/identities/{identityId}. Allows identity modification for a given account identifier/type.
  • PATCH /accounts/{Account Identifiers}/identities/{identityId}. As per above, but supports identification of the account using one, two or three identifiers.

The following fields are modifiable:

  • Account Fields
    • accountStatus
    • accountSubstatus
  • Account Identity Fields
    • identityStatus
    • kycVerificationStatus
    • kycVerificationEntity
    • kycLevel

 

Addition of Custom Data Array

Added a key/value array that can accept and return provider-specific data to all relevant endpoints:

The following objects have been modified to accept customData:

  • Transaction
  • Reversal
  • Batch Transaction
  • Batch Rejection
  • Batch Completion
  • Statement Entry
  • Bill
  • Bill Payment
  • Debit Mandate
  • Link
  • Authorisation Code
  • Quotation
  • Account

 

Debit Mandate Identification

The /debitmandates endpoints have been modified to explicitly identify the payee for a debit mandate as per the following example:

  "payee": [

    {

      "key": "msisdn",

      "value": "+33555123456"

    }

  ],

 

The payer (subject of the mandate) will always be identified in the path.

 

Apply Consistent Usage of Date Fields

Added the following missing fields to the following objects to provide consistency across objects.

Object

requestDate

creationDate

modificationDate

Batch Transaction

Add

 

Add

Bill Payment

Add

Add

Add

Link

Add

Add

Add

Authorisation Code

 

Add

Add

requestDate is optional on request and response.

creationDate is not applicable on request and optional on response.

modificationDate is not applicable on request and optional on response.

Modified all object implementations of the above fields to ensure optionality is correct and consistent across all objects/APIs.

 

Add Cursor Mechanism for Bills Retrieval

Applied standard MM API response headers and query strings on the accounts/{accountId}/bills and /accounts/{identifierType}/{identifier}/bills endpoints:

  • X-Records-Available-Count response header. Informs the client the number of records that can be returned.
  • X-Records-Returned-Count response header. Informs the client how many records have been returned.
  • limit query string. Used by the client to constrain the number of records returned.
  • offset query string. Used by the client to indicate the position from where records are to be returned.
  • fromdatetime query string. Used by the client to return records within a date range.
  • todatetime query string. Used by the client to return records within a date range.

The creationDate field has also been added to the bills object.

 

Add Country Information to Quotations

Added originCountry and receivingCountry to the Quotation object so that they can be populated when using the /quotations endpoints. receivingCountry and originCountry are optional in the request and response as they only apply to international quotations.

To clearly differentiate between the country in which the transaction originated and the country in which the sending service provider resides, created a new optional field – sendingServiceProviderCountry and added this to the Quotation Object and the International Transfer Information object.

 

Add Requesting Organisation to Transactions and Quotations

Added requestingOrganisation to all objects that can be created or updated for complete consistency. For clarity these are:

  • Transaction
  • Batch Transaction
  • Reversal
  • Quotation.
  • Link
  • Debit Mandate
  • Authorisation Code

Note that requestingOrganisation already exists on Bill Payment and is unchanged.

The new requestingOrganisation field is an object and consists of the following sub-fields:

  • requestingorganisationIdentifierType (can be swiftbic, lei, or organisationid)
  • requestingorganisationIdentifier

As a result of the inclusion of the requestingOrganisation field and also the introduction of X-Account-Holding-Institution-Identifier in v1.1, there is no longer a need for requestingLei and receivingLei fields in the transaction object. As such, these fields have been marked as deprecated for final removal in the next major release.

 

Code Lifetime Minimum Value for Authorisation Codes

Added minimum value to ensure that codeLifetime is greater than zero when supplied on /debitmandates APIs.

 

Miscellaneous Changes

  • The /transactions API has been marked as deprecated and will be removed in the next major release. Use /transactions/type/{type} instead.
  • Request and Response fields have been reordered for readability.
  • Regular expression for account identifier verification has been simplified. This change also removes issues when using a YAML parser to verify the OAS specification.
  • Reconstructed the conditionality of debitParty and creditParty in the transactions OAS objects to make correct use of the allOf and anyOf OAS keywords.
  • Added additional textual information to OAS schema fields and APIs to align with the document version more closely.