1GLOBAL Connect API (2024-10-17)

Secure by Design

1GLOBAL strives to implement best of breed security controls to its products and services. 1GLOBAL Connect API has considered security by design since it’s conception. This ensures that all layers from servers to data and source code follow a security by design approach.

1GLOBAL ensures all servers running Connect have a secure architecture and are securely hardened with configurations aligned with international and recognized standards.

Additionally, 1GLOBAL implements a strict vulnerability management program that continuously monitors for potential attack vectors along with the execution of periodic penetration tests to test our defences.

Knowing that preventive controls are just a part of the security puzzle, 1GLOBAL also operates a continuous monitoring and security incident response capability, within from our Cyber Defence Centre.

To maintain a high level of service for all clients of the platform, we enforce rate limiting on our APIs. These limits are applied based on the authentication credentials being used.

By default, the Connect API allows up to 1,000 requests per minute per resource endpoint, which should be sufficient for most high-traffic applications. We monitor the request volume for each API client and apply throttling if the allowed limit is exceeded.

Depending on your requirements, we may adjust this limit or establish different limits for certain API calls. If the current rate limits do not meet your needs, please contact Service Desk to request an increase.

To prevent your systems from becoming unavailable, we strongly recommend implementing custom logic to handle the rate limiting quotas. For every API request that stays within the current rate limits, you will receive a response with the following HTTP headers:

HTTP Header	Description
x-rate-limit-limit	The number of requests available for this API client.
x-rate-limit-remaining	The number of requests remaining in the current quota.
x-rate-limit-reset	The timestamp (Milliseconds since Unix Epoch) when the quota will reset

If you exceed the rate limit quota, you will receive a 429 Too Many Requests error, indicating that you have sent too many requests within the quota period.

Example:

{
    "message": "Rate limit exceeded ! You reach the limit of 10 requests per 1 minutes",
    "http_status_code": 429
}

Country/Currency	Currency Code
United States Dollar	USD
Albanian Lek	ALL
Algerian Dinar	DZD
Argentine Peso	ARS
Armenian Dram	AMD
Australian Dollar	AUD
Bahraini Dinar	BHD
Bangladeshi Taka	BDT
Barbadian Dollar	BBD
Bolivian Boliviano	BOB
Brazilian Real	BRL
British Pound	GBP
Brunei Dollar	BND
Bulgarian Lev	BGN
Cambodian Riel	KHR
Canadian Dollar	CAD
Central African CFA Franc	XAF
Chilean Peso	CLP
Chinese Yuan Renminbi	CNY
Colombian Peso	COP
Costa Rican Colon	CRC
Czech Republic Koruna	CZK
Danish Kroner	DKK
Dominican Peso	DOP
Egyptian Pound	EGP
Euro	EUR
Fijian Dollar	FJD
Georgian Lari	GEL
Hong Kong Dollar	HKD
Hungarian Forint	HUF
Icelandic Krona	ISK
Indian Rupee	INR
Indonesian Rupiah	IDR
Israeli Shekel	ILS
Jamaican Dollar	JMD
Japanese Yen	JPY
Jordanian Dinar	JOD
Kazakhstani Tenge	KZT
Kenyan Shilling	KES
Kuwaiti Dinar	KWD
Kyrgyzstani Som	KGS
Lebanese Pound	LBP
Macedonian Denar	MKD
Malaysian Ringgit	MYR
Mauritian Rupee	MUR
Mexican Peso	MXN
Moldovan Leu	MDL
Moroccan Dirham	MAD
Nepalese Rupee	NPR
New Zealand Dollar	NZD
Nigerian Naira	NGN
Norwegian Krone	NOK
Omani Rial	OMR
Pakistani Rupee	PKR
Peruvian Sol	PEN
Philippine Peso	PHP
Qatari Riyal	QAR
Romanian Leu	RON
Russian Ruble	RUB
Saudi Riyal	SAR
Serbian Dinar	RSD
Singapore Dollar	SGD
South African Rand	ZAR
South Korean Won	KRW
Special Drawing Rights	XDR
Sri Lankan Rupee	LKR
Swedish Krona	SEK
Swiss Franc	CHF
Taiwan Dollar	TWD
Tajikistani Somoni	TJS
Thai Baht	THB
Trinidad and Tobago Dollar	TTD
Tunisian Dinar	TND
Turkish Lira	TRY
UAE Dirham	AED
Ugandan Shilling	UGX
Ukrainian Hryvnia	UAH
Uruguayan Peso	UYU
Uzbekistani Som	UZS
Vietnamese Dong	VND
West African CFA Franc	XOF
Polish Zloty	PLN

