Common formats

Throughout the enabler APIs, we ensure consistency by following common patterns and formats. If you find any discrepancies, we appreciate it if you can submit a ticket to us.

Amount

The Amount object represents monetary values and includes a currency code and amount value. It has two fields: currency & value. This ensures clarity and consistency in representing monetary values across different currencies.

• currency: This field should follow the ISO 4217 currency code (alpha-3) format (e.g., USD for United States Dollar, EUR for Euro).
• value: This field should be a string representing the amount in the smallest currency unit. The format of the decimal value will depend on the currency's minor unit.

USD

{
  "amount": {
    "currency": "USD",
    "value": "100.00"
  }
}

JPY

{
  "amount": {
    "currency": "JPY",
    "value": "1000"
  }
}

Date time

As each enabler deployment is dedicated per customer, the service can be configured with a customer timezone.

All date-time fields in the API will follow the configured timezone, formatted in ISO 8601 (with zone offset).

For example, if the server is configured with a Asia/Singapore zone, the date time returned throughout the APIs will be:

{
  "createdAt": "2024-07-03T16:02:34.021479+08:00",
  "updatedAt": "2024-07-03T16:02:33.730686+08:00"
}

Country code

Country codes should follow the ISO 3166-1 alpha-2 standard (the two letter country code)

e.g., SG for Singapore, HK for Hong Kong and etc

{
  "countryCode": "US"
}

Extras

In some scenarios, extra fields are required for processing with different upstream gateways.

To accommodate this, some APIs support an extra field, which is a plain kv pair object (Map<String, String>) that allows additional data to be passed along with the request.

This is particularly useful for including any custom or optional parameters specific to the integration or transaction.

Key points:

• 1-level: the struct shall be just a plain kv pair.
• Value type: all extra value shall be of string type

{
  "extra": {
    "customParam1": "value1",
    "customParam2": "value2"
  }
}

References

To provide an easier way to sync, track, and identify requests or entities from your system, some API might accept a xxxReference field. These reference fields are used to denote references from third-party systems.

Examples:

• posReference: Used in transaction requests to identify the transaction uniquely from the point of sale system.
• providerReference: Used in profile requests to identify the profile uniquely from the provider's system.

Important considerations:

• Uniqueness: Each reference value must be unique per enabler instance. If a unique constraint is violated during creation, a 400 BadRequest response will be returned.

By using these reference fields, you can ensure efficient tracking and identification of requests and entities across the board, facilitating better synchronization and data management.