Conductor API Docs (2.3)

1. Introduction
   • Purpose
   • Overview
   • Scope
   • Audience
2. Get Started
   • Access
   • Authentication
   • Idempotency
3. Overview
   • Healthcheck
   • Product Catalog
   • Category Hierarchy
   • Accounts
   • Transactions
   • Partners
   • Create Order
4. API Workflows
   • Primitive Flow
   • Composite Flow
   • Catalog Order Transaction Flow
5. Dev Support
6. Revision History
7. API Operations
   • Healthcheck
   • Accounts
   • Transactions
   • Partners
   • Catalog & Orders

Purpose

The aim of this document is to serve as a guideline for integrating to Moment’s Conductor API.

Overview

Moment’s Conductor API describes a set of APIs that enables partners to access multiple billers and merchants for payment processing.

Scope

The scope of this document encompasses the integration into Moment’s Conductor API.

Audience

The intended audience of this document includes product, architects, analysts, developers, project managers and other pertinent stakeholders.

Access

The Conductor API offers a Sandbox and a Production instance. The Sandbox instances servers as a precursor for Production. Upon successful testing and certification in sandbox, Production access may then be requested by partners.

Authentication

The Conductor API uses a secret key to authenticate requests. Secret keys have the prefix sk_. Your secret key carries many privileges, so be sure to keep them secure. Don't share your secret key in publicly accessible areas such as GitHub, client-side code, and so forth. You can use your secret key in the following manner:

-H "Authorization: Bearer sk_RhKeWM4c1mB32CjwIdpfuqDJ"

You must make all API calls over HTTPS. Calls that you make over plain HTTP will fail. API requests without authentication will also fail.

Idempotency

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. When creating or updating an object, use an idempotency key. Then, if a connection error occurs, you can safely repeat the request without risk of creating a second object or performing the update twice.

To perform an idempotent request, provide an additional Idempotency-Key: <key> header to the request.

Conductor idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including 500 errors.

An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions. Idempotency keys can be up to 255 characters long.

Results are only saved if an API endpoint started executing. If incoming parameters failed validation, or the request conflicted with another that was executing concurrently, no idempotent result is saved because no API endpoint began execution. It is safe to retry these requests

All POST requests accept idempotency keys. Sending idempotency keys in GET and DELETE requests has no effect and should be avoided, as these requests are idempotent by definition.

For idempotent requests, the API saves the status code and body of the response of the initial request and, when the same idempotency key is used in another request, it replays the saved response. This includes error responses such as 400 and 500 errors. The following validation is also performed for idempotent requests:

• If the request parameters do not match the initial request, we will return an Unprocessable Entity error
• If the initial request is still being processed concurrently and has not yet responded, we will return a Conflicterror

When a response is replayed, an Idempotent-Replayed: true header will be attached to the response.

Idempotency keys will be removed once they are at least 24 hours old, after which a key may be reused and will be processed as an initial request and response.

Sample request:

curl --location 'https://api.momentco.net/conductor/v1/transactions' \
--header 'Authorization: Bearer sk_RhKeWM4c1mB32CjwIdpfuqDJ' \
--header 'Idempotency-Key: g6378cb0-62b0-11ee-8c99-0242ac120003' \
--header 'Content-Type: application/json' \
--data '{
   "external_reference": "jvboay10o2",
    "items": [
        {
            "id": "bill_651574c0d016708b8b37b8ab",
            "amount": {
                "currency": "ZAR",
                "value": "20"
            }
        }
    ]
}'

Healthcheck

The Health Check API enables partners to check the operating status of the Conductor APIs. It serves as a ping or polling point for conductor API entry points to confirm the accessibility of the APIs. Further information can be found in the API operations section.

Product Catalogue

The conductor API provides a product catalogue that represents the various product catalogs that a biller offers. A Biller can have a category_code associated with it which can have multiple sub-categories and products within the same. A Product can have general product properties like code, name, description and may or may not have amount_rules, quantity_rules within it. A Category can have the following properties name, description, products, categories

Category Hierarchy

Accounts