Currency amounts

Connect API will always send and receive currency in the smallest unit the currency allows. In practice, this means we will receive amounts in whole units, not decimals.

The specific unit used for currency in the API depends on whether it is a zero-decimal currency.

• Zero-decimal currencies: For currencies that do not have decimal subunits, such as the Japanese Yen (JPY), the amount should be provided in the major unit of the currency. The major unit corresponds to the ISO 4217 code of the currency. For example, to specify an amount of JPY 15, set the amount as 15.

• Other currencies: For currencies that do have decimal subunits, Connect API supports values up to two decimal places in the major unit of the currency. This value must be converted to an integer by multiplying it by 100. For example, an amount of $3.53 should be provided as 3.53 x 100, which is 353.

We adhere to industry-standard conventions, allowing you to use familiar tools seamlessly. Our APIs are designed for self-service, guiding you through the next steps with ease. They are intuitive, well-documented, and backed by certifications to support smooth and secure integration.

To further enhance usability, we maintain consistent language across all services. This ensures a seamless experience, allowing you to quickly navigate and integrate different APIs without having to adapt to new terminology or conventions. The result is improved learnability, faster integration, and greater efficiency.

HAL standardizes the format of API resources and links, making it easier to navigate and interact with our APIs. By providing a consistent approach to hyperlinking between API resources, HAL allows seamless integration between different APIs, offering a more consumable and explorable experience.

One of HAL’s key advantages is that it is both machine-readable and human-readable, enabling you to quickly grasp the context from the API reference documentation.

We adopt this convention to structure resource and action links, ensuring compatibility with standard libraries for smoother and more efficient development.

{
  ...
 "_links": {
    "self": {
      "href": "https://example.com/probs/1234"
    },
    "author": {
      "href": "https://example.com/users/john"
    }
  }
}

To protect the service against overload, as well as to support client side iteration and batch processing experience, resource listing endpoints implement cursor-based pagination.

The only input required is the page size (using limit parameter) and subsequent navigation can be done through the next/prev page links provided in each page's response payload.

To prevent misuse of the pagination feature, each API defines a maximum allowed page size (currently 40).

{
  ...
  "_links": {
    "self": { "href": "https://example.com/probs?limit=10" },
    "prev": { "href": "https://example.com/probs?cursor=MTY3NjE1ODU1MS8yNUMxOTgxRjA1RDU5MDAwMDAwMA%3D%3D&limit=10" },
    "next": { "href": "https://example.com/probs?cursor=MTY3NjEzMzkxMS8yNUMxMEYzNkJBODA1NTkwMDAwMDAw&limit=10" },
  }
}

• Correlation-ID: In order to easily identify a request on all of 1GLOBAL's subsystems, we require that requesters create a unique identifier that will be sent on every request header when (Correlation-Id) using the api. This way we can easily identify a request or a sequence of events between both 1GLOBAL and the requester.

1GLOBAL strives to maintain backward compatibility across its APIs to provide a consistent experience for clients. However, there are instances where introducing breaking changes becomes necessary to implement new features, improvements, compliance reasons or architectural updates, in that cases, a new version of the API will be made available. We follow a Header Versioning approach, combined with data-based versioning, to ensure that clients can smoothly transition to the updated version without disrupting their current integrations. Clear documentation, migration guides, and deprecation timelines will always accompany these changes to minimize any potential impact.

