Title: Store Card Asset Definition File Extensions. Author: Guillaume Lebleu <[email protected]> Created: 2015-05-20 Status: DRAFT
This document refines existing fields and defines new fields of the Asset Definition File.
Gift card assets, store card assets, prepaid card assets have specific characteristics that are not captured in the Open Assets Protocol' Asset Definition File.
The following existing fields are re-used and their definition is refined.
| Field | Description |
|---|---|
| General | |
| name_short |
(required) For assets of type storeCard, ISO 4217 3-letter code or 4-letter X-ISO4127-A3 code representing the unit of account for the asset.
|
| contract_url |
(required) For assets of type storeCard, the URL containing the terms and conditions of the asset.
|
| description |
For assets of type storeCard, a brief description of the asset, used for accessibility.
|
| type |
(required) the value is storeCard.
|
| Visual | |
| icon_url |
For assets of type storeCard, the icon is used to represent the card.
|
| image_url |
For assets of type storeCard, the URL to an image representing the front of the card. Recommended size 1,033px x 657px (3.452" x 2.17").
|
The following new top-level fields are added.
| Field | Description |
|---|---|
| asset_group |
Arbitrary string describing a group of assets. Assets belonging to the same group must use the same name_short.
|
| country | (required) ISO 3166-1 2-letter code representing the country of issuance. |
| state |
ISO 3166-2 2-letter code representing the subdivision, state or province of issuance. Ex. CA for California.
|
| store_card |
An object containing new fields for assets of type storeCard.
|
The storeCardfield is added and defined as follows:
| Field | Description |
|---|---|
| Legal | |
| terms | (required) The terms and conditions displayed on the card. At most 4096 characters. 512 or less characters recommended. |
| Financial | |
| expiration_date | ISO 8601 formatted. Explicit UTC date/time when the asset is no longer valid for redemption by the issuer, or period from date/time of issuance after which asset is no longer valid for redemption by the issuer. |
| expiration_timeout |
ISO 8601 formatted. Period since timestamp of the block in which the asset was issued after which asset is no longer valid for redemption by the issuer. If expiration_date and expiration_timeout are both specified, the earliest date/time applies.
|
| dormancy_fees | Describes fees charged to the card after a certain period of inactivity. |
| cash_redemption | Describes conditions under which card is redeemable for cash or cash equivalent. |
| Visual | |
| logo_url | The URL to a logo representing the issuer. |
| back_image_url | The URL to an image representing the back of the card. Recommended size 1,033px x 657px (3.452" x 2.17"). |
| brand_color | The color of the brand, as a CSS-style RGB triple. |
| background_color | The background color of the card, as a CSS-style RGB triple. |
| text_color | The color of the text on the card, as a CSS-style RGB triple. |
| label_color | The color of the field labels on the card, as a CSS-style RGB triple. |
| Commerce | |
| locations_url | A URL to the list of locations accepting the asset. |
| skus_url | A URL to the list list of SKUs that the asset can be redeemed for. |
The dormancy_fees object is defined as follows:
| Field | Description |
|---|---|
| inactivity_period |
ISO 8601 formatted inactivity duration after which dormancy fees are applied (ex. P2Y for 2 years).
|
| fee_amount |
the fee charged to the store card asset after the inactivity duration has elapsed, expressed in units of the asset (ex. 100).
|
| maximum_balance |
the maximum amount of asset on the card for the dormancy fee to apply, expressed in units of the asset (ex. 500).
|
| fee_period |
ISO 8601 formatted period that the fee applies (ex. P1M for monthly).
|
The cash_redemption object is defined as follows:
| Field | Description |
|---|---|
| maximum |
the maximum amount of asset on the card redeemable for cash, expressed in units of the asset (ex. 500).
|
| maximum_percentage | the maximum amount of asset on the card redeemable for cash, expressed as a percentage of the issued amount. |
The concept of a card is foreign to open assets. The wallet will group multiple issuances of the same asset and present a lump balance of the "card" to the user. Therefore, an accounting principle must be followed to compute maximum_percentage. If the card is composed of multiple issuances of the same asset, a FIFO principle is followed to compute the maximum_percentage. For instance, if maximum_percentage is 10% and a card was issued 50 and then another 50, but only 47.5 was redeemed, we assume the 47.5 was spent first, so 2.5 is left of the first issuance and can be redeemed as cash, and 5 of the 50 left on the second issuance can be redeemed as cash, so 7.5 total (not 5% of 52.5).
The locations file is a JSON formatted file with one or more redemption locations, each defined as follows:
For each location, either url, altitude and longitude, or beacon_proximity_uuid is required.
| Field | Description |
|---|---|
| label | name of the location. |
| url | URL of the location |
| altitude | the altitude of the location. |
| latitude | the latitude of the location. |
| longitude | the longitude of the locaiton. |
| beacon_proximity_uuid | the unique identifier of the BLE beacon. |
| beacon_major | major value of the BLE beacon. |
| beacon_minor | minor value of the BLE beacon. |
Example:
{'locations': [ { "label": "Online store", "latitude": "37.4852778", "longitude": "-122.2352778" } ]}`
The SKUs file is a JSON formatted file with one or more redemption SKU, each defined as follows:
For each SKU, either sku or upc is required.
| Field | Description |
|---|---|
| label | name of the product or service |
| sku | the identifier of the product or service used by the merchant |
| upc | the registered universal identifier for the product or service |
Example:
{'skus': [ { "label": "example product", "upc": "123456789999" } ]}`