# Introduction Welcome to the API reference for the mCards Management REST API!

The Management API enables Programs to fully manage their program with CRUD capabilities for Billing Entities, Card Programs, Locations/Location Groups, Offers, Widgets and more through a REST API interface. But before we get into that, some background information!

# Getting Started ## API Objects

### Access Entities Access Entity represents basic information about the marketer or program associated with authenticated user. ### Billing Entities A Billing Entity is the entity contracted to make any payment due for a Card Program. A Billing Entity must be associated to an Card Program before a Card Campaign can be scheduled. ### Funding Sources A Funding Source is an account which can be charged for payment. It is associated to a Billing Entity. A Billing Entity can have multiple Funding Sources attached, and a priority set against them. ### Cards A Card is a virtual Card that the User receives. It is associated to a Card Program. ### Card Program Presets A Card Program Type defines the capabilities and funding models associated with the Card Program. There are two types of Card Program Type:

Generic mCard
Custom Branded mCard

### Card Designs A Card Design controls the appearance of the Card within the application and within the PAYS wallet. ### Card Programs A Card Program defines the configuration for Cards that are received by Users. The Card Program will hold the configuration and Card Features that will be associated to new Cards received by Users. ### Card Features A Card Feature is feature which extends the functionality of the Card for a User. Multiple Card Features can be associated to a Card Program. ### Campaigns A Campaign is created in order to Send a Card to a user. From the campaign the user will receive their Card. If a user already has a Card associated to a program, then the balance will be added to their existing Card. ### Restrictions Restrictions can be applied to a Campaign, such that the receiving mCash balance can only be used when certain criteria is met at a transaction level:

Location restricts the campaign mCash to an individual Location (this location must have terminals associated)
Location Group restricts the campaign mCash to an individual Location Group (locations within this Locatio Group must have terminals associated)
Merchant Category Code restricts the campaign mCash to a Merchant Category Code (this information is matched on transacted terminal)
Merchant Trade Name restricts the campaign mCash to a Merchant Trade Name (this information is matched on transacted terminal)
Preset Group restricts the campaign mCash to a Preset Group. The available Preset Groups can be viewed via List Restriction Preset Groups

### Restriction Preset Group A Restriction Preset Group is a group of restriction data that has been preconfigured by the mCards Backend. They have been organized into tagged groups which can be filtered by `tag` parameter.

Categories contains locations that have been categorized by their industry
Popular contains locations that have been deemed as popular by demand

### Reports Analytics are list of reports that can be retrieve on activity associated to a Card Program. ### Widgets The mCards Widget is a React JS based widget. It can display up to 3 "Product Prices" which are presented to a user. There are different flows that are supported within the Widget for authentication, purchasing and gifting. The flows for each can be condensed or full, where full is a more in-depth flow for the user. It is usually recommended to stick with `condensed` for these flows so that the user experiences the simplest flow with the least amount of blockers.
When a user purchases/accepts an item from the widget, there can be a Subscription or a Reward that is given to the user for their action. For example, on a Subscription-Based Widget, when a user purchases a price from the widget, then the user will receive a Subscription. It can be a One-Time-Use subscription, or a Subscription which has start and end dates and eventually expires. On Rewards-Based Widgets, like the Buy Bucks Widget or the Join Program Widget (currently in development and only accessable through direct API integration), when the user purchases/accepts the price, the user will receive a Reward. This reward is typically some amount of mCash or Points. ## Access In order to get started using this API, contact support@mcards.com to receive your API credentials. Once you have received those, you can get started by making API requests to the Staging/Pre-Production environment. ## Authentication This API allows for Server-to-Server & Client-to-Server communications. ### Server-to-Server HMAC-SHA256 is used to secure our Server-to-Server channels. This is a popular authentication mechanism using cryptographic hash functions. Its benefits are: - Data integrity: It means the data sent by the client to the server has not been tampered. - Request origination: The request comes to the server from a trusted client. Not a replay request: The request is not captured by an intruder and is being replayed. In this approach, the client server will attach a HMAC to each API message it sends. Our server will validate the HMAC, and be reassured that the request originated from the client and has not been sent to us by a malicious middle man. Along with the HMAC-256 Digest, the X-Program-UUID is also provided. - HMAC-256 Digest - X-Program-UUID ### Client-to-Server For Client Facing Apps, e.g. SPA Apps, mCards uses Auth0 Universal Login. After authenticating through Auth0, the logged in user will have their permissions within their JWT access token. These permissions will outline what access the user has. The access token should be sent along in a custom HTTP Header, along with the X-Program-UUID - X-Authorization-AccessJWT - X-Program-UUID #### CORS For Client Facing APIs they use CORs to ensure that the originating domain is allowed to access the widget APIs. Ensure the HTTP Header `Origin` is set on the API request. Your domains will be required to be whitelisted if you are using the APIs directly. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. ## Idempotent Requests The API supports idempotency for safely retrying POST requests without accidental duplication. This is useful when an API call is disrupted in transit and you do not receive a response. If you resend a POST request with the same value for the Idempotency-Key, you will receive the original response. If the server is still processing the original POST, you will receive 429 Too Many Requests. To perform an idempotent request, provide an additional X-Idempotency-Key element to the request headers. ## Metadata Many of the entities accept adding additional metadata which is stored against the entity and will be returned in GET requests. Metadata is useful for storing additional Program data that does not specifically map to an existing attribute of the entity. There is an upper limit of 50 metadata items per entity. ## Originator Identifier All entity accept an originator_identifier attribute. This can be used to store a unique identifier determined by the Program. It can be used to retrieve the entity through the GET/POST requests by providing an additional param identifier_type=originator_identifier. An originator identifier must be unique across the entity type and the Program, i.e. for locations you cannot use the same originator_identifier for two different locations. ### GET Example Request - GET http://staging.mcards.com/api/management/locations/cfcc47f0-7b55-0137-1a74-0242ac110003
Retrieve location associated with this Program using its Management API assigned UUID. -

GET http://staging.mcards.com/api/management/locations/cfcc47f0-7b55-0137-1a74-0242ac110003?identifier_type=originator_identifier

Retrieve location associated with this Program using its Program-assigned originator_identifier. - GET http://staging.mcards.com/api/management/locations/ChIJI6xB8LuNOxAR8ByP9fa7-Yk?identifier_type=google_place_id
Retrieve location associated with this Program using Google place id of an address linked to it. ### PUT Example Request - POST http://staging.mcards.com/api/locations/cfcc47f0-7b55-0137-1a74-0242ac110003
Update location associated with this Program using its Management API assigned UUID. - PUT http://staging.mcards.com/api/locations/cfcc47f0-7b55-0137-1a74-0242ac110003?field=originator_identifier
Update location associated with this Program using its Program-assigned originator_identifier. ## Delete Associated Entities If you want to remove an associated entity, like a targeting_tag or metadata for example, pass along an attribute of '_destroy': true

{
  "targeting_tags_attributes": [
    {
      "type": "user_subscription_tag",
      "value": "multi_city"
    },
      {
      "type": "user_subscription_tag",
      "value": "sydney",
      "_destroy": true
    }
  ]
}