Overview

DeepShield API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no "switch" for changing between modes, just use the appropriate key to perform a live or test transaction. Requests made with test mode credentials never hit the banking networks and incur no cost.


1.0 Authentication

Authenticate your account when using the API by including your secret API key in the request. You can manage your API keys in the Dashboard. Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

If you need to authenticate via bearer auth (e.g., for a cross-origin request), use -H "Authorization: Bearer sk_test_BQokikJOvBiI2HlWgH4olfQ2" instead of -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.


1.2 Errors

DeepShield uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xxrange indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with DeepShield's servers (these are rare).

Not all errors map cleanly onto HTTP response codes, however. When a request is valid but does not complete successfully (e.g., a card is declined), we return a 402 error code.

ATTRIBUTES


type

The type of error returned. Can be: api_connection_error, api_error, authentication_error, card_error, invalid_request_error, or rate_limit_error.


1.3 APIs


1.3.1 Create BUYER

Creates a new buyer profile for a customer to attach a wallet and bank account and track payments and rewards. 


ARGUMENTS

Email address

email

First name

first_name

Last name

last_name

Latitude location (optional)

latitude

Longitude location(optional)

longitude

profile_photo_url

Customer profile photo URL (optional)

phone_number

Phone number (optional)

Customer payment PIN. Secures customer payment. Must be entered every time the customer initiates a payment. (optional)

pin

 

public_token

account_id

Plaid public token (optional)

Plaid customer bank account id. (optional)


Returns

Returns the buyer object if the buyer was created successfully.

Returns an error if the buyer was not created successfully


Example

 

Request : 

curl -X POST https://sandbox.deepshield.co/api/v1/buyer \

 -d application_id=[Merchant Application ID] \

 -d secret=[Merchant Secret] \

 -d request_type=create_buyer_profile \

 -d email=”john.smith@gmail.com” \

 -d first_name=John \

 -d last_name=Smith

Response

{

 "id": 1,

 "merchant_profile_id": 4,

 "email": "john.smith@gmail.com",

 "first_name": "John",

 "last_name": "Smith",

 "unique_id": "@JohnSmith",

 "rank": 0,

 "amount_paid_in_period": 0.0,

 "amount_to_next_rank": 0,

 "next_rank_earning_deadline": "1970-01-01T00:00:00.000Z",

 "created_at": "2016-08-29T17:36:10.269Z",

 "updated_at": "2016-08-29T17:36:10.269Z"

}


1.3.2 UPDATE BUYER

Update buyer can be used to update an existing customer data.


ARGUMENTS

The ID for the buyer.

buyer_profile_id

Email address (optional)

email

First name (optional)

first_name

Last name (optional)

last_name

Customer latitude location (optional)

latitude

Customer longitude location (optional)

longtitude

Customer profile photo URL (optional)

profile_photo_url

Customer phone number (optional)

phone_number

Customer payment PIN (optional)

pin

Plaid public token (optional)

public_token

Customer bank account id (optional)

account_id


Returns

Returns the buyer object if the buyer was created updated.

Returns an error if the buyer was not updated successfully


Example

 

Request

curl -X POST https://sandbox.deepshield.co/api/v1/buyer \

 -d application_id=[Merchant Application ID] \

 -d secret=[Merchant Secret] \

 -d request_type=update_buyer_profile \

 -d buyer_profile_id=1 \

 -d email=”john.smith@gmail.com” \

 -d first_name=John \

 -d last_name=Smith

 

RESPONSE

{

 "id": 1,

 "merchant_profile_id": 4,

 "email": "john.smith@gmail.com",

 "first_name": "John",

 "last_name": "Smith",

 "unique_id": "@JohnSmith",

 "rank": 0,

 "amount_paid_in_period": 0.0,

 "amount_to_next_rank": 0,

 "next_rank_earning_deadline": "1970-01-01T00:00:00.000Z",

 "created_at": "2016-08-29T17:36:10.269Z",

 "updated_at": "2016-08-29T17:36:10.269Z"

}


1.3.3 Get Buyer Transactions

This API retrieves buyer transactions for the specified period


ARGUMENTS

The ID for the buyer.

buyer_profile_id

Start date (e.g. 01-01-2016)

date_from

