Kernel Documentation


The value.io kernel provides RESTful JSON API access to the following resources:

Direct Processor Destinations

  • TSYS
  • Litle
  • Mercury
  • Heartland Payment Systems
  • SecureNet
  • Sage Payments US
  • Stripe

Gateway Destinations

  • Inspire Commerce
  • Network Merchants (NMI)
  • USAePay
  • Authorize.Net

Custom Destinations

  • PassThrough (build your own)

Payment Cards:

  • Secure Input
  • Single Use Tokens
  • Destination Agnostic Vaulting

Payments:

  • Transact With Single Use or vaulted card against any destination

Security: SSL, Authentication, & Authorization

  • The value.io api operates over HTTPS only
  • All requests requiring authentication must use HTTP Basic Authentication with :token.
  • Endpoint authorization is based on 3 primary token roles: admin, pci, & write-only.
  • Tokens with role admin are able to read and write all resources but are only returned masked card data.
  • Tokens with role pci are able to read card data without masking.
  • Tokens with role write-only are used in public facing applications by clients entering credit_card and payment data.
  • GETs to /payments may be made using admin tokens.
  • GETs to /credit_cards may be made using admin or pci tokens.
  • POSTs and PUTs to /payments and /credit_cards may be made using write-only or admin tokens.
  • Requests to /destinations be made using admin tokens.
  • You can obtain credentials by logging in and viewing your current accounts and associated tokens on your dashboard.
  • All operations, such as credit_card creation, are scoped within the authenticated account.

API Responses

Response Definition
HTTP 200 OK
HTTP 202 Accepted for processing
HTTP 401 Unauthorized returned by the api for authentication and authorization errors.
HTTP 404 Not Found returned if a page or a resource could not be found.
HTTP 422 Unprocessable Entity returned for errors during record save.
HTTP 500 Error

Demo

An easy way to observe the value.io kernel in action is by trying the secure value.js payment form:


Destination Configuration

pass-through
Instructions


Configure the endpoint_uri parameter with the uri of your backend processor. The following values may be used for testing which will return the passed pass_through_payload uninterpolated:
test_uncertified_backend,
test_certified_backend_success,
test_certified_backend_failure,

Configure the options parameter with:
http_method(optional): HTTP verb for your HTTP based payment service. Defaults to POST which is currently the only method supported
content_type(optional): The value for the HTTP 'Content-Type' header. Defaults to application/json
basic_auth_username(optional): If provided will be used in HTTP Basic Authentication header
basic_auth_password(optional): If provided will be used in HTTP Basic Authentication header
basic_auth_token(optional): If provided will be used in HTTP Basic Authentication header
ssl_verify(optional): Can be provided with a value of 'none' if value.io environment is not production.
access_token(optional): Adds 'AccessToken' HTTP header.
location_token(optional): Adds 'LocationToken' HTTP header.
soap_action(optional): Adds 'SOAPAction' HTTP header.
content_length(optional): Adds and calculates 'Content-Length' HTTP header for interpolated message body if 'true'.

In posts to payments using this destination include a pass_through_payload string
include the following tokens:

$credit_card.number$,
$credit_card.month$, (m)
$credit_card.year$, (yyyy)
$credit_card.month.mm$, (mm)
$credit_card.year.yy$, (yy)
$credit_card.cvv$,
$credit_card.first_name$,
$credit_card.last_name$,
$credit_card.email$,
$credit_card.address1$,
$credit_card.address2$,
$credit_card.city$,
$credit_card.state$,
$credit_card.country$,
$credit_card.phone$,
$credit_card.zip$

Note: Because the PassThrough destination sends out sensitive data, new instances must be certified by Inspire Commerce prior to processing payments.
When sending transactions to custom end points, 'status: success', means that a payload was sent, and a response was received. It does not represent the success or failure of the actual transaction. This would need to be extracted from the response body.

Configuraiton Options

endpoint_uri
options: (http_method, content_type, basic_auth_username, basic_auth_password, basic_auth_token, ssl_verify, timeout, access_token, location_token, soap_action, content_length)

terminal
Instructions


Configuraiton Options

secure-net
Instructions


* Sign up at http://www.securenet.com/

Configuraiton Options

secure_net_id
secure_key

elavon
Instructions

Configuraiton Options

my_virtual_merchant_id
my_virtual_merchant_user_id
my_virtual_merchant_pin

mercury
Instructions


Configure the Mercury destination with your Mercury merchant_id and password.
Your Mercury account must be configured for MercuryPay MToken support.

