NAV Navbar

What is Omnigate OS

The Omnigate OS is a modular financial operating system offering a high-precision ledger, allowing you to accept and issue payments, and create and manage online wallets each containing multiple fiat, crypto and custom currencies. It's made to enable integration of many banking, blockchain and exchange networks such as SWIFT, Bitcoin, Ripple and Stellar, and payment gateways such as Stripe and Braintree, facilitating account reconciliation, payments, exchanges and conversions. Doing so, it creates a unified way to communicate with many 3rd party services without having to implement each on their own. The OS also offers an Application Programming Interface (API) providing you with a standardized way to operate with the platform and all of its 3rd party integrations.

Written for professionals who want to incorporate all of the platform or some of it's modules, the following guide will explain the core concepts of the Omnigate OS and help you with the it's installation and operation.

Key Concepts

Modular Architecture

To give you the most flexibility, the Omnigate OS is divided in mutliple modules each controlling a portion of the possible platform operations so they can be implement independently. The following chart details the various Omnigate modules.

Chart explaining modules and relationship

Ledger Module & Financial Operations

The Ledger Module (Omnibridge) is an asset tracker. It processes deposits and withdrawals, and manages the internal bookkeeping and reconciliation with the external accounts. Through the help of bridges, it can integrate external accounts such as bank accounts, digital wallets, exchanges and your own sources under the same unified ledger in real-time.

Ledger

The Omnigate OS uses an internal ledger to track all incoming and outgoing transactions for any currency (fiat, crypto and custom currencies). Usually, regular accounting ledgers aren't precise enough for crypto-currencies but ours is a high precision ledger which can support a precision of up to 8 decimal places (and more if need be).

This module supports the 3 basic financial operations: deposit, withdraw and transfer. Keep in mind that all financial operations work for both fiat and crypto currencies.

Deposit

Deposit operations are for money entering an Omnigate OS.

Withdraw

Withdraw operations are for money leaving an Omnigate OS.

Transfer

Transfer operations are for moving money internally between wallets in an Omnigate OS.

The Ledger Module synchronizes wallets balances in real-time with external accounts through the bridges. The wallets are also used for reconciliation with the transaction history of the external accounts.

Freeze & Unfreeze (coming soon)

Bridges

Bridges are pieces of software meant to act as gateways between the Omnigate OS and external networks (i.e. bank accounts, crypto wallets, exchanges, etc.). They are the source of truth of what happens on all external accounts by tracking the transactions and updating the Ledger accordingly. Note that the bridges are used during deposit and withdraw operations only.

Wallets

A Wallet is a logical container for currencies. Each wallet belongs to a profile and contains the balances for an unlimited number of currencies. Also, multiple wallets may belong to a same profile. A wallet contains one balance per currency and each balance is comprised of a total amount which is divided between an available amount and a held amount.

Trading Wallets

Trading wallets are normal wallets which can include bridge currencies. They are used for balance reconciliation with the trading history. To use the trading wallets, you need to also integrate the exchange and conversion module.

Currencies

Whether it is fiat currency (CAD, USD, etc.) or crypto-currency (Bitcoin, Litecoin, etc.), the Omnigate OS organize currencies in 3 types:

Currency Type Description
Base Base currencies represent an internal asset directly controlled by the platform
Extended Extended currencies represent currencies with a counterparty
Bridge Bridge currencies represent currencies that are tied to particular network

Fees (coming soon)

Payment Module

The payment module (Omnipay) is built to handle all types of payments through the use of payment requests. The payment request is a universal mean to request a payment from another end-user using any payment method such as an internal wallet, Ripple, Bitcoin or any integrated 3rd party services like Stripe or Braintree. A common use of the payment module is to integrate with any shopping cart like WooCommerce and Magento.

Recurring Payments (coming soon)

Refunds (coming soon)

Payment Status Codes

Name Value Description
Waiting payment 0 The payment request was just created and we are waiting for the client to pay
Paid 1 This payment request has been paid
Partial amount 2 This payment request has been paid partially (not supported now)
Timeout 3 The payment request was not paid at all, or was not paid in the required amount of time (30 minutes), or was partially paid
Canceled 4 Cancelled by the user (not supported now)
Refunded 5 (not supported now)
Error 7 A technical error occurred
Declined 8 The payment request was declined

Authentication Module

To communicate with the Omnigate OS, an end-user, an application or another module needs to authenticate through our Authentication module (Omnipass). This module acts as an OAuth2 consumer and provider, and issues session tokens following the JWT standard.

To add a layer of security, this module also offers multi-factor authentication (MFA).

OAuth2

OAuth 2.0 is an authorization framework used to grant limited access to an HTTP service, such as Facebook, Google, or the Omnigate OS API. It works by delegating user authentication to the service that hosts the user account and authorizing third-party applications to access the user account on its behalf.

JWT

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.

MFA

Multi-factor Authentication (MFA) is a method of confirming a user's claimed identity in which an end-user is granted access only after successfully presenting two or more pieces of evidence (or factors) to our authentication module: either something the end-user and only the end-user has and/or knows and/or is.

Example of a user and its default profile

{
    "uuid": "uuid_1234567812345678",
    "email": "john@email.com",
    "mfaenabled": false,
    "language": "en",
    "status": "active",
    "defaultprofile": {
        "upid": "upid_8765432112345678",
        "type": "individual",
        "status": "active",
        "tierlevel": 0,
        "roles": [
            "profile-admin"
        ],
        "profile": {
            "birthday": "1978-03-02",
            "firstname": "John",
            "lastname": "Smith",
            "email": "john@email.com",
            "phone": "(555) 555-5555",
            "address1": "123 Main Street",
            "address2": "#404",
            "city": "Montreal",
            "region": "QC",
            "country": "CA",
            "postalcode": "H3H 3H3"
        }
    }
}

Users & Profiles

In the Omnigate OS,

Users represent a set of credentials in the form of username and password, a language for display and communication and, possibly, a two-factor authentication token (MFA). Also, a user is mapped to one or multiple profiles along with a set of roles.

Profiles represent a moral entity either an individual or an organization. They contain details like the full name, the address, the phone number, tier level (related to KYC) and they are associated with a fee schedule which will determine service fees for this particular account. Through their profile, an end-user owns one or multiple wallets.

Roles and Rights

For further flexibility and security, we implemented a role based access control (RBAC) system so that, any user account, if given the right role, can access and/or modify another account's information (profile, wallet, etc.).

A right is a permission to perform a specific operation like reading, editing or creating information (profile, wallet, etc).

A role consists in a group of rights. Multiple roles may be assigned to a user account.

We store the role(s) in the mapping between the user and the profile so that each of them is limited by one or multiple roles. For example, an end-user has every rights on his own personal profile (profile-admin role) and, as a support agent for a client, the same end-user could have permission to view the transactions and balances of a profile's wallet (agent-rw role). See the roles and rights list for the full list.

KYC Module (coming soon)

The Know-Your-Customer (KYC) module manages customer identification, enabling compliance with regulations and the law. The module also allows you to define multiple transactional limits (tiers), to integrate data vaults for automated Personnal Identification Information (PII) storage facilitating PCI compliance and to integrate manual and automated verification processes, all this according to your requirements.

Exchange and Conversion Module

The exchange and conversion module (Omnibroker) is made to connect with exchange networks such as Ripple or Stellar. With this module, you can create trading orders, currency conversion orders and track value differences for arbitrage.

Installation

Prerequisites

Before installing the Omnigate OS, you need to setup a machine with the following requirements:

Get started

Download installation script

wget https://download.omnigate.com/install.sh

Verify script content

cat install.sh

Run installation script

bash install.sh

Once your Red Hat machine is ready:

1. Connect to your Red Hat machine and download, verify and run the installation script.

Install Omnigate OS using the cURL command Omnigate OS installation is complete

Open the installation wizard in the browser

chrome https://{your machine's domain or IP address}

2. Once the Omnigate OS is installed, open your favorite browser and access your Red Hat machine's domain or IP address using HTTPS to continue with the installation wizard.

3. Read and accept the End User License Agreement.
4. Select your preferred country and timezone for your Omnigate OS.
5. Select an environment name (Production, Staging, Development or Workstation) or define your own. The environment name is an internal representation for this Omnigate OS installation.
6. Set up your SSL certificate according to the installation wizard.

Certificate Signing Request creation screen

SSL certificate upload screen

7. Define your informations for the evaluation license.
8. Define your email to receive notifications.
9. Select the location of your database.

Location  Description
Local Your database is hosted on the same Red Hat machine as your Omnigate OS installation
Remote Your database is hosted elsewhere

9.1. If you are using a remote database, define the configuration details according to the installation wizard.

Remote DB setup screen

10. Define your SMTP settings according to the installation wizard so the Omnigate OS can send you email for notifications, for example.

SMTP setup screen

11. If you are using a local database, define the database password of the database administrator.

12. Define the password for platform administrator (by default the administrator's username is admin@omnigate.local).

13. Verify the provided information before finishing the installation and starting the platform setup

14. Once the installation is completed, copy the installation details in a safe place.

Screen to show installation completion

15. Start Omnigate configuration.

16. Define the issuer name for the platform.

Screen to set issuer name

Once the configuration is complete, you will be automatically redirected to the login screen.

Add nodes to your cluster (coming soon)

API Operations

Profile

Resource URL

POST /api/{version}/profile

Sample

POST https://test.example.com/api/v1/profile

CreateProfile

Access Type: Write
Rate Limited: Yes

POST /profile

Create a new profile

Example Request

{
    "type": "individual",
    "email": "john@email.com",
    "registeruser": true,
    "password": "Mypassword$0",
    "timezone": "Canada/Eastern",
    "firstname": "John",
    "lastname": "Smith",
    "extended": {
        "key1": "value",
        "key2": "value"
    }
}

{
    "type": "organization",
    "email": "acme@email.com",
    "registeruser": true,
    "password": "Mypassword$0",
    "timezone": "Canada/Eastern",
    "organizationname": "ACME corp.",
    "adminfirstname": "John",
    "adminlastname": "Smith",
    "extended": {
        "key1": "value",
        "key2": "value"
    }
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
type x Profile type "individual" or "organization" String 10 12
email x Email address linked to the profile Valid email address String 6 60
registeruser If true, will register a new user with the same email for the profile true or false Boolean
subprofile If true will create the new profile as subprofile of the current one true or false Boolean
system If true will create the new profile as a system profile. Only superuser can create system profiles. true or false Boolean
callbackurl Required if "registeruser" is true Valid url String 10 100
password Password for the new user, ignored if "registeruser" is set to false String containing at least one of each lowercase, uppercase, numerical and special symbol String 8 16
language Language for the new user, ignored if "registeruser" is set to false Two letters language code String 2 2
timezone IANA time zone database identifier, ignored if "registeruser" is false Valid tzdata zone from /usr/share/zoneinfo/ (e.g. "Canada/Eastern") String 10 30
emailvalidation If false, email address will not be validated. (defaults to true) This is useful when authenticating with 3rd party providers as the email address in most cases has already been validated. This parameter is limited to internalapp-* roles. true or false Boolean
phone Phone number Valid phone number String 7 20
address1 Address String 1 40
address2 Address String 1 40
city City String 1 30
region Region String 1 30
country Country code String 2 2
postalcode Postal code String 1 15
* Any valid profile attributes in respect to profile type Specific to the attribute
extended Any valid extended attributes. Refer to GetProfileExtendedAttributeList for the complete list of attributes JSON 2 20000

Individual profile type attribute list

Name Required Description Accepted values Type Min length Max length
firstname x First name String 1 30
lastname x Last name String 1 30
birthday Birthday YYYY-MM-DD (ISO 8601) String 10 10

Organization profile type attribute list

Name Required Description Accepted values Type Min length Max length
organizationname x Organization Name String 1 30
adminfirstname x Administrator first name String 1 30
adminlastname x Administrator last name String 1 30
industry Industry String 1 25
registrationid Registration ID String 1 30

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "upid": "upid_1234567812345678"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
upid Profile ID, present on success String
uuid User ID, Present on success if "registeruser" is true String

Additional behavior information

Resource URL

GET /api/{version}/profile
GET /api/{version}/profile/{upid}
GET /api/{version}/profile/{usertoken}
GET /api/{version}/profile/{apikey}

Sample

GET https://test.example.com/api/v1/profile/
GET https://test.example.com/api/v1/profile/upid_1234567812345678
GET https://test.example.com/api/v1/profile/usertoken_380595C6B590BD27C1349428D3DD61A6
GET https://test.example.com/api/v1/profile/apikey_380595C6B590BD27C1349428D3DD61A6

Example Request

GET https://test.example.com/api/v1/profile

GetProfile

Access Type: Read
Rate Limited: Yes

GET /profile

Get the profile associated with the access token or API key which made the request. If you have the appropriate rights, you may also retrieve a profile either by profile ID (upid), by user token or by API key.

Example Response for individual profile type

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "upid": "upid_1234567812345678",
    "type": "individual",
    "status": "active",
    "akid":"akid_1234567812345678",
    "tierlevel": 2,
    "roles": [
        "profile-ro",
        "merchant-ro"
    ],
    "profile": {
        "firstname": "John",
        "lastname": "Smith",
        "email": "john@email.com",
        "address1": "275 Rue Notre-Dame Est",
        "address2": "apt.332",
        "city": "Montreal",
        "region": "QC",
        "country": "CA",
        "postalcode": "H2Y 1C6",
        "phone": "(514) 555-2823",
        "birthday": "1950-07-23"
    },
    "version": 2
}

Example Response for organization profile type

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "upid": "upid_1234567812345678",
    "type": "organization",
    "status": "active",
    "akid":"akid_1234567812345678",
    "tierlevel": 2,
    "roles": [
        "profile-ro",
        "merchant-ro"
    ],
    "profile": {
        "adminfirstname": "John",
        "adminlastname": "Smith",
        "adminemail": "john@acme.com",
        "organizationname": "Acme Corp.",
        "address1": "333 boul. René-Lévesque Ouest",
        "address2": "",
        "city": "Montreal",
        "region": "QC",
        "country": "CA",
        "postalcode": "H2Z 3V8",
        "phone": "(514) 555-4372",
        "industry": "Financial",
        "registrationid": "23587293578124"
    },
    "version": 2
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
type Profile type String
upid Profile ID String
masteruuid User ID the profile is assigned to String
parentupid Profile ID of the parent, only present if profile is a subprofile String
version Version number of this profile Number
roles Roles assigned to current API key/token and profile combination Array
profile Profile object JSON
status Profile status, can be either active or inactive String
akid APIkey ID of the APIkey used for this call String
tierlevel Profile tier level Number
fsid Fee Schedule ID, only present if fsid is set String
internal Internal attributes object JSON
extended Extended attributes object. Refer to GetProfileExtendedAttributeList for the complete list of attributes JSON

profile Object Properties

Name Description Type
address1 Address Line 1 String
address2 Address Line 2 String
city City String
region Region String
country Country String
postalcode Postal Code String
phone Phone number String

profile Object Properties specific to individual profile type

Name Description Type
email Email String
firstname First name String
lastname Last name String
birthday Date of birth String

profile Object Properties specific to organization profile type

Name Description Type
adminemail Admin's email String
adminfirstname Admin's first name String
adminlastname Admin's last name String
organizationname Organization name String
industry Industry type String
registrationid Registration ID String

Example of Internal Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "upid": "upid_1234567812345678",
    "type": "individual",
    "tierlevel": 2,
    "status": "active",
    "akid":"akid_1234567812345678",
    "roles": [
        "profile-ro",
        "merchant-ro"
    ],
    "profile": {
        "firstname": "John",
        "lastname": "Smith",
        "email": "john@email.com",
        "address1": "275 Rue Notre-Dame Est",
        "address2": "",
        "city": "Montreal",
        "region": "QC",
        "country": "CA",
        "postalcode": "H2Y 1C6",
        "birthday": "1950-07-23"
    },
    "version": 2,
    "internal": {
        "omnibridgesetting1": "somevalue"
    },
    "extended":{
        "somesetting": "somevalue"
    }
}