Any additive (non-breaking) changes will be incorporated into all supported API versions, ensuring compatibility while providing access to new features.

Non Breaking Change definition

• Changing the lengh or format of identifiers including changing or removing prefixes
• Adding new optional request parameters to existing APIs
• Adding new properties to existing API responses
• Adding new HTTP headers ( optional request and response )
• Increasing the lenght of existing string field values
• New enumerate values
• New error codes
• Changing error messages
• Adding new webhooks event types (you might need to explicitly opt into these)
• Adding new properties to existing webhook event schemas
• New links and relationship types
• Changing FQDNs/path in links
• Reordering elements

Connect API follows standard HTTP status codes to communicate error information in a consistent and compliant manner following RFC7807

• HTTP status codes will be 4xx or 5xx when there's a problem
• The body of the response will be a JSON object
• The errors property contains an array giving specific details of one or more errors that occurred.

Status codes in the 4xx range

These status codes indicate an issue with the request that needs to be resolved. Once the issue is fixed, you can safely retry the call. Common examples include authentication errors (HTTP status code 401) or request body validation errors (HTTP status code 400).

Status codes in the 5xx range

These errors typically indicate server-side issues, ranging from configuration problems (which may be specific to a merchant or entity) to internal network connectivity issues. They can be transient, affecting only a single call, or persistent, impacting multiple calls over an extended period. In most cases, callers will be unable to resolve these issues on their own. The most common example of 5xx errors is timeouts.

{
    "title": "Invalid request parameters",
    "status": 400,
    "detail": "Invalid request parameters",
    "errors": [
        {
            "code": "MISSING_CONDITIONAL_MANDATORY_FIELD",
            "detail": "Field(s) [first_name, last_name, email, address] cannot be null when field [id] is equal to [null]",
            "json_path": "$.subscriber.id"
        },
        {
            "code": "GENERIC_ERROR",
            "detail": "must not be empty",
            "json_path": "$.purchase_location"
        }
    ],
    "correlation_id": "daaccc90-dd03-471c-a892-0e8c5ec27026"
}

Canada

Name	Code
Alberta	AB
British Columbia	BC
Manitoba	MB
New Brunswick	NB
Newfoundland and Labrador	NL
Northwest Territories	NT
Nova Scotia	NS
Nunavut	NU
Ontario	ON
Prince Edward Island	PE
Quebec	QC
Saskatchewan	SK
Yukon	YT

United States

Name	Code
Alabama	AL
Alaska	AK
Arizona	AZ
Arkansas	AR
California	CA
Colorado	CO
Connecticut	CT
Delaware	DE
Florida	FL
Georgia	GA
Hawaii	HI
Idaho	ID
Illinois	IL
Indiana	IN
Iowa	IA
Kansas	KS
Kentucky	KY
Louisiana	LA
Maine	ME
Maryland	MD
Massachusetts	MA
Michigan	MI
Minnesota	MN
Mississippi	MS
Missouri	MO
Montana	MT
Nebraska	NE
Nevada	NV
New Hampshire	NH
New Jersey	NJ
New Mexico	NM
New York	NY
North Carolina	NC
North Dakota	ND
Ohio	OH
Oklahoma	OK
Oregon	OR
Pennsylvania	PA
Rhode Island	RI
South Carolina	SC
South Dakota	SD
Tennessee	TN
Texas	TX
Utah	UT
Vermont	VT
Virginia	VA
Washington	WA
West Virginia	WV
Wisconsin	WI
Wyoming	WY

"Lifecycle" refers to the series of stages or states that an entity (such as an order or product) goes through from its creation to its completion or termination. It represents the entire journey of the entity within the system, including all possible states and transitions.