Configuraiton Options

merchant_id
password

litle
Instructions

Configuraiton Options

login
password
merchant_id

sage
Instructions


Setting up the Sage Payments Gateway for InspirePay is easy. In your
welcome letter from Sage Payments, you will only need two pieces of
information, your Merchant ID, and your Merchant Key. Again, both
should be in your welcome email letter. If you lost it, you will
need to call Sage Gateway Support.

Configuraiton Options

merchant_id_number
merchant_id_key

authorize-net
Instructions


In order to setup Authorize.net

* Log into your merchant area at Authorize.net.
* Click on 'Account,' from the top menu.
* Click on 'API Login ID and Transaction Key' and generate a Login ID and Transaction Key.
* Use these to connect value.io to Authorize.net.

NOTE: if you already have a shopping cart connected to Authorize.net
with a Login ID and Transaction Key, through their API... even if you do
not check the box to, 'Disable Old Transaction Key(s)' the keys may be
disabled automatically. Update all systems with your newly generated
Login ID/Transaction Key Pair. The last thing we want is for your
connecting InspirePay to crash your other shopping cart processing
systems because of Authorize.net.

Configuraiton Options

api_login_id
transaction_key

heartland
Instructions

Configure the Heartland destination by using the secret_api_key provided within the Heartland Payment Systemts Portico or Secure Submit Systems.

Configuraiton Options

secret_api_key

payeezy
Instructions


Retrieve from Payeezy Global Gateway E4 inside:
"Terminal Gateway ID" and "Terminal Password."

Configuraiton Options

terminal_gateway_id
terminal_password

inspire
Instructions


While connecting with Inspire Commerce is as easy as entering your
username and password into the fields below, there is a 'proper' way to
set up the gateway for enhanced security.

* Log into Inspire Commerce, and select 'Options' from the left menu.
* Select 'User Accounts.'
* Select, 'Click Here To Add A New User Account.'
* Setup the new user information with an email account that you have access to. You will need it to set the password using a system generate email.
* Make sure to select ONLY 'API Access' from the permissions section below, and create user.
* The system will send you an email to verify ownership with a link to set your password.
* Use the username and password of this new user for proper security when setting up InspirePay.

Configuraiton Options

login
password

stripe
Instructions


* Log Into Stripe, Select 'your account > account settings' from the menu.
* Select 'API Keys,' and copy your 'Live Secret Key.'
* Paste your *secret key* into the field below.

Configuraiton Options

live_secret_key

usa-epay
Instructions


Aquire credentials to access http://www.usaepay.com/developer and request sandbox access. From the sandbox system at https://sandbox.usaepay.com/login create a source with no pin and uncheck 'test'. Configure the destination with the source key.

Configuraiton Options

source_key


API Endpoints

 

Uptime

GET /ping
Description

Hit the api without any credentials. This is the only api endpoint which will succeed without credentials.

Response
Data
time
The time of day
Examples
curl https://api.value.io/v1/ping
                      
GET /pong
Description

Hit the api with credentials. All requests must be https and provide account_name:token_uuid as http basic auth credentials to succeed.

Request
Headers
Authorization Basic account:token
Examples
curl \
  -i \
  -u "$account:$token" \
  https://api.value.io/v1/pong
                      

 

Secure Documents

GET /secure_documents
Description

Get a listing of secure document records.

Request
Headers
Authorization Basic account:token (requires token with admin or pci role)
Params
page
The current pagination page
Response
Headers
Link The next page
Data
secure_documents
Array of secure_document objects
Examples
curl https://api.value.io/v1/secure_documents
                      
POST /secure_documents
Description

Create a new secure document record.

Request
Headers
Authorization Basic account:token (requires token with admin or write_only role).
Params
secure_document
identifier (optional)
A user defined identifier which can be used for subsequent GET requests. must be unique in the scope of the current account. if an identifier is not passed one will be generated and returned.
data
The data to be securely stored
Response
Data
secure_document
The secure document record
Examples
curl \
    -i \
    -u "$account:$token" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -X POST \
    -d@- \
    "https://api.value.io/v1/secure_documents" <<-__
      {"secure_document":{"data": "{'a_secure_key': 'a_secure_value'}"}}
                      
GET /secure_documents/:id
Description

Get a secure document object.

Request
Headers
Authorization Basic account:token (requires token with admin or pci role)
Params
id
ID of secure document record
Response
Data
secure_document
The secure document record
Examples
curl \
    -i \
    -u "$account:$token" \
    https://api.value.io/v1/secure_documents/:id

                      
