The Payment Hub API is designed based on the ISO 20022 messaging definitions to capture and process payments and perform related functions. It supports a host of functions where the client could be playing the role of a debtor agent or a creditor agent. The Payment Hub API supports the following payment rails.

Overview

Requests are authenticated using the api_key which is shared with clients at the time of client on-boarding. Clients can only invoke those APIs based on the permissions assigned to the api_key

The HTTP Authorization request header is used to provide authentication information. This header looks like the following.

Authorization : OPAY1-HMAC-SHA256 Credential=...,Signature=...

The constituents of the authorization header are explained in the table below.

Signature Calculation

Signature is calculated as follows.

Base64(HMAC-SHA256(secret,input))

The calculation is explained in detail below.

The string input is computed as follows.

input = method():path():queryString():headers():payload()

Each of the substrings is explained below.

HTTP Response Codes The Payment Hub API uses the standard HTTP response codes to return the status of an API call. An HTTP response code of 2xx indicates success. An HTTP response code of 4xx indicates a client error. An HTTP response code of 5xx indicates a processing error. In these cases, the API returns a list of errors wrapped in the admi.002.001.001 message.

Error Codes

Each error in the list has a code, message, and specifics on which field the error pertains to (if applicable). In addition to these details, it can also have a list of inner errors that caused this error, on the lines of an Exception Stack trace.

Below table specifies the Error category and Error code.

          // format
          <Errors>
            <error>
                  <code>HUB-10-132544</code>
                  <message>Invalid Field<message>
            </error>
            <error>
                  <code>HUB-10-120824</code>
                  <message>Empty Field<message>
            </error>
          </Erros>

The Payment Hub API supports idempotency for the HTTP methods POST, PUT, DELETE and PATCH using the header parameter, namely, idempotent_request_key. In other words, any POST, PUT, DELETE and PATCH request will be considered as a duplicate request or retry and not reprocessed by the API if all the request parameters, including the path and query parameters, the request headers and the request body, match with an earlier request. In case of duplicate requests or retries, the API response will be that of the original request. The idempotent_request_key is valid only for a duration of one hour from the time of the original request. Any duplicate request or retries after a gap of one hour from the original request will be considered as a fresh request.

Point-to-point reference, as assigned by the instructing party, and sent to the next party in the chain to unambiguously identify the message. The instructing party must make sure that MessageIdentification is unique per instructed party for a pre-agreed period.

Below is the format used to generate the Message Id:

Format:

Below code snippet to generate UUID for 22 characters:

UUID uuid = UUID.randomUUID();
// Create byte[] for base64 from uuid
byte[] src = ByteBuffer.wrap(new byte[16])
        .putLong(uuid.getMostSignificantBits())
        .putLong(uuid.getLeastSignificantBits())
        .array();

String uuidInBase64UrlSafe = null;
uuidInBase64UrlSafe = Base64.getUrlEncoder().encodeToString(src);
if (uuidInBase64UrlSafe.length() < 22) {
    StringUtils.rightPad(uuidInBase64UrlSafe, 22, "=");
}
uuidInBase64UrlSafe = uuidInBase64UrlSafe.substring(0, 22);

Every API call should include the following request headers to define the context in which the API is invoked.

HTTP header parameters are returned as part of every API response. Most of these parameters match those sent in the request. Every API call has the following response headers.

The user service level offered by Payment Hub API includes payment options for instant, urgent, and regular response times. The fulfillment service level offered by Payment Hub API includes options for real-time payments, card payments with Visa, ACH, and ACH Sameday. These service levels are used to ensure seamless and efficient transaction handling. Payment Hub API accepts the service levels given below.