RocketKOR

Introduction

Authentication

Sorting and Pagination

Errors

Introduction

This API reference provides detailed documentation for the RocketKOR REST APIs. Our APIs use standard HTTP request methods (such as GET, PUT, POST, and DELETE) and standard HTTP response codes for errors along with detailed error messaging. Requests and responses follow the standard JSON format.

Authentication

All RocketKOR API operations are performed over HTTPS. RocketKOR uses Bearer Authentication to authenticate requests. All API calls are performed by a Service Account and must include an Authorization header with your RocketKOR access token as a Bearer Token.

To obtain an access token, first request an API key. Your API key is associated with a RocketKOR Service Account. Once you receive your API key, invoke the POST /v1/api-keys/exchange endpoint to exchange your API key and secret for an access token. You must pass your API key and API secret as a Basic Authorization header (Base64-encoded). For example:

Authorization: Basic encodedString

where encodedString is your <api-key>:<api-secret> string encoded using Base64 encoding.

If the request is successful, the following fields will be returned:

  • access_token  Access token.
  • expires_in  Access token expiry time (in seconds).

Sorting and Pagination

Sorting and pagination are supported for most RocketKOR APIs that return arrays of resources. You can control sorting and pagination through URL query parameters.

Sorting Query Parameters

Use the sort parameter to specify a sort field and an optional sort order (ASC or DESC). For example, the following parameters would sort the results by two fields: first the createdAt field in descending order, then the title field in ascending order.

GET {endpoint}?sort=createdAt,DESC&sort=title,ASC

Pagination Query Parameters

Use the page (page number to return) and size (maximum number of results to return per page) parameters to limit the number of results and keep responses to a reasonable size. For example, to return the first 10 records on the first page, use page=0 and size=10.

The response includes paging information followed by the content array. The following fields are returned:

totalElements  Total number of available elements.
totalPages  Total number of available pages.
number  Page number returned.
numberOfElements  Number of elements returned.
hasNext  Whether additional elements are available after this set.
content  Array of JSON objects, such as accounts or transactions, for the requested page number.

For example:

				
					{
  "totalElements": 10,
  "totalPages": 1,
  "number": 1,
  "numberOfElements": 10,
  "hasNext": true,
  "content": [
    {
      "id": "6a017f06-83a3-44b7-be6f-5e5cae4a9ed7",
      "businessAccountId": "8th32z87-3845-9810-v7gu-1f827g98swk3",
      "businessRefId": "RECIP001",
      "firstName": "John",
      "middleName": "",
      "lastName": "Smith",
      "secondLastName": "",
      "email": "jsmith@xyz.com",
      "phoneNumber": "4161234567",
      "nationality": "Canadian",
      "dateOfBirth": "1970-07-08",
      "additionalInformation": "",
      "recipientType": "INDIVIDUAL",
      "businessName": "",
      "state": "ACTIVE",
      "createdAt": "2021-07-08T20:56:35.219Z",
      "updatedAt": "2021-07-08T20:56:35.219Z",
      "requestorId": "9kj43t32-2956-2886-x7dy-6r821w39kra3"
    },
    {...},
    {...}
  ]
}
				
			

Errors

HTTP Response Codes

In addition to detailed error messaging, RocketKOR uses standard HTTP response codes to indicate the status of a request. In general, codes can indicate a successful response (2xx range), a failed response due to the content or structure of the request, business validation errors, or request conflicts (4xx range), or a failed response due to an error on the RocketKOR server (5xx range). Most failed responses fall in the 4xx range due to missing/incorrect request parameters or invalid authentication information.

Common HTTP response codes include:

200 OK  The request was successful and a response body was returned.

201 Created  The request was successful and resulted in the creation of a resource.

204 No content  The request was successful but did not return a response body.

400 Bad Request  The request could not be processed due to an invalid structure or missing/incorrect information (for example, a required parameter is missing).

403 Unauthorized  The caller doesn’t have the required permissions to perform the request.

404 Not Found  The requested resource doesn’t exist.

409 Conflict  The request conflicts with a previous request. For example, the provided idempotency key was already used for another request.

422 Unprocessable Entity  The request failed due to business reasons, such as a business validation failure (account limit exceeded, etc).

429 Too many requests  The client has exceeded the API call rate limit.

500 Internal Server Error  The server encountered an unexpected condition that prevented it from fulfilling the request.

503 Service Unavailable  A service is temporary off-line. The request can be retried after a short interval.

Error Messages

RocketKOR error messages use the following structure:

				
					{
  "timestamp": DateTime,
  "traceId": DateTime,
  "error": String,
  "message": String
}
				
			

timestamp  Date and time the error occurred.

traceID  ID used to trace the error. This value can be submitted to RocketKOR Support to help identify the problem.

error  RocketKOR error code. For details, see the next section, “Error Codes”.

message  Description of the error.

Error Codes

The following error codes are used to identify the type of error.

unexpected-system-error  An unexpected system error has occured. The request can be retried.

financial-account-not-found  The Financial Account ID does not exist.

financial-account-inactive  The Financial Account ID is not active.

non-sufficient-funds  The Debit Financial Account does not have sufficient funds for the transaction.

txn-no-provider  The Debit Financial Account for a transaction is not linked to a Provider.

not-allowed  The provided value is not supported.

invalid  The provided value is not valid.