Additional Internal Response Parameters

Name Description Type
internal Used by internal apps to store Omnibridge and Omnipay application data JSON
extended Used to store profile settings JSON

Resource URL

POST /api/{version}/profile/update

Sample

POST https://test.example.com/api/v1/profile/update

UpdateProfile

Access Type: Write
Rate Limited: Yes

POST /profile/update

Update a profile

Example Request

{
    "upid": "upid_1234567812345678",
    "firstname": "John",
    "lastname": "Smith",
    "extended": {
        "key1": "value",
        "key2": "value"
    }
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
upid x Profile ID Valid profile ID String 21 21
phone Phone number Valid phone number String 7 20
address1 Address String 1 40
address2 Address String 1 40
city City String 1 30
region Region String 1 30
country Country code String 2 2
postalcode Postal code String 1 15
* Any valid profile attributes in respect to profile type Specific to the attribute
extended Any valid extended attributes. Refer to GetProfileExtendedAttributeList for the complete list of attributes JSON 2 20000

Individual profile type attribute list

Name Required Description Accepted values Type Min length Max length
firstname First name String 1 30
lastname Last name String 1 30
email Email address Valid email address String 6 60
birthday Birthday YYYY-MM-DD (ISO 8601) String 10 10

Organization profile type attribute list

Name Required Description Accepted values Type Min length Max length
organizationname Organization Name String 1 30
adminfirstname Administrator first name String 1 30
adminlastname Administrator last name String 1 30
adminemail Administrator email address Valid email address String 6 60
industry Industry String 1 25
registrationid Registration ID String 1 30

Example Response

{
  "resultcode": 10000,
  "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Resource URL

POST /api/{version}/profile/team/user

Sample

POST https://test.example.com/api/v1/profile/team/user

AddTeamUser

Access Type: Write
Rate Limited: Yes

POST /profile/team/user

Add team member to default (or specific) profile

Example Request

{
    "callbackurl": "https://localhost/register/set-password",
    "email": "john@email.com",
    "language": "fr",
    "roles": [
        "profile-ro",
        "merchant-ro"
    ]
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
email x Email address of the user Valid email address String 6 60
roles x Roles assigned to the user Array of strings Array 1 20
callbackurl x Redirection url to the set password page Valid url String 10 100
upid If present will create a user and a mapping for child profile Valid upid String 21 21
language Language for the new user Two letters language code String 2 2

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "upid": "upid_8765432187654321",
    "uuid": "uuid_1234567812345678"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
upid Profile ID, present on success String
uuid User ID, Present on success String

Resource URL

GET /api/{version}/profile/team
GET /api/{version}/profile/{upid}/team

Sample

GET https://test.example.com/api/v1/profile/team
GET https://test.example.com/api/v1/profile/upid_1234567812345678/team
GET https://test.example.com/api/v1/profile/team
GET https://test.example.com/api/v1/profile/upid_1234567812345678/team

GetTeamList

Access Type: Read
Rate Limited: Yes

GET /profile/team

Get team members for default (or specific) profile

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "team": [
        {
            "uuid": "uuid_1234567812345678",
            "email": "john@email.com",
            "roles": [
                "profile-rw",
                "merchant-rw"
            ]
        },
        {
            "uuid": "uuid_2234567812345678",
            "email": "steve@email.com",
            "roles": [
                "profile-ro",
                "merchant-ro"
            ]
        }
    ]
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
team Collection of team member objects Array

team member Object Parameters

Name Description Type
uuid User ID String
email User email address String
roles Roles assigned to the user Array

Resource URL

POST /api/{version}/profile/team/user/update

Sample

POST https://test.example.com/api/v1/profile/team/user/update

UpdateTeamUser

Access Type: Write
Rate Limited: Yes

POST /profile/team/user/update

Update team members from default (or specific) profile

Example Request

{
    "email": "john@email.com",
    "roles": [
        "profile-ro",
        "merchant-ro"
    ],
    "upid": "upid_1234567812345678"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
email x Email address of the user Valid email address String 6 60
roles x Roles assigned to the user Array of strings Array 1 20
upid If present will check child profile's user mapping Valid upid String 21 21

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}
Response Parameters
Name Description Type
resultcode Result code Number
resultmessage Result message String

Resource URL

DELETE /api/{version}/profile/team/{uuid}
DELETE /api/{version}/profile/{upid}/team/{uuid}

Sample

DELETE https://test.example.com/api/v1/profile/team/uuid_1234567812345678
DELETE https://test.example.com/api/v1/profile/upid_1234567812345678/team/uuid_2234567812345678

Example Request

DELETE https://test.example.com/api/v1/profile/team/uuid_1234567812345678

DeleteTeamUser

Access Type: Write
Rate Limited: Yes

DELETE /profile/{upid}/team/{uuid}

Delete a team user from default (or specific) profile

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Resource URL

POST /api/{version}/profile/apikey

Sample

POST https://test.example.com/api/v1/profile/apikey

CreateAPIKey

Access Type: Write
Rate Limited: Yes

POST /profile/apikey

Generate a new API key for default (or specific) profile

Example Request

{
    "description": "Development",
    "roles": [
        "merchant-rw",
        "profile-rw"
    ]
}
{
    "description": "customer ewallet access",
    "upid": "upid_1234567812345678",
    "roles": [
        "ewallet-ro"
    ]
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
description x Description of the API key String 2 40
roles x Collection of roles associated with the API key Array of strings Array 1 20
upid If present will create a API key mapping for child profile Valid upid String 21 21

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "upid": "upid_1234567812345678",
    "akid": "akid_1234567812345678",
    "apikey": "D85E4D788BB61CE3F429C8C7997BD3D1"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
upid User Profile ID String
akid API key ID String
apikey API key String

Resource URL

GET /api/{version}/profile/apikey
GET /api/{version}/profile/{upid}/apikey

Sample

GET https://test.example.com/api/v1/profile/apikey
GET https://test.example.com/api/v1/profile/upid_1234567812345678/apikey

Example Request

GET https://test.example.com/api/v1/profile/apikey
GET https://test.example.com/api/v1/profile/upid_1234567812345678/apikey

GetAPIKeyList

Access Type: Read
Rate Limited: Yes

GET /profile/apikey

Get the list of API keys for default (or specific) profile

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "apikeylist": [
        {
            "akid": "akid_1234567812345678",
            "apikey": "****************************D3D1",
            "description": "Development",
            "roles": [
                "profile-rw"
            ]
        },
        {
            "akid": "akid_2234567812345678",
            "apikey": "****************************B491",
            "description": "Production",
            "roles": [
                "profile-rw"
            ]
        }
    ]
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
apikeylist Collection of API key objects Array

API key Object Properties

Name Description Type
akid API key ID String
apikey API key (Obfuscated) String
description Description field of API key String
roles Roles associated with API key Array

Resource URL

DELETE /api/{version}/profile/apikey/{akid}
DELETE /api/{version}/profile/{upid}/apikey/{akid}

Sample

DELETE https://test.example.com/api/v1/profile/apikey/akid_1234567812345678
DELETE https://test.example.com/api/v1/profile/upid_1234567812345678/apikey/akid_2234567812345678

Example Request

DELETE https://test.example.com/api/v1/profile/apikey/akid_1234567812345678

DeleteAPIKey

Access Type: Write
Rate Limited: Yes

DELETE /profile/apikey/{akid}

Delete API key from default (or specific) profile

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Resource URL

GET /api/{version}/profile/extendedattributelist

Sample

GET https://test.example.com/api/v1/profile/extendedattributelist

Example Request

GET https://test.example.com/api/v1/profile/extendedattributelist

GetProfileExtendedAttributeList

Access Type: Read
Rate Limited: Yes

GET /profile/extendedattributelist

Get a list of profile extended attributes

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "extendedattributelist": [
        {
            "name": "walletnotificationenabled",
            "type": "boolean",
            "label": "Wallet notification enabled"
        },
        {
            "name": "paymentnotificationenabled",
            "type": "boolean",
            "label": "Payment notification enabled"
        },
        {
            "name": "merchantnotificationurl",
            "type": "string",
            "label": "Merchant notification URL"
        },
        {
            "name": "merchantcallbackuser",
            "type": "string",
            "label": "Merchant callback username"
        },
        {
            "name": "merchantcallbackpassword",
            "type": "string",
            "label": "Merchant callback password",
            "flags": ["mask"]
        },
        {
            "name": "merchantacceptedcurrencylist",
            "type": "array",
            "label": "Merchant accepted currency list"
        },
        {
            "name": "merchantpaymentprocessor",
            "type": "string",
            "label": "Merchant Payment Processor"
        },
        {
            "name": "issuername",
            "type": "string",
            "label": "Issuer name",
            "flags": ["worm"]
        },
        {
            "name": "candowithdraw",
            "type": "boolean",
            "label": "Can do withdraw"
        },
        {
            "name": "rippleissueraddress",
            "type": "string",
            "label": "Ripple issuer address",
            "flags": ["worm"]
        },
        {
            "name": "stellarissueraddress",
            "type": "string",
            "label": "Stellar issuer address",
            "flags": ["worm"]
        },
        {
            "name": "rippleprofileaddress",
            "type": "string",
            "label": "Ripple profile address",
            "flags": ["worm"]
        },
        {
            "name": "stellarprofileaddress",
            "type": "string",
            "label": "Stellar profile address",
            "flags": ["worm"]
        },
        {
            "name": "notificationsettings",
            "type": "object",
            "label": "Notification settings"
        },
        {
            "name": "mobileappnamewallet",
            "type": "string",
            "label": "Mobile application name"
        },
        {
            "name": "mobileappnameterminal",
            "type": "string",
            "label": "Mobile application name"
        },
        {
            "name": "paymentprocessorname",
            "type": "string",
            "label": "Name of the payment processor"
        },
        {
            "name": "paymentprocessorsecret",
            "type": "string",
            "label": "Merchant Payment Processor secret API Key"
        },
        {
            "name": "paymentprocessorpublic",
            "type": "string",
            "label": "Merchant Payment Processor public Key"
        },
        {
            "name": "paymentprocessorid",
            "type": "string",
            "label": "Merchant Payment Processor identifier"
        },
        {
            "name": "customattribute1",
            "type": "string",
            "label": "Custom Attribute",
            "priority": 10
        }
    ]
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
extendedattributelist List of attribute objects Array

attribute Object Properties

Name Description Type
name System name of the attribute String
type Data type of the attribute String
label Human readable name String
flags Possible flags: worm, mask Array
priority Number used to determine to position among other attributes Number

Default Attributes

Name Type Description
candowithdraw Boolean Can this profile do withdraws or not
issuername String Appended to custom currencies during creation
merchantacceptedcurrencylist Array List of currencies accepted by the merchant
merchantcallbackpassword String The callback password associated to the callback URL
merchantcallbackuser String The callback user associated to the callback URL
merchantnotificationurl String This is the callback URL of the merchant. We send wallet notifications to this address.
merchantpaymentprocessor String The name of the payment processor associated with this merchant
mobileappnameterminal String Name of the POS application
mobileappnamewallet String Name of the mobile wallet application
notificationsettings JSON JSON data
paymentnotificationenabled Boolean If true, send the payment notification to the merchant.
paymentprocessorid String Payment processor ID
paymentprocessorname String Payment processor name
paymentprocessorpublic String Payment processor public value
paymentprocessorsecret String Payment processor secret value
rippleissueraddress String Ripple address to issue IOU associated with this account
rippleprofileaddress String Ripple address to issue IOUs
stellarissueraddress String Stellar address to issue IOU associated with this account
stellarprofileaddress String Stellar address to issue IOUs
walletnotificationenabled Boolean If true, send the wallet event notification to the "merchantnotificationurl".

Resource URL

POST /api/{version}/notifications/transports

Sample

POST https://test.example.com/api/v1/notifications/transports

SetNotificationTransport

Access Type: Write
Rate Limited: Yes

POST /notifications/transports

Add a new transport to a UPID/AKID or UPID/UUID pair

Example Request for Mobile Transport

{
    "upid": "upid_1234567812345678",
    "akid": "akid_1234567812345678",
    "transporttype": "mobile",
    "deviceid": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
    "transport": {
        "platform": "iOS",
        "name": "John's iPhone",
        "eventlist": [
            "deposit",
            "withdraw",
            "transfer"
        ]
    }
}

Example Request for HTTP Transport

{
    "upid": "upid_2234567812345678",
    "uuid": "uuid_2234567812345678",
    "transporttype": "http",
    "transport": {
        "url": "https://remote-host:8081/callback",
        "eventlist": [
            "deposit",
            "withdraw",
            "transfer"
        ]
    }
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
upid x Universal Profile ID Valid profile ID String 21 21
uuid Universal User ID Valid user ID String 21 21
akid API Key ID Valid API key ID String 21 21
transporttype x Transport Type Either mobile or http String 4 6
deviceid Device Universal Unique ID. Required when transporttype is mobile String 1 200
transport x transport object JSON 2 20000

transport Object Properties for Mobile

Name Required Description Accepted values Type Min length Max length
platform Mobile platform (iOS, Android, etc.) String 1 20
name User friendly name to help identify the device (e.g., John's iPhone) String 1 30
eventlist List of events to subscribe to Array 0 200

transport Object Properties for HTTP

Name Required Description Accepted values Type Min length Max length
url Remote URL String 10 100
eventlist List of events to subscribe to Array 0 200

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "ntid": "ntid_1234567812345678"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
ntid Notification transport ID String

Resource URL

GET /api/{version}/notifications/transports/{upid}

Sample

GET https://test.example.com/api/v1/notifications/transports/upid_1234567812345678

Example Request

GET https://test.example.com/api/v1/notifications/transports/upid_1234567812345678

GetAllNotificationTransports

Access Type: Read
Rate Limited: Yes

GET /notifications/transports/{upid}

Get a list of transports for all UPID/AKID and UPID/UUID pairs by UPID

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "results": [
        {
            "type": "akid",
            "akid": "akid_1234567812345678",
            "transportlist": [
                {
                    "ntid": "ntid_1234567812345678",
                    "transporttype": "mobile",
                    "deviceid": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
                    "transport": {
                        "platform": "ios",
                        "name": "John's iPhone",
                        "eventlist": [
                            "deposit",
                            "withdraw"
                        ]
                    }
                },
                {
                    "ntid": "ntid_2234567812345678",
                    "transporttype": "http",
                    "transport": {
                        "url": "https://127.0.0.1:8932/callback",
                        "eventlist": [
                            "deposit",
                            "withdraw"
                        ]
                    }
                }
            ]
        },
        {
            "type": "uuid",
            "uuid": "uuid_3234567812345678",
            "transportlist": [ ... ]
        }
    ]
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
results Results Array

results Object Properties

Name Description Type
type Transport list type (either uuid or akid) String
uuid Universal User ID (only present when type is uuid) String
akid API key ID (only present when type is akid) String
transportlist List of available transportlist objects Array

transportlist Object Properties

Name Description Type
ntid Notification transport ID String
transporttype Type of notification transport (Either mobile or http) String
deviceid Device ID (only present when transporttype is mobile) String
transport transport object JSON

transport Object Properties for Mobile

Name Description Type
platform Mobile platform (iOS, Android, etc.) String
name User friendly name to help identify the device (e.g., John's iPhone) String
eventlist List of events to subscribe to Array

transport Object Properties for HTTP

Name Description Type
url Remote URL String
eventlist List of events to subscribe to Array

Resource URL

GET /api/{version}/notifications/transports/{upid}/{uuid}
GET /api/{version}/notifications/transports/{upid}/{akid}

Sample

GET https://test.example.com/api/v1/notifications/transports/upid_1234567812345678/uuid_2234567812345678
GET https://test.example.com/api/v1/notifications/transports/upid_1234567812345678/akid_2234567812345678

Example Request

GET https://test.example.com/api/v1/notifications/transports/upid_1234567812345678/uuid_2234567812345678
GET https://test.example.com/api/v1/notifications/transports/upid_1234567812345678/akid_2234567812345678

GetNotificationTransports

Access Type: Read
Rate Limited: Yes

GET /notifications/transports/{upid}/{uuid}
GET /notifications/transports/{upid}/{akid}

Get a list of transports for a specific UPID/AKID or UPID/UUID pair

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "results": [
        {
            "type": "akid",
            "akid": "akid_12345678",
            "transportlist": [
                {
                    "ntid": "ntid_1234567812345678",
                    "transporttype": "mobile",
                    "deviceid": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
                    "transport": {
                        "platform": "ios",
                        "name": "John's iPhone",
                        "eventlist": [
                            "deposit",
                            "withdraw"
                        ]
                    }
                },
                {
                    "ntid": "ntid_2234567812345678",
                    "transporttype": "http",
                    "transport": {
                        "url": "https://127.0.0.1:8932/callback",
                        "eventlist": [
                            "deposit",
                            "withdraw"
                        ]
                    }
                }
            ]
        }
    ]
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
results Results Array

results Object Properties

Name Description Type
type Transport list type (either uuid or akid) String
uuid Universal User ID (only present when type is uuid) String
akid API key ID (only present when type is akid) String
transportlist List of available transportlist objects Array

transportlist Object Properties

Name Description Type
ntid Notification transport ID String
transporttype Type of notification transport (Either mobile or http) String
deviceid Device ID (only present when transporttype is mobile) String
transport transport object JSON

transport Object Properties for Mobile

Name Description Type
platform Mobile platform (iOS, Android, etc.) String
name User friendly name to help identify the device (e.g., John's iPhone) String
eventlist List of events to subscribe to Array

transport Object Properties for HTTP

Name Description Type
url Remote URL String
eventlist List of events to subscribe to Array

Resource URL

POST /api/{version}/notifications/transports/update

Sample

POST https://test.example.com/api/v1/notifications/transports/update

UpdateNotificationTransport

Access Type: Write
Rate Limited: Yes

POST /notifications/transports/update

Update a notification transport using a NTID

Example Request for Mobile Transport

{
    "ntid": "ntid_1234567812345678",
    "transport": {
        "platform": "iOS",
        "name": "John's iPhone",
        "eventlist": [
            "deposit",
            "withdraw",
            "transfer"
        ]
    }
}

Example Request for HTTP Transport

{
    "ntid": "ntid_8765432112345678",
    "transport": {
        "platform": "https://remote-host:8081/callback",
        "eventlist": [
            "deposit",
            "withdraw",
            "transfer"
        ]
    }
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
ntid Notification Transport ID String 21 21
transport Transport JSON 2 20000

Transport Properties for Mobile

Name Required Description Accepted values Type Min length Max length
platform Mobile platform (iOS, Android, etc.) String 1 20
name User friendly name to help identify the device (e.g., John's iPhone) String 1 30
eventlist List of events to subscribe to Array 0 200

Transport Properties for HTTP

Name Required Description Accepted values Type Min length Max length
url Remote URL String 10 100
eventlist List of events to subscribe to Array 0 200

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Resource URL

DELETE /api/{version}/notifications/transports/{deviceid}
DELETE /api/{version}/notifications/transports/{ntid}

Sample

DELETE https://test.example.com/api/v1/notifications/transports/da39a3ee5e6b4b0d3255bfef95601890afd80709
DELETE https://test.example.com/api/v1/notifications/transports/ntid_1234567812345678

Example Request

DELETE https://test.example.com/api/v1/notifications/transports/da39a3ee5e6b4b0d3255bfef95601890afd80709
DELETE https://test.example.com/api/v1/notifications/transports/ntid_1234567812345678

DeleteNotificationTransport

Access Type: Write
Rate Limited: Yes

DELETE /notifications/transports/{deviceid}
DELETE /notifications/transports/{ntid}

Delete a notification transport

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Resource URL

POST /api/{version}/system/profile/update

Sample

POST https://test.example.com/api/v1/system/profile/update

UpdateSystemProfile

Access Type: Write
Rate Limited: Yes

POST /system/profile/update

Update the status of a specific profile

Example Request

{
    "upid": "upid_1234567812345678",
    "status": "active"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
upid x Universal Profile ID Valid profile ID String 21 21
status x Profile status Either active or inactive String 6 8

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

User

Resource URL

POST /api/{version}/user/email

Sample

POST https://test.example.com/api/v1/user/email

ChangeUserEmail

Access Type: Write
Rate Limited: Yes

POST /user/email

Change user email address

Example Request

{
    "email": "jdoe@email.com",
    "newemail": "jdoe@acme.com",
    "password": "Mypassword$0",
    "mfa": "123456"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
email x Current email address Valid email address String 6 60
newemail x New email address Valid email address String 6 60
password x User password Valid password String 8 16
mfa Multi-factor authentication code, if enabled 6 digits mfa code String 6 6

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Description

Changes the email address for currently logged in user.
If a profile exists with the masteruser set it to the current user email, it should also change that profile's email
If another user already exists with the new email, the request should fail
If a non-child profile exists with the new email, the request should fail
If a profile exists with masteruser value equal to the new email, the request should fail
User must click the confirmation link in email before change is active

Resource URL

POST /api/{version}/user/password

Sample

POST https://test.example.com/api/v1/user/password

ChangeUserPassword

Access Type: Write
Rate Limited: Yes

POST /user/password

Change password for a user

Example Request

{
    "email": "john@email.com",
    "password": "Mypassword$0",
    "newpassword": "Newpassword$0"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
email x Email address of the user Valid email address String 6 60
password x Current password. Required only when reset password token is not set Valid password String 8 16
newpassword x New password String containing at least one of each lowercase, uppercase and special symbol String 8 16
mfacode Multi-factor authentication code 6 digits mfa code String 6 6
token Reset password token Valid reset password token String 32 32

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Resource URL

POST /api/{version}/user/resetpassword

Sample

POST https://test.example.com/api/v1/user/resetpassword

ResetUserPassword

Access Type: Write
Rate Limited: Yes

POST /user/resetpassword

Reset user password
This call will create a password reset token and send it via email, this token can be used once to change the password to a new one

Example Request

{
    "email": "john@email.com",
    "callbackurl": "https://<hostname>:port/callbackservlet"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
email x Email address of the user Valid email address String 6 60
callbackurl x The url where the client will be redirected (in the email message) https://hostname:port/callbackservlet String 10 60

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Resource URL

GET /api/{version}/user/mfa/status

Sample

GET https://test.example.com/api/v1/user/mfa/status

Example Request

GET https://test.example.com/api/v1/user/mfa/status

GetUserMFAStatus

Access Type: Read
Rate Limited: Yes

GET /user/mfa/status

Get multi factor authentication security status

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "mfaenabled": false
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
mefaenabled MFA status Boolean

Resource URL

POST /api/{version}/user/mfa/enable

Sample

POST https://test.example.com/api/v1/user/mfa/enable

EnableUserMFA

Access Type: Write
Rate Limited: Yes

POST /user/mfa/enable

Enable multi-factor authentication for a personal profile

Example Request

{
    "email": "john@email.com",
    "password": "Mypassword$0",
    "mfacode": "613027"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
email x Email address linked to the profile Valid email address String 6 60
password x Current password Valid password String 8 16
mfacode x MFA code, obtained after entering the seed in the application Valid MFA code String 6 6

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Resource URL

GET /api/{version}/user/mfa/seed

Sample

GET https://test.example.com/api/v1/user/mfa/seed

Example Request

GET https://test.example.com/api/v1/user/mfa/seed

GetUserMFASeed

Access Type: Read
Rate Limited: Yes

GET /user/mfa/seed

Get a new MFA seed

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "mfaseed": "K5JARNEQW2RQIMAM",
    "servicename": "john",
    "useridentifier": "email.com"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
mfaseed MFA activation seed String
servicename Name of service, used for QR Code creation String
useridentifier User indentifier, used for QR Code creation String

Resource URL

POST /api/{version}/user/mfa/disable

Sample

POST https://test.example.com/api/v1/user/mfa/disable

DisableUserMFA

Access Type: Write
Rate Limited: Yes

POST /user/mfa/disable

Disable multi-factor authentication from a profile

Example Request

{
    "password": "Mypassword$0",
    "mfacode": "613027"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
password x Current password Valid password String 8 16
mfacode x MFA code, obtained after entering the seed in the application Valid MFA code String 6 6

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Resource URL

POST /api/{version}/user/login

Sample

POST https://test.example.com/api/v1/user/login

Login

Access Type: Write
Rate Limited: Yes

POST /user/login

Get a token to authenticate user via web interface

Example Request

{
    "email": "john@email.com",
    "password": "Mypassword$0",
    "mfacode": "613027"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
email x Email address of the user Valid email address String 6 60
password x Password of the user Password associated with the email address String 8 16
mfacode Multi-factor authentication code Valid multi-factor authentication code String 6 6

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "upid": "upid_1234567812345678",
    "uuid": "uuid_8765432112345678",
    "roles": [
        "system-admin"
    ],
    "availableprofilelist": [
        {
            "upid":"upid_1234567812345678",
            "name": "John Smith"
        },
        {
            "upid":"upid_2234567812345678",
            "name": "John Doe"
        }
    ]
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
upid Profile ID of the default profile String
uuid User ID String
roles List of roles associated with the user and profile combination Array
token Token to use for login via web interface String
availableprofilelist List of available profile object Array

profile Objects Properties

Name Description Type
upid Profile ID of the profile String
name Name of the profile String

Resource URL

GET /api/{version}/user/profilelist

Sample

GET https://test.example.com/api/v1/user/profilelist

Example Request

GET https://test.example.com/api/v1/user/profilelist

GetProfileList

Access Type: Read
Rate Limited: Yes

GET /user/profilelist

Get a list of profiles available to the user.

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "profilelist": [
        {
            "upid": "upid_1234567812345678",
            "type": "individual",
            "roles": ["role1","role2"],
            "name": "John Smith",
            "masterprofile": true,
            "defaultprofile": true
        },
        {
            "upid": "upid_2234567812345678",
            "type": "organization",
            "roles": ["role1","role2"],
            "name": "Acme Co.",
            "masterprofile": false,
            "defaultprofile": false
        },
        {
            "upid": "upid_31234567812345678",
            "type": "individual",
            "roles": ["role1","role2"],
            "name": "John Doe",
            "masterprofile": false,
            "defaultprofile": false
        }
    ]
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
profilelist Collection of profile objects Array

profile objects properties

Name Description Type
upid Profile ID String
type Profile type, individual or organization String
name Profile name String
roles Roles list Array
masterprofile True if this is the master profile for this user Boolean
defaultprofile True if this is the default profile for this user Boolean

Resource URL

POST /api/{version}/user/activate

Sample

POST https://test.example.com/api/v1/user/activate

ActivationEmail

Access Type: Write
Rate Limited: Yes

POST /user/activate

Send an activation email to a user.
Will send only if the user is pending email validation, and email and password are valid.
Doesn't support users already activated, or having MFA enabled.

Example Request

{
    "email": "john@email.com",
    "password": "Mypassword$0"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
email x Email address of the user Valid email address String 6 60
password x Password of the user Password associated with the email address String 8 16

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Resource URL

GET /api/{version}/system/user?email={email}
GET /api/{version}/system/user?uuid={uuid}

Sample

GET https://test.example.com/api/v1/system/user?email=john%40email.com
GET https://test.example.com/api/v1/system/user?uuid=uuid_1234567812345678

GetSystemUser

Access Type: Read
Rate Limited: Yes

GET /system/user

Get a user

Example request

GET https://test.example.com/api/v1/system/user?email=john%40email.com
GET https://test.example.com/api/v1/system/user?uuid=uuid_1234567812345678

Request Parameters (GET)

Name Required Description Accepted values Type Min length Max length
email User email Valid email address, must be URL encoded String 6 60
uuid User Universal ID Valid user ID String 21 21

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "user": {
        "uuid": "uuid_1234567812345678",
        "email": "john@email.com",
        "mfaenabled": false,
        "language": "en",
        "status": "active",
        "defaultprofile": {
            "upid": "upid_8765432112345678",
            "type": "individual",
            "status": "active",
            "tierlevel": 0,
            "roles": [
                "profile-admin"
            ],
            "profile": {
                "birthday": "1978-03-02",
                "firstname": "John",
                "lastname": "Smith",
                "email": "john@email.com",
                "phone": "(555) 555-5555",
                "address1": "123 Main Street",
                "address2": "#404",
                "city": "Montreal",
                "region": "QC",
                "country": "CA",
                "postalcode": "H3H 3H3"
            }
        }
    }
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
user User object JSON

user Object Properties

Name Description Type
uuid Universal User ID String
email User email String
mfaenabled MFA enabled Boolean
language User language String
status User status, may be active or inactive String
defaultprofile User default profile JSON

defaultprofile Object Properties

Name Description Type
upid Universal Profile ID String
type Profile type, may be individual or organization String
status Profile status, may be active or inactive String
tierlevel Tier level Number
roles List of roles Array
profile Profile object JSON

individual profile Object Properties

Name Description Type
firstname First name String
lastname Last name String
email Email String
phone Phone number, may not be present String
birthday Birthday, may not be present String
address1 Address line 1, may not be present String
address2 Address line 2, may not be present String
city City, may not be present String
region Region, may not be present String
country Country, may not be present String
postalcode Postal code, may not be present String

organization profile Object Properties

Name Description Type
organizationname Organization name String
adminfirstname Admin first name String
adminlastname Admin last name String
adminemail Admin email String
phone Phone number, may not be present String
industry Industry, may not be present String
registrationid Registration ID, may not be present String
address1 Address line 1, may not be present String
address2 Address line 2, may not be present String
city City, may not be present String
region Region, may not be present String
country Country, may not be present String
postalcode Postal code, may not be present String

Resource URL

POST /api/{version}/system/user/update

Sample

GET https://test.example.com/api/v1/system/user/update

UpdateSystemUser

Access Type: Write
Rate Limited: Yes

POST /system/user/update

Update the status of a specific user

Example Request

{
    "uuid": "uuid_1234567812345678",
    "status": "active"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
uuid x Universal User ID Valid uuid String 21 21
status x User status Either active or inactive String 6 8

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Wallet

Resource URL

POST /api/{version}/wallet/create

Sample

POST https://test.example.com/api/v1/wallet/create

CreateWallet

Access Type: Write
Rate Limited: Yes

POST /wallet/create

Create a new wallet for default (or specific) profile

Example Request

{
    "upid": "upid_1234567812345678",
    "walletname": "Main"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
walletname x Name of the wallet to be created String 1 30
upid Profile to add wallet to Valid Profile ID String 21 21
trading Is it a trading wallet true or false Boolean
market Associated market for a trading wallet String 1 20

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "walletname": "Main",
    "waid": "waid_4826413786035628"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
walletname Wallet name String
waid Wallet ID String

Resource URL

GET /api/{version}/wallet
GET /api/{version}/wallet/{waid}

Sample

GET https://test.example.com/api/v1/wallet
GET https://test.example.com/api/v1/wallet/waid_1234567812345678

Example Request

GET https://test.example.com/api/v1/wallet

GetWallet

Access Type: Read
Rate Limited: Yes

GET /wallet

Get balances from default (or specific) wallet

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "upid": "upid_1234567812345678",
    "trading": false,
    "waid": "waid_1234567812345678",
    "default": true,
    "shortcode": "A7e48E7cB4",
    "walletname": "Main",
    "expertmode": true,
    "balances": [
        {
            "currencyname": "Euro",
            "currencycode": "EUR",
            "available": "226.84",
            "held": "21.71",
            "total": "248.55"
        },
        {
            "currencyname": "Bitcoin",
            "currencycode": "BTC",
            "available": "1.616281",
            "held": "0.0",
            "total": "1.616281"
        }
    ]
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
waid Wallet ID String
shortcode Wallet ID shortcode (Base32) String
trading Is it a trading wallet Boolean
market Market associated with a trading wallet, only present for trading wallet String
balances List of balance objects Array
upid User Profile ID String
default Is it the default wallet Boolean
walletname Wallet name String
expertmode Is the wallet in expert mode Boolean

balance Object Properties

Name Description Type
currencycode Currency code String
currencyname Currency name String
available Available balance String
held Amount held String
total Total amount String

Resource URL

GET /api/{version}/wallet/list

Sample

GET https://test.example.com/api/v1/wallet/list

Example Request

GET https://test.example.com/api/v1/wallet/list

GetWalletList

Access Type: Read
Rate Limited: Yes

GET /wallet/list

Get balances from all wallets

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "walletlist": [
        {
            "trading": false,
            "waid": "waid_1234567812345678",
            "default": true,
            "walletname": "Main",
            "balances": [
                {
                    "currencyname": "Euro",
                    "currencycode": "EUR",
                    "available": "226.84",
                    "held": "21.71",
                    "total": "248.55"
                },
                {
                    "currencyname": "Bitcoin",
                    "currencycode": "BTC",
                    "available": "1.616281",
                    "held": "0.0",
                    "total": "1.616281"
                }
            ]
        }
    ]
}

Response parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
walletlist List of wallet objects Array

wallet Object Properties

Name Description Type
default Is it the default wallet Boolean
walletname Wallet Name String
waid Wallet ID String
trading Is it a trading wallet Boolean
market Market associated with a trading wallet, only present for trading wallet String
balances List of balance objects Array

balance Object Properties

Name Description Type
currencycode Currency code String
currencyname Currency name String
available Available balance String
held Amount held String
total Total amount String

Resource URL

GET /api/{version}/wallet/list/{upid}

Sample

GET https://test.example.com/api/v1/wallet/list/upid_1234567812345678

Example Request

GET https://test.example.com/api/v1/wallet/list/upid_1234567812345678

GetWalletListByUpid

Access Type: Read
Rate Limited: Yes

Get /wallet/list/{upid}

Get balances from all wallets for a specific profile

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "defaultwalletid": "waid_1234567812345678",
    "walletlist": [
        {
            "waid": "waid_1234567812345678",
            "walletname": "Main",
            "trading": true,
            "market": "ripple",
            "balances": [
                {
                    "currencyname": "Euro",
                    "currencycode": "EUR",
                    "available": "226.84",
                    "held": "21.71",
                    "total": "248.55"
                },
                {
                    "currencyname": "Bitcoin",
                    "currencycode": "BTC",
                    "available": "1.616281",
                    "held": "0.0",
                    "total": "1.616281"
                }
            ]
        },
        { ... }
    ]
}

Response parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
defaultwalletid Default wallet ID String
walletlist List of wallet objects Array

wallet Object Properties

Name Description Type
walletname Wallet Name String
waid Wallet ID String
trading Is it a trading wallet Boolean
market Market associated with a trading wallet, only present for trading wallet Boolean
balances List of balance objects Array

balance Object Properties

Name Description Type
currencycode Currency code String
currencyname Currency name String
available Available balance String
held Amount held String
total Total amount String

Resource URL

GET /api/{version}/wallet/list/name_{walletname}

Sample

GET https://test.example.com/api/v1/wallet/list/name_main
GET https://test.example.com/api/v1/wallet/list/name_paul
GET https://test.example.com/api/v1/wallet/list/name_expenses

Example Request

GET https://test.example.com/api/v1/wallet/list/name_main

GetWalletListByName

Access Type: Read
Rate Limited: Yes

Get /wallet/list/name_{walletname}

Get wallet list, matching the name criteria, for the current profile or all profiles if the caller is a superuser

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "defaultwalletid": "waid_1234567812345678",
    "walletlist": [
        {
            "waid": "waid_1234567812345678",
            "walletname": "Main"
        },
        { ... }
    ]
}

Response parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
walletlist List of wallet objects Array

wallet Object Properties

Name Description Type
walletname Wallet Name String
waid Wallet ID String

Resource URL

POST /api/{version}/wallet/depositaddress

Sample

POST https://test.example.com/api/v1/wallet/depositaddress

CreateWalletDepositAddress

Access Type: Write
Rate Limited: Yes

POST /wallet/depositaddress

Create new deposit address

Example Request

{
    "method": "ripple",
    "waid": "waid_1234567812345678"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
method x Deposit method Valid deposit method String 1 15
waid x Wallet ID Valid wallet ID String 21 21
mainaddress Main receiving address to use, if left blank will use the system default receiving address. Used for ripple other networks that use destination tags. Valid address for selected deposit method String 1 50

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "depositmethod": "ripple",
    "depositaddress": "rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn-123456",
    "waid": "waid_1234567812345678"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
depositmethod Deposit method String
depositaddress Deposit address. Includes destination tag for ripple other networks that uses it. String
waid Wallet ID String

Resource URL

GET /api/{version}/wallet/depositaddress/{depositmethod}/{currencycode}
GET /api/{version}/wallet/{waid}/depositaddress/{depositmethod}/{currencycode}

Sample

GET https://test.example.com/api/v1/wallet/depositaddress/ripple/ABC.acme
GET https://test.example.com/api/v1/wallet/waid_1234567812345678/depositaddress/ripple/ABC.acme

Example Request

GET https://api.omnigate.com/v1/wallet/depositaddress/ripple/ABC.acme

GetWalletDepositAddress

Access Type: Read
Rate Limited: Yes

GET /wallet/depositaddress/{depositmethod}/{currencycode}

Get deposit address for currency code in default (or specific) wallet
Currency code can only be for a base or extended currency

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "waid": "waid_1234567812345678",
    "depositmethod": "ripple",
    "depositaddress": "rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn-123456"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
waid Wallet ID String
depositmethod Deposit method String
depositaddress Deposit address String

Resource URL

GET /api/{version}/wallet/transactionlist
GET /api/{version}/wallet/{waid}/transactionlist

Sample

GET https://test.example.com/api/v1/wallet/transactionlist
GET https://test.example.com/api/v1/wallet/waid_1234567812345678/transactionlist

Example Request

GET https://test.example.com/api/v1/wallet/transactionlist
GET https://test.example.com/api/v1/wallet/waid_1234567812345678/transactionlist

GetWalletTransactionList

Access Type: Read
Rate Limited: Yes

GET /wallet/transactionlist

List all transactions for default (or specific) wallet

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "transactionlist": [
        {
            "amount": "178.53",
            "balance": "254.19",
            "fee": "0",
            "txid": "txid_1234567812345678",
            "description": "Deposit using Ripple",
            "currency": "CAD",
            "state": "Completed",
            "currencycode": 124,
            "type": "deposit",
            "timestamp": "2014-12-04T15:31:03Z"
        },
        {
            "amount": "-226.89",
            "balance": "24.78",
            "fee": "0",
            "txid": "txid_2234567812345678",
            "description": "Bank withdrawal",
            "currency": "USD",
            "state": "Completed",
            "currencycode": 840,
            "type": "withdraw",
            "timestamp": "2014-12-04T15:22:45Z"
        }
    ]
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
transactions List of transaction objects Array

transaction Properties

Name Description Type
amount Transaction amount String
balance Transaction balance String
fee Transaction fee String
txid Transaction ID String
description Description String
currency Currency Name String
state State String
currencycode Currency code Number
type Transaction type String
timestamp Timestamp String

Resource URL

GET /api/{version}/wallet/transaction/{txid}

Sample

GET https://test.example.com/api/v1/wallet/transaction/txid_1234567812345678

Example Request

GET https://test.example.com/api/v1/wallet/transaction/txid_1234567812345678

GetWalletTransactionDetails

Access Type: Read
Rate Limited: Yes

GET /wallet/transaction/{txid}

Get details of specific transaction

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "errorcode": 10000,
    "errormessage": "Ok",
    "timestampstart": "2017-04-28T17:12:07Z",
    "timestampfinal": "2017-04-28T17:12:07Z",
    "currency": "USD",
    "amount": "17.04",
    "method": "internal",
    "fee": "0",
    "txid": "txid_1234567812345678",
    "description": "Transfer",
    "currencycode": 840,
    "type": "transfer",
    "sourcewaid": "waid_1234567812345678",
    "sourcebalance": "27.35",
    "destinationwaid": "waid_2234567812345678",
    "destinationbalance": "17.04",
    "state": "Completed"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
errorcode Error code from the bridge Number
errormessage Error message from the bridge String
txid Transaction ID String
timestampstart Transaction start timestamp String
timestampfinal Transaction final timestamp String
currency Transaction currency String
amount Transaction amount String
fee Transaction fee String
state Transaction state String
method Transaction method String
type Transaction type String
description Description String
currencycode Currency code Number
sourcewaid Source wallet ID String
destinationwaid Destination wallet ID String
sourcebalance Source balance String
destinationbalance Destination balance String
externaltransactionid External network transaction ID String
externalsourceaddress External source address String
externaldestinationaddress External destination address String

Resource URL

POST /api/{version}/wallet/withdraw

Sample

POST https://test.example.com/api/v1/wallet/withdraw

WalletWithdraw

Access Type: Write
Rate Limited: Yes

POST /wallet/withdraw

Withdraw money from the default (or specific) wallet to an external account

Example Request

{
  "method": "ripple",
  "waid": "waid_1234567812345678",
  "amount": "10.97",
  "currency": "XRP",
  "destinationaddress": "rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn-123456"
}

As IOU

{
    "method": "ripple",
    "amount": "0.04",
    "currency": "BTC.bitstamp",
    "destinationaddress": "rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn-123456"
}

With conversion

{
    "method": "ripple",
    "amount": "1.87",
    "currency": "XRP",
    "destinationaddress": "rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn-123456",
    "destinationamount":"0.01",
    "destinationcurrency":"USD/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
amount x Amount to withdraw String 1 20
currency x Currency to withdraw in alphanumerical format, must be an internal currency Valid alphanumerical currency name String 3 16
method x Withdraw method Either bank, iban, ripple or bitcoin String 1 15
destinationaddress x Address of the recipient Valid destination address (varies depending on selected method) String 1 50
waid If present will withdraw from specified wallet Valid wallet ID String 21 21
destinationamount Destination amount (Applicable to in flight conversions) Valid quoted amount String 1 20
destinationcurrency Destination currency (Applicable to in flight conversions) Valid 3 letters alphanumerical currency name "/" issuer address. External to the platform String 3 3
extrabridgedata External data for the bridge, this is bridge dependant Missing, or any valid json data JSON 0 1000

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "txid": "txid_1234567812345678"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
txid Transaction ID String

Resource URL

POST /api/{version}/wallet/withdraw/test

Sample

POST https://test.example.com/api/v1/wallet/withdraw/test

WalletWithdrawTest

Access Type: Write
Rate Limited: Yes

POST /wallet/withdraw/test

Do a test prior to the actual withdraw. Works only with Ripple for now.

Example Request

{
    "method": "ripple",
    "amount": "23.78",
    "currency": "BTC.bitstamp",
    "destinationaddress": "rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn-123456"
}

With conversion

{
    "method": "ripple",
    "destinationamount": "17.89",
    "destinationcurrency": "USD/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
    "destinationaddress": "rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn-123456"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
amount depends Amount to withdraw String 1 20
currency depends Currency to withdraw in alphanumerical format, must be an internal currency Valid alphanumerical currency name String 3 16
method x Withdraw method ripple String 1 15
waid If present will withdraw from specified wallet Valid wallet ID String 21 21
destinationaddress x Destination address, may or may not have a destination tag. Valid destination address String 30 50
destinationamount depends Destination amount (Applicable to in flight conversions) Valid quoted amount String 1 20
destinationcurrency depends Destination currency (Applicable to in flight conversions - not defined in the platform) Valid 3 letters alphanumerical currency name and issuer address delimited with a slash String 3 40

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "paths": [
        {
            "sourceamount": "1.02321",
            "sourcecurrency": "BTC",
            "fee": "0.0032"
        },
        {
            "sourceamount": "532.26",
            "sourcecurrency": "USD",
            "fee": "0.75"
        }
    ]
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
paths List of possible paths, present only of enough funds Array
sourceamount The amount that will be withdraw from the wallet. The is the MAX amount. Will be adjusted after the actual withdraw. Will be lower or equal. String
sourcecurrency The currency that will be withdraw from the wallet String

Resource URL

POST /api/{version}/wallet/transfer

Sample

POST https://test.example.com/api/v1/wallet/transfer

WalletTransfer

Access Type: Write
Rate Limited: Yes

POST /wallet/transfer

Transfer money from one wallet to another

Example Request

{
    "amount": "278.53",
    "currency": "CAD",
    "sourcewaid": "waid_8765432112345678",
    "destinationwaid": "waid_1234567812345678"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
amount x Amount Available amount String 10 12
currency x Currency code Valid currency code String 3 16
destinationwaid x Destination wallet ID Valid wallet ID String 21 21
sourcewaid x Source wallet ID Valid wallet ID String 21 21
bridgecurrency Required when transferring money to a trading wallet Bridge currency code String 10 21
description The description string for this transaction String 1 40

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "txid": "txid_1234567812345678"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
txid Transaction ID String

Resource URL

GET /api/{version}/wallet/trustlines/{network}/{address}

Sample

GET https://test.example.com/api/v1/wallet/trustlines/ripple/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B

Example Request

GET https://api.omnigate.com/v1/wallet/trustlines/ripple/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B

GetTrustLines

Access Type: Read
Rate Limited: Yes

GET /wallet/trustlines/{network}/{address}

This operation returns the list of trust lines associated with a particular address

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "acceptxrps": true,
    "trustlines": [
        {
            "currency":"USD",
            "issueraddress ":"rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
            "issuername ":"BitStamp"
        },
        {
            "currency":"CAD",
            "issueraddress ":"rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
            "issuername ":"BitStamp"
        }
    ]
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
acceptxrps Does the address accept XRPs (hardcoded to true for now) Boolean
trustlines List of trustline objects Array

trustline Object Properties

Name Description Type
currency The 3 letters currency code String
issueraddress The issuer address String
issuername The issuer name String

Payment

Resource URL

POST /api/{version}/payment/request

Sample

POST https://test.example.com/api/v1/payment/request

CreatePaymentRequest

Access Type: Write
Rate Limited: Yes

POST /payment/request

Create a payment request.
If the Source wallet is present on the local platform, get funds from wallet.
This can be used to charge a wallet ID (waid) from a remote platform (identified by wallet id prefix)

Example Request

{
    "amount": "0.1214",
    "currency": "BTC",
    "method": "bitcoin",
    "referenceid": "ORD_02648579",
    "destinationwaid": "waid_1234567812345678"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
amount x Amount required to clear the payment request Valid amount String 1 20
currency x Currency required to clear the payment request, funds will be deposited in this currency Valid currency name String 3 16
method x Payment method Valid method (ripple, bitcoin, applepay, wallet) String 3 16
sourcewaid If known, source wallet ID (required for Apple Pay and wallet methods) Any valid wallet id (local to the platform, or in a remote platform) String 21 21
referenceid ID provided by your system for internal reference 64 character alphanumerical String 4 64
destinationwaid If present will deposit the funds into specified wallet Valid wallet ID String 21 21
clerkname Name of the clerk (if any) Person name (first+last name) String 4 30
creatoruuid UUID (user id) of the clerk that created this payment request UUID String 21 21

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "statuscode": 0,
    "statusmessage": "Waiting payment",
    "prid": "prid_1234567812345678",
    "method": "bitcoin"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
statuscode Payment status code Number
statusmessage Payment status message String
prid Payment request ID String
method Payment method String
paymentamounts A list of paymentamount objects containing possible payment amounts and methods, may not be present Array

paymentamount Object Properties

Name Description Type
method The method to use to pay this amount (ripple, bitcoin, etc...) String
amount The amount String
currency The currency String
paymentaddress The address where the payment must be sent to String
paymenturl The URL where the payment must be sent to String
expiration The payment must be sent before this time (usually 30 minutes) String

Resource URL

GET /api/{version}/payment/{prid}

Sample

GET https://test.example.com/api/v1/payment/prid_1234567812345678

Example Request

GET https://test.example.com/api/v1/payment/prid_1234567812345678

GetPaymentStatus

Access Type: Read
Rate Limited: Yes

GET /payment/{prid}

Get a payment status

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "statuscode": 0,
    "statusmessage": "Waiting payment",
    "prid": "prid_1234567812345678",
    "merchantname": "ACME corp.",
    "amount": "0,1214",
    "currency": "BTC",
    "destinationwallet": "waid_1234567812345678",
    "method": "bitcoin",
    "tip": true,
    "referenceid": "ORD_02648579"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
statuscode Payment status code Number
statusmessage Payment status message String
prid Payment request ID String
merchantname Name of the merchant String
amount Total amount required to change the payment status to paid String
currency Currency associated with the clearing amount String
destinationwaid Wallet ID of the destination wallet String
method Payment method String
tip Is tip allowed for this payment Boolean
referenceid ID provided by your system for internal reference, may not be present String
pcid The payment confirmation ID in the case this payment was completed, may not be present String

Resource URL

GET /api/{version}/payment/transactionlist

Sample

GET https://test.example.com/api/v1/payment/transactionlist

Example Request

GET https://test.example.com/api/v1/payment/transactionlist

GetPaymentTransactionList

Access Type: Read
Rate Limited: Yes

GET /payment/transactionlist

Get list of payment transactions

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "transactionlist": [
        {
            "amount": "0.002465",
            "currency": "BTC",
            "type": "charge",
            "timestampopen": "2014-12-08T12:27Z",
            "timestampclose": "2014-12-08T12:53Z",
            "method": "bitcoin",
            "statusmessage": "Paid",
            "prid": "prid_1234567887654321",
            "paymentrequestdirection": "outgoing",
            "processortoken":"sdfhghjg32hj4ghsavdfgfh234",
            "referenceid": "1A7SDHFJ78J9L65Y7598L980PDF6HJ8K"
        },
        {
            "amount": "83.15",
            "currency": "CAD",
            "type": "refund",
            "timestampopen": "2014-11-05T12:27Z",
            "timestampclose": "2014-11-05T12:40Z",
            "method": "wallet",
            "status": "Sent",
            "prid": "prid_1234567887654322",
            "paymentrequestdirection":"incoming"
        }
    ]
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
transactionlist List of transaction objects Array

transaction Object Properties

Name Description Type
prid Payment request ID String
amount Invoice amount String
currency Invoice currency String
method Payment method String
type Transaction type String
statusmessage Payment status message String
timestampopen Creation timestamp String
timestampclose Clearing timestamp String
paymentrequestdirection The direction of this payment request (outgoing if user is the creator, or incoming if user is the receiver) String
referenceid ID provided by your system for internal reference, if any String
processortoken Token from the payment processor, if any String

Resource URL

POST /api/{version}/payment/accept

Sample

POST https://test.example.com/api/v1/payment/accept

AcceptPayment

Access Type: Write
Rate Limited: Yes

POST /payment/accept

Accept a payment notification from a remote platform, or local to this platform.
Can only be paid once.
The user must be authenticated. The wallet is already associated with a payment notification ID.
The method parameter determines which method is used to process the payment. See Methods bellow.

Example Request

{
    "prid": "prid_2234567812345678",
    "currency":"CAD",
    "totalamount":"25.61",
    "method":"applepay",
    "paymentprocessorinformation" : {
        "number": 72637263762736273,
        "cvc": 123
    }
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
prid x Payment request id Valid prid String 21 21
currency x The currency code used for that payment String 3 3
method x Payment method applepay or wallet (for now) String 20 20
totalamount x The amount debited from the user wallet (invoice amount + tip for the waiter) String 1 20
paymentprocessorinformation Data specific to the method or payment processor JSON 2 20000

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Methods

ApplePay

"method": "applepay"

Integration of ApplePay is dependent on which payment processor you want to integrate with ApplePay.

Example Request for ApplePay with Stripe

{
    "prid": "prid_1603419819263741",
    "currency":"CAD",
    "totalamount":"25.61",
    "paymentprocessorinformation" : {
        "paymentprocessortoken": "tok_xxxxxxxxxxxxxxxxxxx"
    }
}
ApplePay with Stripe

To integrate ApplePay with Stripe in Omnigate, you need the Stripe token and send it to the Omnigate backend.

Example Stripe ApplePay payload to Accept Payment

Resource URL

POST /api/{version}/payment/refuse

Sample

POST https://test.example.com/api/v1/payment/refuse

RefusePayment

Access Type: Write
Rate Limited: Yes

POST /payment/refuse

Refuse a payment notification from a remote platform, or local to this platform.
Can only be refused once.

Example Request

{
    "prid": "prid_1234567812345678"
}

Request Parameters

Name Required Description Accepted values Type Min length Max length
prid x Payment Request ID valid prid String 21 21

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Resource URL

POST /api/{version}/payment/merchantinfo

Sample

POST https://test.example.com/api/v1/payment/merchantinfo

UpdateMerchantInfo

Access Type: Write
Rate Limited: Yes

POST /payment/merchantinfo

Update Stripe merchant information in order to activate that merchant on Stripe

Example Request

{
    "accepttos": "true",
    "firstname": "John",
    "lastname": "Smith",
    "dateofbirth": "1978-11-12",
    "city": "Montreal",
    "address": "123 Long Street",
    "postalcode": "H3H 3H3",
    "state": "QC",
    "entitytype": "company",
    "businessname": "ACME corp.",
    "businesstaxid": "1234567890TQ001"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
accepttos x Acceptance of the term of service, must be true true or false Boolean
firstname x First name String 20 20
lastname x Last name String 20 20
dateofbirth x Date of birth (YYYY-MM-DD) String 10 10
city x City name String 20 20
address x Address line 1 String 20 20
postalcode x Postal code String 20 20
state x State or province code 2 char state or province code String 2 2
ssnlast4 4 last digits of the social security number (required for individual) Number 4 4
entitytype x Type of merchant Only "company" for now String 7 7
businessname x Business name String 2 30
businesstaxid x Business tax ID String 9 9

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Currency

Resource URL

POST /api/{version}/currency/extended/create

Sample

POST https://test.example.com/api/v1/currency/extended/create

CreateExtendedCurrency

Access Type: Write
Rate Limited: Yes

POST /currency/extended/create

Create a new extended currency for active profile

Example Request

{
    "currencycode": "USD",
    "currencyname": "Starbucks USD",
    "currencydecimals": 2,
    "displaydecimals": 2,
    "referencecurrency": "USD"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
currencycode x 3 letters currency code 3 letters alpha code String 3 3
currencyname x Full currency name Human readable currency name String 1 15
currencydecimals x Currency accounting decimal precision 0 to 8 Number 1 1
displaydecimals x Currency display decimal precision 0 to 8 Number 1 1
issuername Issuer name, required when creating first extended currency lowercase 12 characters max String 1 12
referencecurrency Reference currency, when set the new currency will be accepted at par value for invoices created with the reference currency Existing base currency String 3 3

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Resource URL

POST /api/{version}/currency/bridge/create

Sample

POST https://test.example.com/api/v1/currency/bridge/create

CreateBridgeCurrency

Access Type: Write
Rate Limited: Yes

POST /currency/bridge/create

Create a new bridge currency for active profile. Parent currency can only be a currency owned by the current profile.

Example Request

{
    "parentcurrency": "USD.starbucks",
    "bridgename": "ripple",
    "enabledeposit": true,
    "enablewithdraw": true,
    "issueraddress":"r1hdg234uy234yg5ds5jb2ds8hn9d"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
parentcurrency x Parent currency Existing extended currency linked to the current profile String 5 16
bridgename x Bridge name Valid instantiated bridge name String 1 15
issueraddress x Issuer address String 10 40
enablewithdraw x If true, will enable withdraw for the new currency true or false Boolean
enabledeposit x If true, will enable deposit for the new currency true or false Boolean
issueraddress x Issuer address String 10 40

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "issueraddress": "r1hdg234uy234yg5ds5jb2ds8hn9d"
}

Response Parameters

Name Description Type
resultcode Result code Integer
resultmessage Result message String
issueraddress Issuer address String

Resource URL

POST /api/{version}/currency/issue

Sample

POST https://test.example.com/api/v1/currency/issue

IssueGatewayCurrency

Access Type: Write
Rate Limited: Yes

POST /currency/issue

"Create" money and add it to the currency creator's wallet

Example Request

{
    "currencycode": "ZZZ",
    "amount": "100"
}

The issuer name is added automatically after the currency code.
It would look like this after addition ZZZ.issuername.

Request Parameters

Name Required Description Accepted values Type Min length Max length
currencycode x Currency code The currency code String 5 20
amount x Amount of currency to create String 1 12

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "waid": "waid_1234567812345678"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
waid Wallet ID in which the money was added String

Resource URL

POST /api/{version}/currency/issueiou

Sample

POST https://test.example.com/api/v1/currency/issueiou

IssueIOU

Access Type: Write
Rate Limited: Yes

POST /currency/issueiou

Issue some IOUs on a network, from one address to another.
Note that the issuer address must be defined in the system and we must have the matching private key for this address. This address must also be funded.
There is no tracking or bookkeeping for this transfer.
If you send IOUs to your hot wallet, destination tag (receiverdesttag) must be present in the request.

Example Request

{
    "network": "ripple",
    "issueraddress": "racMPWzRVd38L9txvfY7Mj7zqRA2UNL8Me",
    "receiveraddress": "rpmGcKEqTFDHd3tvAWFENNLhy2HMy7Yj89",
    "receiverdesttag": 1234,
    "currencycode": "CAD",
    "amount": "10000"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
network x A valid network name, supported by a bridge Valid network name, depending on bridges (only ripple is used for now) String 1 25
issueraddress x The issuer address, this address must be know by the system, we must have the secret key and this address must be funded Valid network address String 6 60
receiveraddress x The receiver address, can be the hot wallet address Valid network address String 6 60
receiverdesttag The receiver destination tag, if not present, no destination tag will be sent on the network Valid 32 bits number Number 1 8
currencycode x The currency code, valid on that network (3 char for ripple) Valid currency String 3 3
amount x The amount to send to the destination address Valid amount String 1 25

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Resource URL

GET /api/{version}/currency/list

Sample

GET https://test.example.com/api/v1/currency/list

Example Request

GET https://test.example.com/api/v1/currency/list

GetProfileCurrencyList

Access Type: Read
Rate Limited: Yes

GET /currency/list

Get a list of currencies managed by this profile

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "currencylist": [
        {
            "currencyname": "Starbucks USD",
            "currencycode": "USD.starbucks.ripple",
            "displaydecimals": 2,
            "type": "bridge",
            "visible": true,
            "issueraddress": "rpmGcKEqTFDHd3tvAWFENNLhy2HMy7Yj89",
            "receivingaddress": "rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn"
        },
        ...
    ]
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
currencylist List of currency objects Array

currency Object Properties

Name Description Type
currencyname Currency full name String
currencycode Currency code String
displaydecimals Display decimal precision of the currency Number
type Currency type String
visible If set to true, curency is visible in the list Boolean
issueraddress Isser address String
receivingaddress Profile address String
referencecurrency Reference currency String

Resource URL

POST /api/{version}/currency/address/create

Sample

POST https://test.example.com/api/v1/currency/address/create

CreateProfileAddress

Access Type: Write
Rate Limited: Yes

POST /currency/profileaddress/create

Creates a receiving address, and adds the profile address extended attribute (profileaddress) to the profile

Example Request

{
    "bridgename": "ripple"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
bridgename x Bridge name Compatible name that is instantiated in the system String 2 15

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "bridgename": "ripple",
    "profileaddress": "r3UbZ8tKpNZau6Ydmrox34FAAjwmJzEHvg"
}

Response Parameters

Name Description Type
resultcode Result code Integer
resultmessage Result message String
bridgename Bridge name String
profileaddress Profile address String

Resource URL

GET /api/{version}/currency/address
GET /api/{version}/currency/{upid}/address

Sample

GET https://test.example.com/api/v1/currency/address
GET https://test.example.com/api/v1/currency/upid_1234567812345678/address

Example Request

GET https://test.example.com/api/v1/currency/address
GET https://test.example.com/api/v1/currency/upid_1234567812345678/address

GetProfileAddressList

Access Type: Read
Rate Limited: Yes

GET /currency/address

List all profile addresses and required trust lines for default or specific profile

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "profileaddresslist": {
        "ripple": {
            "profileaddress": "rKYCbogMexAxR3tySTTC7UFbnoKdUK5H19",
            "trustlinelist": [
                {
                    "issueraddress": "rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn",
                    "currency": "CAD"
                },
                ...
            ]
        },
        ...
    }
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
profileaddresslist List of profileaddress objects (one for each bridge) JSON

profileaddress Object Properties

Name Description Type
profileaddress Profile address String
trustlinelist List of trustline objects Array

trustline Object Properties

Name Description Type
issueraddress Issuer address String
currency Currency String

Resource URL

POST /api/{version}/currency/address/trustline

Sample

POST https://test.example.com/api/v1/currency/address/trustline

SetAddressTrustline

Access Type: Write
Rate Limited: Yes

POST /currency/address/trustline

This operation creates a trust line associated with an address and a currency

Example Request

{
    "bridgename": "ripple",
    "hostedaddress": "racZzyXWwvuUT98SsrQP7p65OnmMLkK4j3",
    "trustedaddress": "rpmABbCdEeF1GhiJ23Klm4NOo5Pq6RS78t",
    "currencycode": "USD",
    "amount": "1000"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
bridgename x Bridge name Compatible name that is instantiated in the system String 2 15
hostedaddress x Receiving address String 10 40
trustedaddress x Issuing address String 10 40
currencycode x Currency code 3 letters currency code String 3 3
amount x Trust line amount String 1 20

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Resource URL

POST /api/{version}/currency/address/attribute

Sample

POST https://test.example.com/api/v1/currency/address/attribute

SetAddressAttribute

Access Type: Write
Rate Limited: Yes

POST /currency/address/attribute

Creates a receiving address, and adds the profile address extended attribute (profileaddress) to the profile.

Example Request

{
    "bridgename": "ripple",
    "address": "rpmGcKEqTFDHd3tvAWFENNLhy2HMy7Yj89",
    "destinationtagrequired": true
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
bridgename x Bridge name Compatible name that is instantiated in the system String 2 15
address x Address The address to modify String 10 40
destinationtagrequired Sets destination required flag true or false Boolean

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Resource URL

GET /api/{version}/system/currency/list

Sample

GET https://test.example.com/api/v1/system/currency/list

Example Request

GET https://test.example.com/api/v1/system/currency/list

GetSystemCurrencyList

Access Type: Read
Rate Limited: Yes

GET /system/currency/list

Get a list of currencies supported by the system

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "currencylist": [
        {
            "depositmethodlist": [
                "ripple"
            ],
            "visible": true,
            "tier": 1,
            "public": true,
            "currencyname": "Canadian dollar",
            "decimaldisplay": 2,
            "currencyid": 124,
            "currencycode": "CAD",
            "type": "base",
            "withdrawmethodlist": [
                "ripple"
            ],
            "enabled": true
        },
        {
            "depositmethodlist": [
                "bitcoin",
                "ripple"
            ],
            "visible": true,
            "tier": 1,
            "public": true,
            "currencyname": "Bitcoin",
            "decimaldisplay": 4,
            "currencyid": 1001,
            "currencycode": "BTC",
            "type": "base",
            "withdrawmethodlist": [
                "bitcoin",
                "ripple"
            ],
            "enabled": true
        },
        ...
    ]
}
Response Parameters
Name Description Type
resultcode Result code Number
resultmessage Result message String
currencylist List of currency object Array
currency Object Properties
Name Description Type
currencyname Currency name String
currencyid Currency ID Number
currencycode Currency code String
type Currency type String
decimaldisplay Currency display decimal precision Number
tier Tier level Number
visible Is this currency visible Boolean
public Is this currency public Boolean
enabled Is this currency enabled Boolean
depositmethodlist List of deposit methods Array
withdrawmethodlist List of withdraw methods Array

Resource URL

POST /api/{version}/system/currency/bridge/create

Sample

POST https://api.omnigate.com/api/v1/system/currency/bridge/create

CreateSystemBridgeCurrency

Access Type: Write
Rate Limited: Yes

POST /system/currency/bridge/create

Create a new bridge currency for use system wide.
This is the only call that can create a bridge currency with a tier 1 (base) parent

Example Request

{
    "parentcurrency": "USD.starbucks",
    "bridgename": "ripple",
    "issuername": "Starbucks",
    "issueraddress": "r234hjwdghjg2hj34gjh...",
    "enabledeposit": true,
    "enablewithdraw": true
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
parentcurrency x Parent currency, must be present when creating a currency with external deposit or withdrawal methods String 3 30
bridgename x Bridge name Only ripple is used for now String 1 15
issuername x Issuer name String 1 25
issueraddress x Issuer address String 1 25
enabledeposit Is deposit enabled for this currency true or false Boolean
enablewithdraw Is withdraw enabled for this currency true or false Boolean

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Bridge

Resource URL

GET /api/{version}/system/bridge/active

Sample

GET https://test.example.com/api/v1/system/bridge/active

Example Request

GET https://test.example.com/api/v1/system/bridge/active

GetSystemActiveBridgeList

Access Type: Read
Rate Limited: Yes

GET /system/bridge/active

Get a list of active/instantiated bridges

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "bridgelist": [
        {
            "bridgename": "ripple",
            "description": "Ripple bridge",
            "instanceid": "1",
            "enabled": true,
            "status": "started",
            "externalaccountscount": 2
        },
        {
            "bridgename": "stellar",
            "description": "Stellar Bridge",
            "instanceid": "1",
            "enabled": false,
            "status": "started",
            "externalaccountscount": 1
        }
    ]
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
bridgelist List of bridge objects Array

bridge Object Properties

Name Description Type
bridgename Bridge name String
description Bridge description String
instanceid Instance ID Number
enabled Is bridge enabled Boolean
status Bridge status String
externalaccountscount Number or external accounts connected to this bridge Number

Resource URL

GET /api/{version}/system/bridge/{bridgename}-{instanceid}/balances

Sample

GET https://test.example.com/api/v1/system/bridge/bitcoin-1/balances

Example Request

GET https://test.example.com/api/v1/system/bridge/bitcoin-1/balances

GetSystemBridgeBalances

Access Type: Read
Rate Limited: No

GET /system/bridge/{bridgename}-{instanceid}/balances

Return the list of balances, internal and external for that bridge.
May take several seconds to execute. Rely on communicating to an external system.

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "bridgename": "bitcoin",
    "instanceid": 1,
    "description": "Bitcoin bridge",
    "balances": [
        {
            "identifier": "1",
            "internalfee": "0",
            "internalbalance": "0.01275387",
            "internalavail": "0.01275387",
            "internalheld": "0",
            "externalbalance": "0.01275387",
            "precision": 8,
            "currency": "BTC",
            "currencycode": 1001
        },
        {
            "identifier": "2",
            "internalfee": "0",
            "internalbalance": "0",
            "internalavail": "0",
            "internalheld": "0",
            "externalbalance": "0",
            "precision": 8,
            "currency": "BTC",
            "currencycode": 1001
        }
    ]
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
bridgename Bridge name String
instanceid Instance ID Number
description Bridge description String
balances List of balance objects Array

balance Object Properties

Name Description Type
identifier Balance identifier String
internalfee Internal fee String
internalbalance Internal balance String
internalavail Internal available balance String
internalheld Internal held baalance String
externalbalance External Balance String
precision Balance precision Number
currency 3 characters currency code String
currencycode Currency code Number

Resource URL

POST /api/{version}/system/bridge/updateaccount

Sample

POST https://test.example.com/api/v1/system/bridge/updateaccount

UpdateBridgeExternalAccount

Access Type: Write
Rate Limited: Yes

POST /system/bridge/updateaccount

Update the configuration of a bridge's external account

Example Request

{
    "bridgename": "ripple",
    "instanceid": 1,
    "accountdata": {
        "identifiername": "identifiervalue",
        "attributename": "value"
    }
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
bridgename x Bridge name Either ripple or bitcoin String 1 15
bridgeinstanceid x Instance ID Number 1 2
accountdata x List of external account attributes attribute_name/value pair JSON 2 20000

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Resource URL

GET /api/{version}/system/bridge/{bridgename}/externalaccount/identifier

Sample

GET https://test.example.com/api/v1/system/bridge/ripple/externalaccount/identifier

Example Request

GET https://test.example.com/api/v1/system/bridge/ripple/externalaccount/identifier

GetExternalAccountIdentifierField

Access Type: Read
Rate Limited: Yes

GET /system/bridge/{bridgename}/externalaccount/identifier

Get the details for the attribute name, that uniquely identify the external account for that type of bridge

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "accountidentifier": {
        "name": "publicaddress",
        "label": "Public Address",
        "type": "string"
    }
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
accountidentifier account identifier object JSON

account identifier Object Properties

Name Description Type
name Attribute name String
label Attribute label String
type Attribute type String

Resource URL

GET /api/:version/system/bridge/:bridgename/externalaccount/attributelist

Sample

GET https://test.example.com/api/v1/system/bridge/ripple/externalaccount/attributelist

Example Request

GET https://test.example.com/api/v1/system/bridge/ripple/externalaccount/attributelist

GetSystemBridgeExternalAccountAttributeList

Access Type: Read Rate Limited: Yes

GET /system/bridge/:bridgename/externalaccount/attributelist

Get a list of external account attributes for a particular bridge

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "attributelist": [
        {
            "name": "publicaddress",
            "label": "Public address",
            "type": "string",
            "masked": "false"
        },
        {
            "name": "secret",
            "label": "Secret",
            "type": "string",
            "masked": "true"
        }
    ]
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
attributelist List of external account attribute objects Array

attribute Object Properties

Name Description Type
name Attribute name String
label Attribute label String
type Attribute type String
masked Does this attribute value need to be masked Boolean

Resource URL

GET /api/{version}/system/bridge/{bridgename}-{instanceid}/externalaccountlist

Sample

GET https://test.example.com/api/v1/system/bridge/ripple-1/externalaccountlist

Example Request

GET https://test.example.com/api/v1/system/bridge/ripple-1/externalaccountlist

GetSystemBridgeExternalAccountList

Access Type: Read
Rate Limited: Yes

GET /system/bridge/{bridgename}-{instanceid}/externalaccountlist

Get a list of external accounts (and attributes) for a particular instance.

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "accountidentifier": "publicaddress",
    "externalaccountlist": [
        {
            "id": 1,
            "description": "Ripple Address",
            "status": "Ok",
            "issuing": false,
            "trackable": true,
            "attributelist": {
                "publicaddress": "rpmABbCdEeF1GhiJ23Klm4NOo5Pq6RS78t",
                "secret": "********",
                ...
            },
            "trustlinelist": [
                {
                    "issueraddress": "rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn",
                    "currency": "CAD"
                },
                ...
            ]
        },
        ...
    ]
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
accountidentifier Name of the most prominent attribute (e.g., useful when summarizing accounts) String
externalaccountlist List of external account objects Array

external account Object Properties

Name Description Type
id External account ID Number
description External account description String
status External account status String
issuing Is this account / address considered as an issuing address Boolean
trackable Is this account / address trackable Boolean
attributelist List of external account attributes JSON
trustlinelist List of external account trustline objects, only present when bridge is Ripple Array

trustline Object Properties

Name Description Type
issueraddress Issuer address String
currency Currency code String

Tier

Resource URL

GET /api/{version}/system/tiers

Sample

GET https://api.omnigate.com/api/v1/system/tiers

Example Request

GET https://api.omnigate.com/api/v1/system/tiers

GetTierData

Access Type: Read
Rate Limited: No

GET /system/tiers

Get a list of all tiers

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "tierlist": [
        {
            "level": 55,
            "tiername": "testTier",
            "depositcrypto": true,
            "depositfiat": true,
            "withdrawcrypto": true,
            "withdrawfiat": true,
            "transfercrypto": true,
            "transferfiat": true,
            "trading": true,
            "createpaymentreq": true,
            "sendpayment": true,
            "receivepayment": true,
            "processpayment": true,
            "limitdepositfiatamount1": "test",
            "limitdepositfiatamount2": "test",
            "limitdepositcryptoamount1": "test",
            "limitdepositcryptoamount2": "test",
            "limitdelayhours": 5,
            "limitwithdrawfiatamount1": "test",
            "limitwithdrawfiatamount2": "test",
            "limitwithdrawcryptotamount1": "test",
            "limitwithdrawcryptotamount2": "test",
            "limitdelaydays":5
        },
        ...
    ]
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
tierlist List of tier objects Array

tier Object Properties

Name Description Type
level A number representing the level of the tier Number
tiername The tier's name String
depositcrypto Does the tier allow crypto currency deposit Boolean
depositfiat Does the tier allow fiat currency deposit Boolean
withdrawcrypto Does the tier allow crypto currency withdrawal Boolean
withdrawfiat Does the tier allow fiat currency withdrawal Boolean
transfercrypto Does the tier allow crypto currency transfer Boolean
transferfiat Does the tier allow fiat currency transfer Boolean
trading Does the tier allow trading Boolean
createpaymentreq Does the tier allow creating payment requests Boolean
sendpayment Does the tier allow sending payment Boolean
receivepayment Does the tier allow receiving payment Boolean
processpayment Does the tier allow processing payment Boolean
limitdepositfiatamount1 The first limit of fiat currency the tier allows depositing String
limitdepositcryptoamount1 The first limit of crypto currency the tier allows depositing String
limitdepositfiatamount2 The second limit of fiat currency the tier allows depositing String
limitdepositcryptoamount2 The second limit of crypto currency the tier allows depositing String
limitwithdrawfiatamount1 The first limit of fiat currency the tier allows withdrawing String
limitwithdrawcryptoamount1 The first limit of crypto currency the tier allows withdrawing String
limitwithdrawfiatamount2 The second limit of fiat currency the tier allows withdrawing String
limitwithdrawcryptoamount2 The second limit of crypto currency the tier allows withdrawing String
limitdelayhours The time in hours the limit apply Number
limitdelaydays The time in days the limit apply Number

Resource URL

DELETE /api/{version}/system/tiers/{level}

Sample

DELETE https://api.omnigate.com/api/v1/system/tiers/55

Example Request

DELETE https://api.omnigate.com/api/v1/system/tiers/55

DeleteTier

Access Type: Write
Rate Limited: No

DELETE /system/tiers/{level}

Removes a tier, downgrading any user on the tier to be deleted to the first tier lower.

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Fee

Resource URL

DELETE /api/{version}/system/fee/schedule/{fsid}

Sample

DELETE https://api.omnigate.com/api/v1/system/fee/schedule/fsid_1234567812345678

Example Request

DELETE https://api.omnigate.com/api/v1/system/fee/schedule/fsid_1234567812345678

DeleteFeeSchedule

Access Type: Write
Rate Limited: No

DELETE /system/fee/schedule/{fsid}

Removes a fee schedule, replacing any profile's fee schedule to the default one.

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Component

The following operations may be used for any of the Omnigate components or modules which are Omnipass, Omnibridge or Omnipay. Use the component's name in lowercase to replace the component value in the operation's path. For example: ex. /api/{version}/system/omnipass/unlock.

Resource URL

POST /api/{version}/system/{component}/unlock

Sample

POST https://test.example.com/api/v1/system/omnipass/unlock

UnlockSystemComponent

Access Type: Write
Rate Limited: Yes

POST /system/{component}/unlock

Unlock a system component.

Example Request

{
    "password": "18j182n2^03%m1)I"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
password x Application password Valid unlock passphrase String 16 16

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Resource URL

GET /api/{version}/system/{component}/attributelist

Sample

GET https://test.example.com/api/v1/system/omnipass/attributelist

Example Request

GET https://test.example.com/api/v1/system/omnipass/attributelist

GetSystemAttributeList

Access Type: Read
Rate Limited: Yes

GET /system/{component}/attributelist

Get a list of system attribute descriptions for specified component.

Example response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "attributelist": [
        {
            "name": "notifierhost",
            "description": "Host name of the notifier"
        },
        ...
    ]
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
atttributelist List of attribute objects Array
attribute Object Properties
Name Description Type
name Attribute name String
description Attribute description String

Resource URL

POST /api/{version}/system/{component}/attribute

Sample

POST https://test.example.com/api/v1/system/omnipass/attribute

SetSystemAttribute

Access Type: Write
Rate Limited: Yes

POST /system/{component}/attribute

Set a specific system attribute for specified component.

Example Request

{
    "name": "inactivitytimeoutinminutes",
    "value": "15"
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
name x Attribute name String 1 30
value x Attribute value String 1 400

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String

Static

Resource URL

GET /api/{version}/static/currencylist

Sample

GET https://test.example.com/api/v1/static/currencylist

Example Request

GET https://test.example.com/api/v1/static/currencylist

GetPublicCurrencyList

Access Type: Read
Rate Limited: Yes

GET /static/currencylist

Get list of all available currencies

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "currencylist": [
        {
            "currencyname": "Bitcoin",
            "currencycode": "BTC",
            "currencytype": "base",
            "currencydecimals": 8,
            "displaydecimals": 8,
            "tier": 1,
            "depositmethodlist": ["ripple", "bitcoin"],
            "withdrawmethodlist": ["ripple", "bitcoin"]
        },
        {
            "currencyname": "Canadian Dollar",
            "currencycode": "CAD",
            "currencytype": "base",
            "currencydecimals": 2,
            "displaydecimals": 2,
            "tier": 1,
            "depositmethodlist": ["bank", "ripple"],
            "withdrawmethodlist": ["bank", "ripple"]
        },
        {
            "currencyname": "Starbucks Canadian Dollar",
            "currencycode": "CAD.starbucks",
            "currencytype": "extended",
            "currencydecimals": 2,
            "displaydecimals": 2,
            "tier": 2,
            "depositmethodlist": ["ripple"],
            "withdrawmethodlist": ["ripple"]
        }
    ]
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
currencylist List of currency objects Array

currency Object Properties

Name Description Type
currencyname Currency name String
currencycode Currency code String
currencydecimals Currency decimals Number
currencytype Currency Type String
displaydecimals Display decimals Number
depositmethodlist List of methods as strings Array
withdrawmethodlist List of methods as strings Array
tier Tier number Number
network Network name, only present on bridge currency String
issueraddress Issuer Address, may not be present String

Resource URL

GET /api/{version}/static/rolelist

Sample

GET https://test.example.com/api/v1/static/rolelist

Example Request

GET https://test.example.com/api/v1/static/rolelist

GetPublicRoleList

Access Type: Read
Rate Limited: Yes

GET /static/rolelist

Get list of roles and rights

Example Response

{
    "resultcode": 10000,
    "resultmessage": "Ok",
    "rolelist": [
        {
            "roleid": "agent-admin",
            "description": "Can add new agents",
            "rightlist": [
                {
                    "rightid": "readallprofiles",
                    "description": "Can read all profiles in the system"
                },
                ...
            ]
        },
        ...
    ]
}

Response Parameters

Name Description Type
resultcode Result code Number
resultmessage Result message String
rolelist List of role objects Array

role Object Properties

Name Description Type
roleid Role ID String
description Role description String
rightlist List of right objects Array

right Object Properties

Name Description Type
rightid Right ID String
description Right description String

API Interactions

Example Request

POST https://test.example.com/api/v1/user/login
Content-Type: application/json
{
    "email": "john@email.com",
    "password": "Mypassword$0",
    "mfacode": "613027"
}

Once your instance of the Omnigate OS is installed, you will have access to its API (Application Programming Interface). The Omnigate API is the best way to interact with the Omnigate OS from any 3rd party services (dashboards, mobile or web apps, etc.). This API is based on HTTP and is inspired by REST meaning that it uses the GET, POST and DELETE verbs, predictable resource-oriented URLs and the HTTP headers and accept parameters understood by off-the-shelf HTTP clients.

Example Responses

{
    "resultcode": 10000,
    "resultmessage": "Ok"
}
{
    "resultcode": 10001,
    "resultmessage": "Maintenance in progress"
}

Under normal circumstance, the API always returns JSON with a minimum of 2 parameters.

Parameter Description
resultcode A numeric code, that gives you details on what happens during that call.
resultmessage A human readable version of the resultcode, sometime with additional information.

Keep in mind that when you call this API, a number of things might happen:

As a caller of the Omnigate API, you must be very tolerant, and never assume that a call will succeed. That's a good general practice to gracefully handle problem that can take place at any moment while you are calling the API, keep that in mind when you design your application.

Financial operations

We consider financial operations, any operations that moves money, namely the "transfer" and "withdraw" operations. Some other operations can also fall into that category, like "createpaymentrequest", anything that's money related and that should not be executed twice. These operations are critical, and special care must be taken when error occurs during these type of operations.

Authentication

Example Requests with authentication

GET https://test.example.com/api/v1/profile
X-APIKey: {api_key}
...
GET https://test.example.com/api/v1/profile
Authorization: Bearer {access_token}
...

To access any routes in Omnigate API, one must authenticate using one of the 2 possible HTTP headers.

Header Description
X-APIKey Used with an API key for machine to machine communication
Authorization Used with a Bearer token (access_token) for human to machine communication

To further understand the authentication mechanism and for details on how to request an access token or an API key, see Using OAuth 2.0 with Omnigate.

Using OAuth 2.0 with Omnigate

The Omnigate API follows the OAuth 2.0 standard for authentication and authorization. OAuth 2.0 is an authorization framework used to enable a third-party to obtain limited access to user accounts on an HTTP service, such as Facebook, Google, and Omnigate. It works by delegating user authentication to the service that hosts the user account, and authorizing third-party applications to access the user account. The Omnigate SSO service, which manages Omnigate's authentication, works 2 ways. First, using the OAuth 2.0 grant types, it handles the authentication process to access the Omnigate API from a third-party website or application in the name of a user on your Omnigate installation. Second, it manages the login flow to your Omnigate installation using an external account such as Facebook or Google.

This page gives an overview of the OAuth 2.0 authorization protocol the Omnigate SSO service follows to control the access to the Omnigate API. If you want more details on how to enable login to your Omnigate installation with an external account, see Enable Public Registration

To request access to the Omnigate API from a third-party website or application

The Omnigate SSO service supports 2 types of authorization scenarios. Web Server for server side services and Client side and Installed applications for JavaScript (React, Angular, etc.), mobile devices, computers, etc. All applications follow a basic pattern when accessing the Omnigate API using OAuth 2.0, here are the 4 major steps:

1. Obtain OAuth 2.0 credentials from the Omnigate SSO service
Visit the Omnigate SSO /auth/apps endpoint to register your application and obtain OAuth 2.0 credentials such as a Client ID and Client Secret that are known to both Omnigate and your application. The Client ID is a publicly exposed string that is used by the Omnigate API to identify the application, and is also used to build authorization URLs that are presented to users. The Client Secret is used to authenticate the identity of the application to the service API when the application requests to access a user's account, and must be kept private between the application and the API. The set of values varies based on what type of application you are building. For example, a JavaScript application does not require a secret, but a web server application does.

OAuth 2.0 apps list

The Omnigate SSO service supports multiple OAuth applications and each can be configured for different third-party products.

2. Obtain an access token from the Omnigate SSO service
Before your application can access private data using the Omnigate API, it must obtain an access token that grants access to the API. A variable parameter called scope controls the set of resources and operations that an access token permits. During the access-token request, your application sends one or more values in the scope parameter. There are several ways to make this request, and they vary based on the type of application you are building. For example, a JavaScript application might request an access token using a browser redirect to the Omnigate SSO service, while an application installed on a device that has no browser uses web service requests. Some requests require an authentication step where the user logs in with their Omnigate account. After logging in, the user is asked whether they are willing to grant the permissions that your application is requesting. This process is called user consent.

Omnigate Permission Request

If the user grants the permission, the Omnigate SSO service sends your application an access token (or an authorization code that your application can use to obtain an access token). If the user does not grant the permission, the server returns an error.

3. Validate the access token
After an application obtains an access token, it needs to validate it with the JWKs endpoint. For details, see JWT and token validation

4. Send the access token to the API
After an application validates an access token, it sends the token to the Omnigate API in an Bearer authorization HTTP header.

5. Refresh the access token, if necessary
Access tokens have limited lifetimes. If your application needs access to the Omnigate API beyond the lifetime of a single access token, it can obtain a refresh token. A refresh token allows your application to obtain new access tokens. Token refresh is only possible with the Web server and Installed application scenarios.

Scenarios

Web Server applications

The Omnigate SSO OAuth 2.0 endpoint supports web server applications that use languages and frameworks such as PHP, Java, Python, Ruby, and ASP.NET. The authorization sequence begins when your application redirects a browser to an Omnigate SSO endpoint; the URL includes query parameters that indicate the type of access being requested. Omnigate SSO service handles the user authentication, session selection, and user consent. The result is an authorization code, which the application can exchange for an access token and a refresh token. The application should store the refresh token for future use and use the access token to access the Omnigate API. Once the access token expires, the application uses the refresh token to obtain a new one.

Server side requests process

For details, see Using OAuth 2.0 for Web Server applications

Client side and Installed applications

The Omnigate SSO OAuth 2.0 endpoint also supports JavaScript applications that run in a browser (React, Angular, etc.) and applications that are installed on devices such as computers, mobile devices, and tablets. The authorization sequence begins when your application redirects a browser to an Omnigate SSO endpoint; the URL includes query parameters that indicate the type of access being requested. Omnigate SSO service handles the user authentication, session selection, and user consent. The result is an access token, which the client should validate before including it in an Omnigate API request. When the token expires, the application repeats the process.

Client side requests process

For details, see Using OAuth 2.0 from Client Side or Installed applications

Unlock SSO component

On your Omnigate installation, if you need to restart your Omnigate SSO service, you will need to unlock it before accessing your Omnigate Dashboard in the browser. To do so, simply send a request to the auth/unlock endpoint of your Omnigate SSO service with the Application Password from the Omnigate® Installation Details generated during your Omnigate installation.

Resource URL

POST http://localhost:8040/auth/unlock

Sample

POST http://localhost:8040/auth/unlock

unlocksso

Access Type: Write Rate Limited: Yes

POST /auth/unlock

Unlock SSO component

Example Request

{
    "password": "1ABC234D5EF67G8H"
}
Request Parameters (POST)
Name Required Description Accepted values Type Min length Max length
password x Application password String 16 16

Example Response

{
    "status": "ok"
}
Response Parameters
Name Description Type
status Request status String

Enable Public Registration

Enable Public Registration on your Omnigate Installation (Facebook, Google, etc.)

Omnigate offers the possibility to connect to the Omnigate platform with an external account. For now, the only permitted accounts are Facebook, Google and LinkedIn.

1. Verify System Settings

Go to the System Dashboard on the System Settings panel and make sure your Omnigate Application has Enable Public Registration set to true. (System Dashboard > System > Settings > Enable Public Registration)

2. Create an Omnigate application with each of your social media provider

Once Public Registration is enabled, go to your social media (Facebook, Twitter, etc.) developer panel and create an app for Omnigate with the following Redirect URI (https://{domain}/auth/p/{strategy_name}/callback) to retrieve your AppID and App Secret.

To create an app for Omnigate on Facebook, visit your Apps panel on Facebook To create an app for Omnigate on Google, visit Google API's Developer dashboard To create an app for Omnigate on LinkedIn, visit LinkedIn's Developer dashboard

3. Add and configure an Authentication Strategy for each social network to Omnigate

With your AppID and App Secret in hand, go back to Omnigate's System Dashboard on the Authentication Strategies panel and set your authentication strategy with the following details. Select your Strategy name (Facebook, Google or LinkedIn for now). Then, set your Client ID with your AppID, your Client Secret with your App Secret and the Callback URL with the Redirect URI set in the previous step (https://{domain}/auth/p/{strategy_name}/callback).

Once these steps are done, the Authentication Strategies login buttons will be automatically added to the Omnigate Login screen.

List Authentication strategies

To list all public authentication strategies configured on your Omnigate installation, you may send requests to the auth/api/strategies endpoint on the Omnigate SSO service. The following request requires the Authorization Bearer HTTP Header.

Example Request

GET auth/api/strategies HTTP/1.1
Authorization: Bearer {access_token}
Host: test.example.com/

Example Response

{
    "status": "ok",
    "results": [
        {
            "id": "facebook",
            "name": "Facebook",
            "config": {
                "clientID": "123456789012345",
                "clientSecret": "a1234b5cd67e89f01234ghi56jk7l8mn",
                "callbackURL": "https://test.example.com/auth/p/facebook"
            }
        },
        {
            "id": "google",
            "name": "Google"
        },
        {
            "id": "linkedin",
            "name": "LinkedIn"
        }
    ]
}

Response Parameters

Name Description Type
status Response status String
results List of Authentication strategy object Array

Strategy Object Properties

Name Description Type
id Strategy ID String
name Strategy Name String
config Strategy config object, only present if the strategy is configured JSON

Config Object Properties

Name Description Type
clientID Client ID String
clientSecret Client Secret String
callbackURL Strategy callback url String

Add or Configure an Authentication strategy

To configure a public authentication strategy for your Omnigate installation, you may send requests to the auth/api/strategies endpoint on the Omnigate SSO service. The following request requires the Authorization Bearer HTTP Header with your access token and the Content-Type HTTP Header set to application/json.

Example Request

GET auth/api/strategies HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json
Host: test.example.com/
Data: {
    "google": {
        "clientID": "0987654321987654",
        "clientSecret": "ab12345c6d789ef0g",
        "callbackURL": "https://test.example.com/auth/p/google"
    }
}

Request Parameters (POST)

Name Required Description Accepted values Type Min length Max length
strategy_config x Authentication Strategy's config object ID'd by the strategy ID JSON 2 20000

strategy_config Object Properties

Name Required Description Accepted values Type Min length Max length
clientID x Strategy's Client ID String 8 8
clientSecret x Strategy's Client Secret String 32 32
callbackURL x Strategy's Callback URL String 1 2048

Example Response

{
    "status": "ok"
}

Response Parameters

Name Description Type
status Response Status String

JWT and Token validation

The Omnigate SSO service uses the JWT standard (JSON Web Token) following the JWK format (JSON Web Key) for the access token instead of using a randomly generated token to authenticate request to the Omnigate API.

Usage

Basically, in a JWT there are 3 section, the Header, the Payload and the Signature.

Once decoded, this is what the JWT should look like

{
    "header": {
        "alg": "RS256",
        "typ": "JWT",
        "kid": "a12b3cdef456789012ghij3kl4567m8n"
    },
    "payload": {
        "iss": "",
        "sub": "uuid_1234567812345678",
        "iat": 1502216561,
        "exp": 1502220161,
        "scope": "*",
        "context": {
            "upid": "upid_1234567812345678",
            "roles": [
                "system-admin"
            ]
        }
    },
    "signature": ...
}

Header Object Parameters

Name Description
alg Hashing algorithm
type Type
kid Key ID (Public Key fingerprint)

Payload Object Parameters

Name Description Value
iss Issuer Client ID (may not be present)
sub Subject User ID
iat Issued at Time in milliseconds at which the token was issued
exp Expiration Time Time in milliseconds at which the token expires
scope Scope Access token scope
context Context Object in which we store user related values

Context Object Parameters

Name Description Type
upid User Profile ID String
roles List of user permissions Array

JWK Validation

Coming soon

Notes

For more informations, you may read on these topics
JWK: https://tools.ietf.org/html/rfc7517
JWT: https://tools.ietf.org/html/rfc7519
Javascript Object Signing and Encryption framework (JOSE) : http://jose.readthedocs.io/en/latest/#

Using OAuth 2.0 from Web Server applications

This document explains how web server applications use the Omnigate SSO service endpoints to implement OAuth 2.0 authorization to access Omnigate API. OAuth 2.0 allows users to share specific data with an application while keeping their usernames, passwords, and other information private. For example, an application can use OAuth 2.0 to obtain permission from users to access their wallets.

This OAuth 2.0 flow is specifically for user authorization. It is designed for applications that can store confidential information and maintain state. A properly authorized web server application can access the API while the user interacts with the application or after the user has left the application.

Step 1: Retrieve your Client ID & Client Secret from the list of OAuth 2.0 Applications

Connect to the auth/apps endpoint on the Omnigate SSO service. If it's not already done, create a new application with a name and a valid redirect uri referring to the authentication callback url on your website. Finally, you'll be able to retrieve your Client ID and your Client Secret.

Step 2: Redirect to Omnigate SSO service

To request permissions to access a user's data, redirect the user to the Omnigate SSO auth/authorize endpoint.

Example Request

GET https://test.example.com/auth/authorize?response_type=code&client_id=12345678&redirect_uri=https%3A%2F%2Fmerchant.com%2Fauth-endpoint
Request Parameters (GET)
Name Required Description Accepted values Type Min length Max length
client_id x The Client ID for your application String 8 8
redirect_uri x Determines where the API server redirects the user after the user completes the authorization flow The value must exactly match the redirect_uri value listed for your project in the list of OAuth 2.0 Applications. Note that the http or https scheme, case, and trailing slash ('/') must all match. String 1 2048
response_type x OAuth2 Response type. Determines whether the Omnigate SSO endpoint returns an authorization code code String 4 4

In this step, the user decides whether to grant your application the requested access. At this stage, Omnigate displays a consent window that shows the name of your application that it is requesting permission to access with the user's authorization credentials. The user can then consent or refuse to grant access to your application.

Your application doesn't need to do anything at this stage as it waits for the response from the Omnigate SSO service indicating whether the access was granted. That response is explained in the following step.

Response Example: Authorization Code

GET https://merchant.com/auth-endpoint?code=12a3b4cd5ef67g8h9012i3jk456l78m9

Response Example: Error message

GET https://merchant.com/auth-endpoint?error=access_denied

Step 4: Handle the Omnigate SSO response

The Omnigate SSO service sends a response to the redirect_uri specified in your authorize request.

If the user approves the request, then the response contains an authorization code. If the user does not approve the request, the response contains an error message. The authorization code or error message that is returned to the server appears on the query string, as shown below:

Resource URL

POST /auth/token

Sample URL

POST https://test.example.com/auth/token

Step 5: Exchange authorization code for refresh and access token

After the web server receives the authorization code, it can exchange the authorization code for an access token. To do this, call the Omnigate SSO auth/token endpoint and set the following parameters:

Example Request

{
        "code": "{authorization_code}",
        "client_id": "12345678",
        "client_secret": "{client_secret}",
        "redirect_uri": "https://merchant.com/auth-endpoint",
        "grant_type": "authorization_code"
}
Request Parameters (POST)
Name Required Description Accepted values Type Min length Max length
code x Authorization code String
client_id x The Client ID for your application String 8 8
client_secret x Your application Client Secret String 32 32
redirect_uri x The redirect URI listed for your application on Omnigate The value must exactly match the redirect_uri value listed for your project in the API Console. Note that the http or https scheme, case, and trailing slash ('/') must all match. String 1 2048
grant_type x OAuth2 grant type authorization_code (as defined in the OAuth 2.0 specification) String 18 18

Example Response

{
    "access_token": "{access_token}",
    "refresh_token": "{refresh_token}",
    "token_type": "Bearer"
}
Response Parameters
Name Description Type
access_token The token that your application sends to authorize a Google API request. String
refresh_token A token that you can use to obtain a new access token. Refresh tokens are valid until the user revokes access. String
token_type The type of token returned. At this time, this field's value is always set to Bearer. String

Resource URL

GET /auth/jwks.json

Sample URL

GET https://test.example.com/auth/jwks.json

Step 6: Validate the user's Access Token

If the user has granted access to your application and you have exchanged the authorization code for an access token, you must explicitly validate the access token returned from the Omnigate SSO service. By validating, or verifying, the token, you ensure that your application "is not vulnerable to the confused deputy problem".

To validate the access token, get the Omnigate SSO list of JWKs from the auth/jwks.json endpoint. Then, decode your access token and retrieve the kid from it's header. Filter out your kid from the JWKs list and verify your access token against the JWK (check JWT and Token validation for more details).

HTTP Example

GET /api/v1/profile HTTP/1.1
Authorization: Bearer {access_token}
Host: test.example.com/

cURL Example

curl -H "Authorization: Bearer {access_token}" https://test.example.com/api/v1/profile

Calling Omnigate API

After your application has obtained an access token and validated it, you can use the token to make calls to the Omnigate API on behalf of a given user account or service account. To do this, include the access token in a request to the API by including the Authorization: Bearer {access_token} HTTP header.

Refresh access token

Access tokens periodically expire. You can refresh an access token without prompting the user for permission. To refresh an access token, your application sends an HTTPS POST request to the Omnigate SSO auth/token endpoint that includes the following parameters:

Resource URL

POST /auth/token

Sample URL

POST https://test.example.com/auth/token

Example Request

{
    "refresh_token": "{refresh_token}",
    "client_id": "12345678",
    "client_secret": "{client_secret}",
    "grant_type": "refresh_token"
}
Request Parameters (POST)
Name Required Description Accepted values Type Min length Max length
refresh_token x The refresh token returned from the authorization code exchange. String
client_id x The Client ID for your application String 8 8
client_secret x Your application Client Secret String
grant_type x OAuth2 grant type Must be refresh_token (as defined in the OAuth 2.0 specification) String 13 13

Example Response

{
    "access_token": "{access_token}",
    "token_type": "Bearer"
}
Response Parameters
Name Description Type
access_token The token that your application sends to authorize a Google API request. String
token_type The type of token returned. At this time, this field's value is always set to Bearer. String

Using OAuth 2.0 from Client Side or Installed applications

This document explains how to implement OAuth 2.0 authorization to access Omnigate API from a JavaScript application such as React or Angular and applications installed on devices like phones, tablets and computers. OAuth 2.0 allows users to share specific data with an application while keeping their usernames, passwords, and other information private. For example, an application can use OAuth 2.0 to obtain permission from users to access their wallets.

Client Side and Installed apps are running on individual devices, and it is assumed that these apps cannot keep secrets. They can access the Omnigate API while the user is present at the app or when the app is running in the background.

The main difference for Installed apps is that they must open the system browser and supply a local redirect URI to handle responses from the Omnigate SSO service.

Here is an example of a redirect intent-filter.

<activity android:name=".screens.redirect.RedirectActivity">
<intent-filter>
<action android:name="android.intent.action.VIEW"/>
<category android:name="android.intent.category.DEFAULT"/>
<category android:name="android.intent.category.BROWSABLE"/>
<data android:scheme="com.omnigate.app"/>
</intent-filter>
</activity>

Android way of handling browser and redirection

Since the users will be typing in their usernames and passwords on a sign in page that’s hosted on the Omnigate SSO service, you must create an intent that opens a browser and takes the user to the sign in page.

Once the user completes the sign in, the Omnigate SSO service will redirect the browser to the redirect URI you set in step 1 (below). Therefore, to be able to get the sign in result, your app must handle that redirect URI. You can do so by adding an intent-filter for it inside you manifest file.

Step 1: Retrieve your Client ID from the list of OAuth 2.0 Applications

Connect to the auth/apps endpoint on the Omnigate SSO service. If it's not already done, create a new application with a name and a valid redirect URI referring to the authentication callback url on your website or app. Finally, you'll be able to retrieve your Client ID.

Redirect URI format

When working on installed applications (iOS, Android, Desktop, etc.), your redirect URI should use the reverse DNS notation format for the Custom URI scheme value. For example, if the redirect URI is set to com.omnigate.app:/oauth2callback, the part com.omnigate.app is the reverse DNS notation of a domain under your control and /oauth2callback is an optional path component. Note that the custom scheme must contain a period to be valid and the path should begin with a single slash, which is different from regular HTTP URLs. This may vary depending if your on iOS or Android.

Step 2: Redirect to Omnigate SSO service

To request permissions to access a user's data, redirect the user to the Omnigate SSO auth/authorize endpoint.

Example Request

GET https://test.example.com/auth/authorize?response_type=token&client_id=12345678&redirect_uri=https%3A%2F%2Fmerchant.com%2Fauth-endpoint
Request Parameters (GET)
Name Required Description Accepted values Type Min length Max length
client_id x The Client ID for your application String 8 8
redirect_uri x Determines where the Omnigate SSO service redirects the user after the user completes the authorization flow The value must exactly match the redirect_uri value listed for your project in the list of OAuth 2.0 Applications. Note that the http or https scheme, case, and trailing slash ('/') must all match. String 1 2048
response_type x OAuth2 response type. This instructs the Omnigate SSO service to return the access token as a name=value pair in the hash (#) fragment of the URI to which the user is redirected after completing the authorization process. token String 5 5

In this step, the user decides whether to grant your application the requested access. At this stage, Omnigate displays a consent window that shows the name of your application that is requesting permission to access with the user's authorization credentials. The user can then consent or refuse to grant access to your application.

Your application doesn't need to do anything at this stage as it waits for the response from the Omnigate SSO service indicating whether the access was granted. That response is explained in the following step.

Response Example: Access Token

GET https://merchant.com/auth-endpoint#access_token={access_token}&token_type=Bearer

Response Example: Error message

GET https://merchant.com/auth-endpoint#error=access_denied
Step 4: Handle the Omnigate SSO response

The Omnigate SSO service sends a response to the redirect_uri specified in your authorize request.

If the user approves the request, then the response contains an authorization code. If the user does not approve the request, the response contains an error message. The authorization code or error message is returned on the hash fragment of the redirect_uri, as shown below:

Resource URL

GET /auth/jwks.json

Sample URL

GET https://test.example.com/auth/jwks.json
Step 5: Validate the user's Access Token

If the user has granted access to your application and you have exchanged the authorization code for an access token, you must explicitly validate the access token returned from the Omnigate SSO service. By validating, or verifying, the token, you ensure that your application "is not vulnerable to the confused deputy problem".

To validate the access token, get the Omnigate SSO list of JWKs from the auth/jwks.json endpoint. Then, decode your access token and retrieve the kid from it's header. Filter out your kid from the JWKs list and verify your access token against the JWK (check JWT and Token validation for more details).

HTTP Example

GET /api/v1/profile HTTP/1.1
Authorization: Bearer {access_token}
Host: test.example.com/

cURL Example

curl -H "Authorization: Bearer {access_token}" https://test.example.com/api/v1/profile

Calling Omnigate API

After your application obtains an access token, you can use the token to make calls to the Omnigate API on behalf of a given user account or service account. To do this, include the access token in a request to the API by including the Authorization: Bearer {access_token} HTTP header.

Roles and Rights List

Roles prefixes

Role prefix Description
system Related to system configuration and maintenance
internalapp Related to platform's backend services (internal application)
agent Related to calling center agents
registration Related to user registration
issuer Related to currencies
gateway Related to platform operations
trader Relating to trading
merchant Related to merchant operations
profile Related to a specific profile operations
adapter Related to the generic bridge
ewallet Related to ewallet operations

Roles suffixes

Role suffix Description
admin Administrative actions are possible.
rw Read and Write actions are possible
ro Read-only actions are possible

System Roles

Role Description
system-admin All rights to configure the platform, including adding currencies
system-rw Can perform system maintenance operation
system-ro Can read system wide data
registration-rw Can register a new user
internalapp-rw Internal application write right
internalapp-ro Internal application read right
adapter-admin Can interact with the generic bridge
agent-admin Can add new agents
agent-rw Can approve profiles and support tasks on profiles
agent-ro Can read limited profile data
gateway-admin Can select which networks and currencies can be emitted and other platform gateway settings
issuer-admin Can create currencies
issuer-rw Can create currencies
merchant-admin Can configure merchant settings, supported payment methods and manage team members and employee roles (per merchant)
merchant-rw All payment functions, including charging child profile wallets
merchant-ro Read only, can access list and GET operations including payments function
trader-admin Trader admin
trader-rw Active trader
trader-ro Can monitor orders
profile-admin Can configure profile settings. Can create child profile, manage roles mapping according to own profile.
profile-rw All operations on this profile ID (UPID)
profile-ro Read operations on this profile ID (UPID)
ewallet-rw Can access write, create and POST operations on child profiles and ewallets
ewallet-admin Can configure ewallet permissions including supported currencies, deposit and withdrawal methods for all childs, and add team members
ewallet-ro Can access list and GET operations on child profiles and ewallets

Rights

Right Description
superuser Can do anything!
systemadmin Can start and stop nodes, change node roles, etc...
readsystemdata Can access system private data (roles and rights list for example)
internalapp Represent an internal application
createusernoemailvalidation Can create a new user without the need of doing the email validation
approvekyc Can approve KYC submission
viewkyc Can view all kyc submission.
documentread Can read information about documents
kycdocumentupload Can upload document for KYC process
documentwrite Can modify information about a document
createagent Can create new agents
modifyagent Can modify agents
createmerchants Can create merchant profiles, can add merchant-admin rights to a user
createchildextendedcurrency Can create a child extended currency
manualdeposit Can do a manual deposit (adapters). Only possible for internalapp roles.
closewithdraw Can finalize a withdraw (adapters). Only possible for internalapp roles.
negativewallet Can set the balance of a wallet in the negative
addemptyprofile Can register an empty profile under some circumstances
createstandaloneprofile Can create a standalone profile
readallprofiles Can read all profiles in the system
modifyallprofiles Can modify all profiles in the system
readallwallets Can access all wallets
listallwallettx Can list all wallet transactions in the system
readallbalances Can read all wallet balances
createuser Can create users
resetpassword Can reset my password
resetchildpassword Can reset child password
modifyusermfa Can manage user MFA
modifyuserpassword Can change user password
managemerchants Can manage merchant profiles
readmyprofile Can read own profile.
modifymyprofile Can modify own profile.
createchildprofile Can create child profile
readchildprofile Can read child profiles.
modifychildprofile Can modify child profiles.
createprofileapikey Can create an APIKey for profile
changeprofiletier Can update a profiles tier
createchildprofileapikey Can create an APIKey for child
requestread Can read information about tier change requests
requestwrite Can write and update information about a tier change request
tiermanagement Can create tiers
createpaymentrequest Can create payment request
managepaymentrequest Can manage payments request
getpaymentlist Can view list of all payments
initiatetransfer Can initiate a transfer
initiatewithdraw Can initiate a withdraw
sendpaymentmessage Can send payment message
listmyswallettx Can list my wallet transactions
readwalletbalances Can get my wallet's balances
createreceivingaddress Can create a receiving address for a wallet
chargechildprofile Can pay using a child's wallet
listchildswallettx Can list my child's wallet transactions
readchildwalletbalances Can get my child wallet's balances
createchildreceivingaddress Can create a receiving address for a child's wallet
createcurrency Can create currency
createparentcurrency Can create extended currency with parent currency relation
createextendedcurrency Can create extended currency
listmycurrencies Can list extended currency associated with the current profile/issuer
manageteam Can view team members
createorders Can create trading orders
monitororders Can monitor own trading orders
createcheckout Can create a checkout
getcheckout Can get a checkout

System Roles and rights mapping

Role Rights
system-admin superuser
system-rw readsystemdata, listallwallettx, readallprofiles, modifyallprofiles, approvekyc, systemadmin, systeminstall
system-ro readsystemdata, listallwallettx, readallprofiles
registration-rw createstandaloneprofile, createuser
internalapp-ro internalapp, readallprofiles, readallwallets
internalapp-rw internalapp, readallprofiles, modifyallprofiles, createusernoemailvalidation, readallwallets
adapter-admin manualdeposit, closewithdraw, negativewallet, readallwallets
agent-admin readallprofiles, modifyallprofiles, approvekyc, createmerchants, managemerchants, listallwallettx, createstandaloneprofile, changeprofiletier, readallwallets
agent-rw readallprofiles, modifyallprofiles, approvekyc, createmerchants, managemerchants, listallwallettx, documentread, requestread, requestwrite, documentwrite, createstandaloneprofile, changeprofiletier, readallwallets
agent-ro readallprofiles, listallwallettx, documentread, requestread, readallwallets
gateway-admin
issuer-admin createcurrency
issuer-rw createcurrency
merchant-admin createpaymentrequest, managepaymentrequest, createcurrency, manageteam, createcheckout, getcheckout
merchant-rw createpaymentrequest, managepaymentrequest, createcheckout, getcheckout
merchant-ro managepaymentrequest, getcheckout
trader-admin createorders, monitororders
trader-rw createorders, monitororders
trader-ro monitororders
profile-admin readmyprofile, listmyswallettx, readwalletbalances, modifymyprofile, initiatewithdraw, initiatetransfer, manageteam, createuser
profile-rw readmyprofile, listmyswallettx, readwalletbalances, modifymyprofile, initiatewithdraw, initiatetransfer
profile-ro readmyprofile, listmyswallettx, readwalletbalances
ewallet-admin readmyprofile, modifymyprofile, listmyswallettx, readwalletbalances, readchildwalletbalances, listchildswallettx, readchildprofile, modifychildprofile, createchildprofile, createuser, modifyusermfa, modifyuserpassword, createprofileapikey, createchildprofileapikey, chargechildprofile, initiatewithdraw, initiatetransfer, manageteam
ewallet-rw readmyprofile, modifymyprofile, listmyswallettx, readwalletbalances, modifyusermfa, modifyuserpassword, initiatewithdraw, initiatetransfer
ewallet-ro readmyprofile, listmyswallettx, readwalletbalances

Errors

The Omnigate API uses custom error codes as opposed to the standard HTTP codes (200, 404, 500, etc). These codes might be returned at anytime during the normal operation of the platform and your application must handle these correctly.

Result code Name Description Caller behavior Retry Delay (in seconds) Max number of retries
10001 MAINTENANCE_IN_PROGRESS The platform is currently under maintenance Retry 10 2
10002 TOO_BUSY The platform is currently over capacity Retry 10 2
10003 SYSTEM_ERROR An internal error occurred Retry (only if not financial operations) 10 2
10004 TOO_FAST Some operations have frequency capping, this is the code that is returned when a particular operation is called too fast Retry 5 2
None Communication timeout Network error, or platform over capacity Retry (only if not financial operations) 10 2
None Invalid response Invalid http response (empty body / non JSON) Retry (only if not financial operations) 10 2

During network error, you, as the caller, have no way to know if the network error took place when the query was on its way to the platform, or on its way back to you, so the operation may or may not have been executed.

Because the actual platform, might be behind some form of load balancer or HTTP router, it's possible that you get a non JSON response. In that case, treat it as a SYSTEM_ERROR.

How to handle errors during financial operations

When you call a financial operation, and you get SYSTEM_ERROR or communication timeout, then you cannot just resubmit the call.

Under that scenario, you don't know if the call went through or not.

So you must get the transaction list first, in order to see if the operation was executed or not.

If the operation was not executed, then, and only then, you can resubmit this operation.

Typical response time and application timeout setting

System API operations all start with /system. For example: GET /api/{version}/system/profile/list

Public API operations are all the other calls. For example: GET /api/{version}/profile

Type of operation or operation name Typical response time Timeout in your application
Public API Operations <500 ms 5,000 ms
System API operations <600 ms 5,000 ms
Login and password related operations <800 ms 5,000 ms
WalletWithdrawTest operation <10,000 ms 15,000 ms
Bridge related operations <10,000 ms 15,000 ms