DELETE /secure_documents/:id
Description

Destroy a secure document record

Request
Headers
Authorization Basic account:token (requires token with admin role).
Params
id
The identifier for the secure_document record to be destroyed.

 

Credit Cards

GET /credit_cards
Description

Get a listing of credit card records.

Request
Headers
Authorization Basic account:token (requires token with admin or pci role)
Params
page
The current pagination page
Response
Headers
Link The next page
Data
credit_cards
Array of credit_card objects
Examples
curl https://api.value.io/v1/credit_cards
                      
POST /credit_cards
Description

Create a new credit card record.

Request
Headers
Authorization Basic account:token (requires token with admin or write_only role).
Params
credit_card
identifier (optional)
A user defined identifier which can be used for subsequent GET requests. must be unique in the scope of the current account. if an identifier is not passed one will be generated and returned.
vaulted (optional)
Vault the card for use on future purchases. The default is false.
brand (required)
The brand of the credit card: visa, master, american_express, discover, diners_club, jcb, switch, solo, dankort, maestro, forbrugsforeningen, or laser.
number (required)
The credit card number
cvv (optional)
The credit card security code
month (required)
The credit card expiration month
year (required)
The credit card expiration year
first_name (required)
The credit card holder's first name
last_name (required)
The credit card holder's last name
address1 (optional)
Billing address street line 1
address2 (optional)
Billing address street line 2
city (optional)
Billing address city
state (optional)
Billing address state
zip (optional)
Billing address zip
country (optional)
Billing address country
email (optional)
The credit card holder's email
phone (optional)
The credit card holder's phone
ip (optional)
The ip address of the device that credit card data was entered on.
data (optional)
A hash of abitrary key:val pairs you would like to store in the credit card record.
Response
Data
credit_card
The credit card record
Examples
curl \
    -i \
    -u "$account:$token" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -X POST \
    -d@- \
    "https://api.value.io/v1/credit_cards" <<-__
      {"credit_card":{"brand": "visa", "number":"4242424242424242","cvv":"123","month":4,"year":2025,"first_name":"Terry","last_name":"Doe"}}
__
                      
GET /credit_cards/:id
Description

Get a credit card object.

Request
Headers
Authorization Basic account:token (requires token with admin or pci role)
Params
id
ID of credit card record
Response
Data
credit_card
The credit card record
Examples
curl \
    -i \
    -u "$account:$token" \
    https://api.value.io/v1/credit_cards/:id

                      
PUT /credit_cards/:id
Description

Generally archives card and create new card with passed parameters. If only identifier or only cvv is passed then the card will be updated without archiving. Can also be used with provision_single_use_token: 'true' to create a new single use token without archiving/recreating or otherwise modifying.

Request
Headers
Authorization Basic account:token (requires token with admin or write_only role)
Params
credit_card
provision_single_use_token (optional)
Create a new single use token for the credit card without archiving. All other credit_card parameters are ignored if true. The default is false.
identifier (optional)
A user defined identifier which can be used for subsequent GET requests. Must be unique in the scope of the current account. If an identifier is not passed one will be generated and returned.
vaulted (optional)
Vault the card for use on future purchases. The default is false.
brand (optional)
The brand of the credit card: visa, master, american_express, discover, diners_club, jcb, switch, solo, dankort, maestro, forbrugsforeningen, or laser.
number (optional)
The credit card number
cvv (optional)
The credit card security code
month (optional)
The credit card expiration month
year (optional)
The credit card expiration year
first_name (optional)
The credit card holder's first name
last_name (optional)
The credit card holder's last name
address1 (optional)
Billing address street line 1
address2 (optional)
Billing address street line 2
city (optional)
Billing address city
state (optional)
Billing address state
zip (optional)
Billing address zip
country (optional)
Billing address country
email (optional)
The credit card holder's email
phone (optional)
The credit card holder's phone
ip (optional)
The ip address of the device that credit card data was entered on
data (optional)
A hash of abitrary key:val pairs you would like to store on with the credit card. The values are all stored in encypted form.
Response
Data
credit_card
The credit card record
Examples
curl \
  -i \
  -u "$account:$token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -X PUT \
  -d@- \
  "https://api.value.io/v1/credit_cards/:id" <<-__
    {"credit_card":{"month":7}}
__

                      
DELETE /credit_cards/:id
Description

Archive card_card record

