USConnect API - Blue World Inc

MigrateAccountDetails

Returns a data set describing the account. The account_id can be either: OAN | card_number | account_id | "apple_pay"

GET /migrate/account/:account_id[/][:country_code][/][:currency_type][/]

This will accept plain text OAN or "apple_pay". If account_id is set to apple_pay, vas decryption will be used on the param "vasData". Otherwise the OAN will be used as plain text.
Example: /account/apple_pay?vasData={url encoded BASE64_ENCODED_VAS_DATA}
NOTE: BASE64_ENCODED_VAS_DATA must be url safe encoded.

Request

Headers

Header	Value
Accept	application/vnd.us-connect.v1+json application/json application/*+json

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
404: Not Found

Headers

Header	Value
Content-Type	application/vnd.us-connect.v1+json application/json application/*+json
Allow	Comma-separated list of all HTTP methods allowed

Body

Example response:
{
    "account_id": "1234",
    "active": true,
    "aliases": [
        "12345678901234", 
        "1234567890123456"
    ],
    "available_balance": 4.75,
    "current_balance": 4.75,
    "points_balance": 153
}

MigrateLoad

This call allows a consumer to add funds to their USConnect balance. This can be a cash or credit load of funds from a point of sale or other approved medium.

POST /migrate/load[/]

Fields

Field	Type	Description	Required
device_serial_number	string	Serial number of device making request.	YES
card_number	integer	Field id can be: card_number \| card_info OAN or Card number being using to make purchase	NO
external_reference_id	string	Supplier generated ID of the original call	YES
load_type	string	Indicate if the load is done with cash or card. Possible value: “cash” \| “card”	YES
amount		Amount of the money to be loaded to the card.	YES
card_info		The card number or OAN.	NO
account_info		The account identifier. This could be the account ID, card OAN, card number, or other account alias.	NO
account_id		The account ID.	NO
country_code	string	Country code. Possible values: USA \| CAN. Defaults to USA. Required if currency_type is present.	NO
currency_type	string	Currency code. Possible values: USD \| CAD. Defaults to USD. Required if country_code is present.	NO

Request

Headers

Header	Value
Accept	application/vnd.us-connect.v1+json application/json application/*+json
Content-Type	application/vnd.us-connect.v1+json application/json

Body

Example Request:
{
    "device_serial": "123456789",
    "card_number": "1234567890123456",
    "external_reference_id": "8sf8342-8295b61c16918s3-8123j5",
    "load_type": "card",
    "amount": 10.00
}

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
201: Created
404: Not Found
400: Client Error
422: Unprocessable Entity

Headers

Header	Value
Content-Type	application/vnd.us-connect.v1+json application/json application/*+json
Allow	Comma-separated list of all HTTP methods allowed

Body

Example Response:
{
    "account_id": "1234",
    "account_url": "/account/1234",
    "net_transaction_amount": 10.00,
    "net_transaction_points": 0,
    "new_available_balance": 23.00,
    "new_points_balance": 288,
    "transaction_id": 23256458,
    "url": "/load/23256458"
}

MigratePromotionDetails

Gets a list of current active promotions.

GET /migrate/promotion_details[/][:country_code][/]

Request

Headers

Header	Value
Accept	application/vnd.us-connect.v1+json application/json application/*+json

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
404: Not Found

Headers

Header	Value
Content-Type	application/vnd.us-connect.v1+json application/json application/*+json
Allow	Comma-separated list of all HTTP methods allowed

Body

Example Response:

[
    [
        {
		"id": 1,
		"title": "Promotion 1",
                "desc": "Test Description 1",
		"image_url": "/images/promotion_1.png",
                "start_timestamp": 1488844800,
                "end_timestamp": 1490918400,
                "created_timestamp":1475091136,
                "updated_timestamp":1475091136,
                "upc":1234567890
	}, 
        {
		"id": 1,
		"title": "Promotion 2",
                "desc": "Test Description 2",
		"image_url": "/images/promotion_2.png",
                "start_timestamp": 1488844801,
                "end_timestamp": 1490918401,
                "created_timestamp": 1475091136,
                "updated_timestamp": 1475091136,
                "upc": 0987654321
	}, 
    ]
]

MigratePurchase

Allows consumer to buy an item at a USConnect enabled point of sale or other approved medium.

POST /migrate/purchase[/]

NOTE: Multiple barcodes will be accepted, however only the first one in the string will be used for the item.
NOTE: Quantity is optional, if included only transmit the price for a single item. For example, a quantity of 3 items priced at $1 each will lead to a balance reduction of $3.

Fields

Field	Type	Description	Required
device_serial_number	String	Serial number of device making request or pos_id	NO
card_number	integer	Field id can be card_number \| card_info OAN or Card number being using to make purchase	NO
external_reference_id	string	Supplier generated ID of the original call	NO
items	Array	Array of items that are to be purchased.	NO
card_info		The card number or OAN.	NO
account_info	string	The account identifier. This could be the account ID, card OAN, card number, or other account alias.	NO
account_id		The account ID.	NO
method	string	regular or apple_pay (default is regular)	NO
country_code	string	Country code. Possible values: USA \| CAN. Defaults to USA. Required if currency_type is present.	NO
currency_type	string	Currency code. Possible values: USD \| CAD. Defaults to USD. Required if country_code is present.	NO
affiliate_name	string	Affiliate name.	NO

Request

Headers

Header	Value
Accept	application/vnd.us-connect.v1+json application/json application/*+json
Content-Type	application/vnd.us-connect.v1+json application/json

Body

Example Request:

{
    "card_number": "1234567890123456",
    "device_serial_number": "123456789",
    "external_reference_id": "123456-asdfghjklzxcvbnm-09876",
    "affiliate_name": "Food Express",
    "items": [
        {
            "barcode": "000123456789",
            "coil_name": null,
            "deposit": 0.00,
            "description": "Test Description 1",
            "price": 1.25,
            "tax": 0.09
        },
        {
            "barcode": "987654321, 982735827, 9812653296",
            "coil_name": null,
            "deposit": 0.00,
            "description": "Test Description 2",
            "price": 1.50,
            "tax": 0.10
        },
        {
            "barcode": "7632347812",
            "coil_name": null,
            "deposit": 0.00,
            "description": "Test Description 3",
            "price": 1.50,
            "tax": 0.10,
            "quantity": 3
        }
    ]
}

OR
{
    "method": "apple_pay",
    "card_info": "16qwkjh02935bjkv98wyerjaog893tkasd9g8yqk4j3tas9dg",
    "device_serial_number": "123456789",
    "external_reference_id": "123456-asdfghjklzxcvbnm-09876",
    "affiliate_name": "Food Express",
    "items": [
        {
            "barcode": "000123456789",
            "coil_name": null,
            "deposit": 0.00,
            "description": "Test Description 1",
            "price": 1.25,
            "tax": 0.09
        },
        {
            "barcode": "987654321, 982735827, 9812653296",
            "coil_name": null,
            "deposit": 0.00,
            "description": "Test Description 2",
            "price": 1.50,
            "tax": 0.10
        },
        {
            "barcode": "7632347812",
            "coil_name": null,
            "deposit": 0.00,
            "description": "Test Description 3",
            "price": 1.50,
            "tax": 0.10,
            "quantity": 3
        }
    ]
}

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
201: Created
404: Not Found
400: Client Error
422: Unprocessable Entity

Headers

Header	Value
Content-Type	application/vnd.us-connect.v1+json application/json application/*+json
Allow	Comma-separated list of all HTTP methods allowed

Body

Example Response:


{
    "account_url": "/account/1234",
    "reward_url": "/reward/23256450",
    "url": "/purchase/23256450",
    "account_id": "1234",
    "transaction_id": 10028,
    "net_transaction_amount": 2.75,
    "net_transaction_points": 18,
    "new_available_balance": 23.00,
    "new_points_balance": 288,
    "reward_amount": 0.25,
    "reward_points": 0,
    "created": 1489513831
}

MigrateRedeemPromotion

Redeem a promo code onto the specified account.

POST /migrate/redeem/promotion[/]

Fields

Field	Type	Description	Required
promo_code		Promo code being redeemed.	YES
oan		OAN that should be used.	NO
card		The Card Number associated with the OAN.	NO
country_code	string	Country code. Possible values: USA \| CAN. Defaults to USA. Required if currency_type is present.	NO
currency_type	string	Currency code. Possible values: USD \| CAD. Defaults to USD. Required if country_code is present.	NO

Request

Headers

Header	Value
Accept	application/vnd.us-connect.v1+json application/json application/*+json
Content-Type	application/vnd.us-connect.v1+json application/json

Body

Example Request:
{
    "promo_code": "promo_1234",
    "oan": "12345678901234"
}

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
201: Created
404: Not Found
400: Client Error
422: Unprocessable Entity

Headers

Header	Value
Content-Type	application/vnd.us-connect.v1+json application/json application/*+json
Allow	Comma-separated list of all HTTP methods allowed

Body

Example Response:
{
    "redeemed_code" => "promo_1234",
    "redeemed_credit" => 10,
    "transaction_id" => 1,
    "new_balance" => 15,
    "oan" => "12345678901234"
}

MigrateReversal

Immediately undoes the transaction previously performed. Use case would be if a product was approved to vend and a successful purchase call was made and then the coil selected was empty.

POST /migrate/reversal[/]

Fields

Field	Type	Description	Required
external_reference_id	string	External reference ID that will be saved with the transaction.	NO
original_external_reference_id	string	If the original transaction ID is unknown, the transaction may be reversed by specifying the external_reference_id that was used in the transaction.	NO
original_transaction_id	string	Transaction ID of the transaction you want to reverse.	NO
original_transaction_type	string	The type of the original transaction.	YES
device_serial_number	string	device_serial_number	YES
country_code	string	Country code. Possible values: USA \| CAN. Defaults to USA. Required if currency_type is present.	NO
currency_type	string	Currency code. Possible values: USD \| CAD. Defaults to USD. Required if country_code is present.	NO

Request

Headers

Header	Value
Accept	application/vnd.us-connect.v1+json application/json application/*+json
Content-Type	application/vnd.us-connect.v1+json application/json

Body

Example Request:

{
    "external_reference_id": null,
    "original_external_reference_id": null,
    "original_transaction_id": 23256450,
    "original_transaction_type": "purchase",
    "device_serial_number": "123456789"
}

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
201: Created
404: Not Found
400: Client Error
422: Unprocessable Entity

Headers

Header	Value
Content-Type	application/vnd.us-connect.v1+json application/json application/*+json
Allow	Comma-separated list of all HTTP methods allowed

Body

Example Response:

{
    "account_id": "1234",
    "account_url": "/account/1234",
    "url": "/reversal/23256455",
    "net_transaction_amount": 2.75,
    "net_transaction_points": -18,
    "new_available_balance": 21.25,
    "new_points_balance": 200,
    "transaction_id": 23256455
}

Documentation

USConnect (v1)

MigrateAccountDetails

GET /migrate/account/:account_id[/][:country_code][/][:currency_type][/]

Request

Headers

Response

Status Codes

Headers

Body

MigrateLoad

POST /migrate/load[/]

Fields

Request

Headers

Body

Response

Status Codes

Headers

Body

MigratePromotionDetails

GET /migrate/promotion_details[/][:country_code][/]

Request

Headers

Response

Status Codes

Headers

Body

MigratePurchase

POST /migrate/purchase[/]

Fields

Request

Headers

Body

Response

Status Codes

Headers

Body

MigrateRedeemPromotion

POST /migrate/redeem/promotion[/]

Fields

Request

Headers

Body

Response

Status Codes

Headers

Body

MigrateReversal

POST /migrate/reversal[/]

Fields

Request

Headers

Body

Response

Status Codes

Headers

Body