End date (e.g. 12-31-2016)

date_to


Returns

Returns the list of transactions object if request was successful

Returns an error if request was unsuccessful


Example

Request

curl https://sandbox.deepshield.co/api/v1/buyer \

 -d application_id=[Merchant Application ID] \

 -d secret=[Merchant Secret] \

 -d request_type=get_wallet_transactions \

 -d buyer_profile_id=1 \

 -d date_from=”08-27-2016” \

 -d date_to=”08-27-2016”

RESPONSE

[

 {

   "id": 35,

   "wallet_id": 13,

   "created_at": "2016-08-27T00:18:39.820Z",

   "updated_at": "2016-08-27T00:18:39.820Z",

   "amount": "20.00",

   "transaction_type": "debit",

   "pending": false

 },

 {

   "id": 37,

   "wallet_id": 13,

   "created_at": "2016-08-27T00:19:25.479Z",

   "updated_at": "2016-08-27T00:19:25.479Z",

   "amount": "20.00",

   "transaction_type": "debit",

   "pending": false

 }

]


1.3.4 Add funds to walleT

This API initiates transfer of funds from the customer bank account to the wallet.


ARGUMENTS

The ID for the buyer

buyer_profile_id

The amount to add (e.g. 10.00)

amount


Returns

Returns the wallet if the transfer was successfully initiated

Returns error if the transfer failed to initiate


Example

Request

curl -X POST https://sandbox.deepshield.co/api/v1/pay \

 -d application_id=[Merchant Application ID] \

 -d secret=[Merchant Secret] \

 -d request_type=add_funds_to_wallet \

 -d buyer_profile_id=1 \

 -d amount=”10.00”

Response

{

 "id": 1,

 "merchant_profile_id": 4,

 "email": "john.smith@gmail.com",

 "first_name": "John",

 "last_name": "Smith",

 "unique_id": "@JohnSmith",

 "phone_number": "4087550324",

 "rank": 0,

 "created_at": "2016-08-23T16:52:33.637Z",

 "updated_at": "2016-08-24T00:55:40.092Z",

 "wallet": {

   "id": 13,

   "buyer_profile_id": 1,

   "merchant_profile_id": 4,

   "amount_available": "1085.00",

   "amount_pending": "1035.00",

   "negative_balance": false,

   "pending_available_date": "2016-09-01T00:37:17.168Z",

   "transaction_type": "credit",

   "suspended": false,

   "bank_account_connected": true,

   "created_at": "2016-08-23T16:52:33.651Z",

   "updated_at": "2016-08-29T20:50:28.261Z"

 }

}


1.3.5 Pay

This API lets a buyer pay the merchant


Arguments

The ID for the buyer

buyer_profile_id

The total payment amount.

total_price

Customer payment PIN (optional)

pin

Customer latitude location (optional)

latitude

Customer longitude location(optional)

longitude

Additional gratuity above the total_amount (optional)

gratuity


Returns

Returns invoice and buyer profile if transaction was successful

Returns error if transactions was unsuccessful


Example

Request

curl -X POST https://sandbox.deepshield.co/api/v1/pay \

 -d application_id=[Merchant Application ID] \

 -d secret=[Merchant Secret] \

 -d request_type=pay \

 -d buyer_profile_id=1 \

 -d total_price=”10.00” \

 -d pin=”1234” \

 -d source=0

RESPONSE

{

 "id": 13,

 "buyer_profile_id": 1,

 "merchant_profile_id": 4,

 "total_price": "10.00",

 "currency": "USD",

 "payment_source": "cus_93poDFoUl7wrU8",

 "status": 5,

 "qrcode_id": "yxj7dXiMxl8fdaOATJ5g6g",

 "order_id": 16,

 "sales_tax": "0.00",

 "gratuity": "0.00",

 "convenience_fee": "0.00",

 "created_at": "2016-08-29T20:29:21.416Z",

 "updated_at": "2016-08-29T20:29:21.416Z",

 "buyer_profile": {

   "id": 1,

   "merchant_profile_id": 4,

   "email": "john.smith@gmail.com",

   "first_name": "John",

   "last_name": "Smith",

   "unique_id": "@JohnSmith",

   "phone_number": "4087550324",

   "rank": 0,

   "created_at": "2016-08-23T16:52:33.637Z",

   "updated_at": "2016-08-24T00:55:40.092Z"

 }

}