The accounts API serves to request the account details of a customer including the amount due and other associated bills. Additionally, it facilitates customer identifier verification. The API mandates authorization via header parameters, requiring the inclusion of the Retailer-Id, along with a request body. Within the request body, essential elements such as the biller_code (uniquely identifies the biller),, an identifier (uniquely identifies the customer to the biller) and a reference (uniquely identifies the biller’s product) are required. Further information can be found in the API operations section.

Transactions

The transaction APIs allow for creation, completion, cancellation and fetching of transactions. The operations under these groups of APIs include the Create Transaction, Complete Transaction, Cancel Transaction and Get transaction. Further information can be found in the API operations section.

Partners

Similar to the transaction APIs, the partner APIs offer partners the capability to create, complete, cancel and get transactions. The difference between the partner APIs and the transaction APIs, is that the partner APIs Create Transaction operation does not require items, the complete, cancel and get transaction operations use external_transaction_id instead of transaction_id. Further information can be found in the API operations section.

Create Order

The create order API enables partners to create an order based on products using the biller_code, identifier and product code. The create order API supports creating multiple orders in one API call . Further information can be found in the API operations section.

Conductor uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Conductor's servers (these are rare).

Status Code	Type	Detail
400	BAD_REQUEST	Bad request
400	INVALID_BILLER_CODE	Biller code is invalid
400	INACTIVE_BILLER_CODE	Biller is inactive.
400	INVALID_IDENTIFIER	Customer identifier is invalid.
400	INVALID_REFERENCE	Reference is invalid.
400	INVALID_EXTERNAL_REFERENCE	External reference has already been used
400	INVALID_ITEMS	One or more items are invalid
400	INVALID_AMOUNT	Amount in the request is invalid. Value should not contain non-numeric characters or negative value.
400	INVALID_CURRENCY	Currency must adhere to the standard ISO 4217 format
400	INVALID_PAGE_SIZE	Page size is invalid
400	INVALID_DEPTH	Depth is invalid
400	INVALID_CATEGORY	Category code is invalid
400	INVALID_PRODUCTS	One or more products are invalid
400	CONFLICTED_ITEMS	The bill and order cannot be processed together due to conflicting items or business rules
400	NOT_SUPPORTED	Sorry, it seems that this is not supported at the moment
400	INVALID_PAYMENT_METHOD	Payment method is invalid
400	IN_PROCESSING	Transaction is processing
400	ALREADY_COMPLETED	Transaction is already completed
400	ALREADY_CANCELLED	Transaction is already cancelled
400	ALREADY_ACCEPTED	Transaction is already accepted
400	ALREADY_REJECTED	Transaction is already rejected
401	UNAUTHORIZED	No valid Secret Key provided.
403	FORBIDDEN	The parameters were valid but the request failed.
404	NOT_FOUND	The requested resource doesn't exist.
409	CONFLICT	The request conflicts with another request (perhaps due to using the same idempotent key).
422	UNPROCESSABLE_CONTENT	The request cannot be processed due to semantic errors or invalid data
500	INTERNAL_SERVER_ERROR	Something went wrong on Conductor's end

Primitive Flow

The primitive flow describes a complex implementation that allows partners to customise and initiate transactions to Moment’s conductor API with more API calls.

Flow 1: Account_Enquiry + Create_Transactions

This primitive flow entails the initiation of an account enquiry and a create transaction with the complete.

Flow 2: Account_Enquiry + Create_Transactions + Complete_Transaction or Cancel_Transaction

Composite Flow

The composite flow describes a simpler implementation that allows partners to initiate transactions to the Moment’s conductor partner APIs with fewer API calls.

Flow 1: Create_Transactions with complete = true, payment_method and amount set

Flow 2: Create_Transactions + Complete_Transaction or Cancel_Transaction

Catalog Order Transaction Flow

The catalog and order transaction flow describes an implementation that allows partners to get product catalog information for a biller, upgrade or downgrade by creating an order against the product and submitting payment to Moment’s conductor APIs.

Flow 1: Fetch_Catalog + Create_Order + Create_Transaction

Moment supports partner development through enhanced communication and collaboration over Slack Connect.

Healthcheck APIs

Accounts APIs

Transactions APIs

Partner APIs

Catalog & Orders APIs