Request
Headers
Authorization Basic account:token (requires token with admin role).
Params
id
The identifier for the credit_card record to be archived.

 

Destinations

GET /destinations
Description

Get a list of configured destinations for the authenticated account

Request
Headers
Authorization Basic account:token (requires token with admin role)
Response
Data
destinations
Array of destination records
POST /destinations
Description

Create a new destination for the authenticated account.
ALL METHODS ON /destinations REQUIRE A TOKEN WITH THE ADMIN ROLE.

Request
Headers
Authorization Basic account:token (requires token with admin role)
Params
destination
kind (required)
Which destination kind to create
config (required)
A hash of auth credentials for the destination.
ref: $api/v1/destinations/details
payments_include_address (optional)
A boolean indicating whether or not to include credit card billing address with card details. Gateway's such as Sage require this. Review your gateway's AVS configuration options when enabling this. The default is false.
payment_address_defaults_to_account (optional)
A boolean indicating whether or not to use the account's address as a payments billing address if the credit card record does not contain an address and payments_include_address is true. The default is false.
Response
Data
destination
The destination record
Examples
curl \
    -i \
    -u "$account:$token" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -X POST \
    -d@- \
    "https://api.value.io/v1/destinations" <<-__
      {"destination":{"kind":"inspire","identifier":"4242","config":{"live_secret_key":"42"}}}
__
                      
GET /destinations/:id
Description

Get a configured destination for the authenticated account with an identifier.
ALL METHODS ON /destinations REQUIRE A TOKEN WITH THE ADMIN ROLE

Request
Headers
Authorization Basic account:token (requires token with admin role)
Params
id
The destination identifier
Response
Data
destination
The destination record
Examples
curl \
  -i \
  -u "$account:$token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -X GET \
  "https://api.value.io/v1/destinations/:id"

                      
PUT /destinations/:id
Description

Get a configured destination for the authenticated account with an identifier archive destination and create a new destination with passed parameters.

Request
Headers
Authorization Basic account:token (requires token with admin role)
Params
destination
kind (required)
Which destination kind to create
config (required)
A hash of auth credentials for the destination.
ref: $api/v1/destinations/details
payments_include_address (optional)
A boolean indicating whether or not to include credit card billing address with card details. Gateway's such as Sage require this. Review your gateway's AVS configuration options when enabling this. The default is false.
payment_address_defaults_to_account (optional)
A boolean indicating whether or not to use the account's address as a payments billing address if the credit card record does not contain an address and payments_include_address is true. The default is false.
Examples
curl \
  -i \
  -u "$account:$token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -X PUT \
  -d@- \
  "https://api.value.io/v1/destinations/:id" <<-__
    {"destination":{"config":{"live_secret_key":42.0}}}
__

                      
DELETE /destinations/:id
Description

Archives a destination

Request
Headers
Authorization Basic account:token (requires token with admin role)
Params
id
The destination identifier

 

Payments

GET /payments
Description

Returns a list of payment records for the authenticated account

Request
Headers
Authorization Basic account:token (requires token with admin role)
Response
Headers
Link The absolute url of the next page of results
Data
destination
The destination record
POST /payments
Description

Creates a new payment record for the authenticated account