1.3.6 Redeem Reward

This API is should be called when a customer redeems the reward they have already earned


Arguments

The ID for the buyer

buyer_profile_id

The ID of the reward to redeem

reward_id


Returns

The reward object if the operation was successful

An error if the operation failed


Example

Request

curl -X POST https://sandbox.deepshield.co/api/v1/pay \

 -d application_id=[Merchant Application ID] \

 -d secret=[Merchant Secret] \

 -d request_type=redeem_reward \

 -d buyer_profile_id=1 \

 -d reward_id=3

Response

{

 "id": 3,

 "buyer_profile_id": 1,

 "merchant_profile_id": 4,

 "points_earned": 1000,

 "points_milestone": 1000,

 "points_earned_per_unit": 100,

 "expiration_date": "2016-11-23T07:59:59.999Z",

 "status": 2,

 "reward": "Free Scented Candle",

 "created_at": "2016-08-24T18:42:30.420Z",

 "updated_at": "2016-08-29T21:32:39.834Z"

}

 


1.4 Data Structures


1.4.1 Buyer Profile

{

id - The ID for the buyer.

merchant_profile_id - The ID for the merchant profile.

email - The email for the buyer.

first_name - The first name for the buyer.

last_name - The last name for the buyer.

unique_id - The system-generated global unique ID for the buyer.

phone_number - The phone number for the buyer.

created_at - The creation date for this buyer.

updated_at - The last updated date for this buyer.

wallet - The wallet associated with this buyer. See Wallet.

rewards - The earned rewards for this buyer. See Reward.

}

1.4.2 Wallet

{

id - The ID for the wallet.

buyer_profile_id - The ID for the buyer that owns this wallet.

merchant_profile_id - The associated ID of the merchant for this wallet.

amount_available - The funds that are available to use to pay the merchant.

amount_pending - The funds that are pending settlement and are not immediately available for use.

negative_balance - Whether the amount available represents a negative balance.

pending_available_date - The estimated availability date of the earliest settlement of any pending funds.

transaction_type - The transaction type of the next available pending funds. (e.g. credit)

suspended - Whether this wallet is suspended from payment.

bank_account_connected - Whether this wallet is connected to a bank account.

created_at - The creation date for this wallet.

updated_at - The last updated date for this wallet.

}

1.4.3 Transaction

{

id - The ID for the transaction.

wallet_id - The associated ID of the wallet for this transaction.

created_at - The creation date for this transaction.

updated_at - The last updated date for this transaction.

amount -The amount of this transaction

transaction_type - The transaction type of this transaction. (e.g. credit, debit)

pending - Whether this transaction is pending settlement.

pending_available_date - The estimated pending settlement date for this transaction.

}

1.4.4 Invoice

{

id -The ID for the invoice.

buyer_profile_id - The ID for the buyer that made this payment.

merchant_profile_id - The associated ID of the merchant that received the payment.

total_price - The amount of the payment.

currency - The three-letter ISO currency code representing the currency in which the payment was made.

payment_source -The customer payment source for this invoice.

status -The payment status for the invoice (e.g. paid, refunded)

qrcode_id -The unique payment ID for the invoice.

order_id -The order ID associated with the invoice and merchant.

sales_tax -The applicable sales tax amount specified by the merchant.

gratuity -The gratuity added to the invoice payment.

convenience_fee -Any convenience fee for this invoice (if applicable).

created_at -The creation date for this invoice.

updated_at - The last updated date for this invoice.

buyer_profile -The buyer that made this invoice payment. See Buyer Profile.

}

1.4.5 Reward

{

id - The ID for the reward

buyer_profile_id - The ID for the buyer that owns this reward

merchant_profile_id - The associated ID of the merchant this reward applies to.

points_earned - The points earned toward this reward.

points_milestone - The points required to earn this reward

points_earned_per_unit - The points earned per unit for this reward

expiration_date - The redemption expiration date for this reward.

status - The reward status (e.g. ongoing, available, redeemed, expired)

reward - The reward earned when the reward milestone is met.

created_at - The creation date for this reward.

updated_at - The last updated date for this reward.

}