Skip to main content

Introduction to API IsSettled

IsSettled enables a network of geographically distributed financial institutions to exchange value worldwide in seconds using blockchain-based digital settlement instruments and ISO 20022 standard payment messages for real-time Clearing and settlements of international payments.

The IsSettled APIs are built on well-known REST principles and have predictable behavior. The API supports DELETE, POST, and GET requests. The API always returns a JSON-formatted response, regardless of the type of request.

The API uses HTTP as the primary protocol and is suitable for development in any programming language that can work with HTTP libraries.

ParametersDescription
headerParameters are passed in the HTTP request header.
bodyParameters are passed in the request body.
pathParameters are passed as part of the path in the URL. They are highlighted with curly braces—{}.
queryParameters are passed as URL request parameters. Are they specified after the ?.

IsSettled processes the received request immediately and returns the processing result. The response contains the HTTP response code, standard headers, and, if necessary, the response body.

The main entity of API IsSettled is an object. Each request is associated with performing a specific action on the object, for example, creating or deleting an object and obtaining information about it.

When a request is successfully processed, IsSettled returns the created, modified, or requested object in the response body or a list of objects. The parameters of the response body depend on the request.

If something is wrong with the request, then for HTTP response codes: 400, 401, 403, 404, 406, 409, and 500, the response body will be returned in JSON format with an error description.

NameTypeDescriptionRequired
build_versionstringService build version.
No
codestringError code.
No
endpoint_urlstringURL of the endpoint that failed with an error.
No
long_messagestringDetailed error description.
Yes
member_identificationstringMember Identifier. Example: bankName.
No
service_namestringService name.
No
short_messagestringShort error description.
Yes
timestampnumber (int64)Event timestamp. Example: 1651224866578.
Yes
troubleshooting_idstringIdentifier indicating the error source.
No

Authentication

One must use an OAuth token and pass it with each request to authenticate requests.

curl https://us.bankname.payments.issettled.com/client/v1/api/digital-accounts \
-H "Authorization: Bearer <OAuth-token>"

To use IsSettled features, a User must request permission to receive an OAuth token from a User-Member with Administrator Access Rights.

The User-Member creates API access tokens with Administrator Access Rights in the Web Office interface.

Get an Access Token

Step 1. Log in to the Web Office

A User-Member with Administrator Access Rights must log in to the client portal.

Step 2. Create a User

User-Member with Administrator Access Rights should go to the “User Management” section and create a new User with the Access Rights Viewer or Manager.

Step 3. Create a JWT OAuth token

User-Member with Administrator Access Rights should go to “Access Token Management” and create a new OAuth token for a User with the Access Rights of a Viewer or Manager.

To create a JWT must specify the following parameters:

  • Member Identifier in IsSettled if the organization has multiple Deployed Member Nodes.
  • Digital Account Identifiers for which access will be allowed.
  • Allowed IP addresses from which the User can make requests.
  • Permitted Endpoints to which the User will be allowed access.

The Access Token session is 24 hours, so the User-Member with Administrator Access Rights must create a new Access Token.

A User-Member with Viewer or Manager Access Rights must update the Access Token every fifteen minutes or sooner by calling /oauth-token/refresh endpoint; otherwise, the Token is automatically revoked.

Page last updated: 17 January 2024