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.
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:
- CentOS 7.x and later or Red Hat Enterprise Linux 7.x or later
- A processor with at least two cores
- At least 2Gb of RAM
- 20 Gb of hard disk space. Note that this is the recommended space for regular operations (including database and logs). The OmniGate installation itself will use much less space.
- An internet connection
- A static IP address
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.
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.
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.
10. Define your SMTP settings according to the installation wizard so the Omnigate OS can send you email for notifications, for example.
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.
15. Start Omnigate configuration.
16. Define the issuer name for the platform.
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 |
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
- If profile already exists in the system as top level profile with the same email, request should fail, else it should succeed
- If profile already exists in the system as sub-profile for the same merchant, request should fail and notify caller profile already exists
- If profile already exists in the system as sub-profile for another merchant, the request should succeed
- If registeruser is set to true and email already exists in the database the following logic should apply:
- If creating a top level profile, check if the user has masterprofile set, if no then the request should succeed if yes the request should fail
- If creating a sub-profile , and the user already exists, the request should succeed and give profile-ro right to new sub-profile to the existing user
- Email can only be changed by the master user
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 |
---|---|---|
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 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 |
---|---|---|---|---|---|---|
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 |
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 |
---|---|---|---|---|---|---|
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 |
---|---|---|---|---|---|---|
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 |
---|---|---|---|---|---|---|
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 |
---|---|---|---|---|---|---|
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 |
---|---|---|---|---|---|---|
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 |
---|---|---|---|---|---|---|
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 |
---|---|---|---|---|---|---|
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 |
---|---|---|---|---|---|---|
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 |
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 |
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 additionZZZ.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:
- Invalid parameters passed to the API
- Service availability problem (out of capacity, services simply not running)
- Network problem
- Internal errors
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.
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.
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.
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.
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 |
Step 3: Omnigate prompts user for consent
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 |
Step 3: Omnigate prompts user for consent
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 |