Request
Headers
Authorization Basic account:token (requires token with admin or write_only role)
Params
payment (required)
The payment to be created
destination (optional)
An id or custom identifier of a previously created destination the default is the first destination associated with the account.
credit_card (optional)
An identifier of a previously created credit card. required for purchase and authorize unless card_data param provided (see below).
amount (required)
A string representing the amount to charge in dollars.cents. example "42.42"
kind (optional)
Purchase, capture, authorize, refund purchase is the default.
transact (optional)
Weather or not to perform the transaction. the default is true
refunded_payment
A payment id from a previously created payment to refund
authorized_payment
A payment id from a previously created authorize payment to capture
require_cvv (optional)
Require that the credit card has a cvv value. false is the default.
currency (optional)
The currency of the amount. USD is the default.
test (optional)
Use the destination's test sandbox. false is the default.
first_name (optional)
The payer's first name
last_name (optional)
The payer's last name
address1 (optional)
Billing address street line 1
address2 (optional)
Billing address street line 2
city (optional)
Billing address city
state (optional)
Billing address state
zip (optional)
Billing address zip
country (optional)
Billing address country
email (optional)
The credit card holder's email
phone (optional)
The credit card holder's phone
ip (optional)
The ip address of the device that credit card data was entered on
data (optional)
A hash of abitrary key:val pairs you would like to store on with the payment.
credit_card (optional)
Card data may optionally be passed instead of a previously vaulted card identifier
vaulted (optional)
Vault the card for use on future purchases. the default is false
identifier (optional)
A user defined identifier which can be used for subsequent GET requests. Must be unique in the scope of the current account. if an identifier is not passed one will be generated and returned.
brand (required)
The brand of the credit card: visa, master, american_express, discover, diners_club, jcb, switch, solo, dankort, maestro, forbrugsforeningen, or laser.
number (required)
The credit card number
cvv (optional)
The credit card security code
month (required)
The credit card expiration month
year (required)
The credit card expiration year
first_name (required)
The credit card holder's first name
last_name (required)
The credit card holder's last name
address1 (optional)
Billing address street line 1
address2 (optional)
Billing address street line 2
city (optional)
Billing address city
state (optional)
Billing address state
zip (optional)
Billing address zip
country (optional)
Billing address country
email (optional)
The credit card holder's email
phone (optional)
The credit card holder's phone
ip (optional)
The ip address of the device that credit card data was entered on
data (optional)
A hash of abitrary key:val pairs you would like to store on with the credit card.
Response
Data
payment
the payment record
Examples
# Simple payment using credit card data directly.
 curl \
    -i \
    -u "$account:$token" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -X POST \
    -d@- \
    "https://api.value.io/v1/payments" <<-__
      {"payment":{"amount":"42.42"},"credit_card":{"brand":"visa","number":"4111111111111111","cvv":"234","month":4,"year":2020,"first_name":"Phill","last_name":"Yourbank"}}
__

# Advanced payment using credit card token from /credit_cards, SecureForm, or SecureField.
curl \
    -i \
    -u "$account:$token" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -X POST \
    -d@- \
    "https://api.value.io/v1/payments" <<-__
      {"payment":{"amount":"42.42","credit_card":"credit_card-identifier-or-id"}}
__


#d Advanced showing addition of destination parameter.
curl \
    -i \
    -u "$account:$token" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -X POST \
    -d@- \
    "https://api.value.io/v1/payments" <<-__
      {"payment":{"amount":"42.42","destination":"destination-identifier-or-id","credit_card":"credit_card-identifier-or-id"}}
__
                      
GET /payments/:id
Description

Get a payment record for the authenticated account with an identifier

Request
Headers
Authorization Basic account:token (requires token with admin role)
Params
id
The payment identifier
Response
Data
payment
The payment record
Examples
curl \
  -i \
  -u "$account:$token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -X GET \
  "https://api.value.io/v1/payments/:id"

                      
PUT /payments/:id
Description

Transact or void a previously created payment

Request
Headers
Authorization Basic account:token (requires token with admin or write_only role)
Params
payment (required)
The payment to be modified
kind (required)
Either transact or void. Transact processes a previously created but untransacted payment. Void voids a previously created payment.
credit_card (optional)
An identifier of a previously created credit card. Required for transact unless card_data param provided (see below).
credit_card (optional)
Card data may optionally be passed instead of a previously vaulted card identifier
vaulted (optional)
Vault the card for use on future purchases. The default is false
identifier (optional)
A user defined identifier which can be used for subsequent GET requests. Must be unique in the scope of the current account. If an identifier is not passed one will be generated and returned.
brand (required)
The brand of the credit card: visa, master, american_express, discover, diners_club, jcb, switch, solo, dankort, maestro, forbrugsforeningen, or laser.
number (required)
The credit card number
cvv (optional)
The credit card security code
month (required)
The credit card expiration month
year (required)
The credit card expiration year
first_name (required)
The credit card holder's first name
last_name (required)
The credit card holder's last name
address1 (optional)
Billing address street line 1
address2 (optional)
Billing address street line 2
city (optional)
Billing address city
state (optional)
Billing address state
zip (optional)
Billing address zip
country (optional)
Billing address country
email (optional)
The credit card holder's email
phone (optional)
The credit card holder's phone
ip (optional)
The ip address of the device that credit card data was entered on
data (optional)
A hash of abitrary key:val pairs you would like to store on with the credit card.
Response
Data
payment
the payment record
Examples
curl \
  -i \
  -u "$account:$token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -X PUT \
  -d@- \
  "https://api.value.io/v1/payments/:id" <<-__
    {"payment":{"kind":"transact"}}
__
                      

Inspire Commerce © 2017, all rights reserved.