ubivar

Ubivar node.js bindings

Ubivar is an API that takes over the hassle of screening e-payment for frauds.

Ubivar routes e-commerce transactions given their risk. By default the three routing outcomes are rejection, manual verification and acceptance. And the two elementary resources are the transactions and the labels. Transactions are online sales pushed to your payment gateway and labels define the a posteriori truth about each transaction, i.e. {fraud, non-fraud}.

Using Ubivar simply requires an access token. Then the bindings provide the hooks to send and receive resources to the API. For each transaction that Ubivar receives, it calculates a routing. Later, as you review manually some of the transactions or as you receive fraud notifications, you label those transactions as fraud.

Quick Start

Install the nodejs binding of ubivar from npm.

npm install ubivar

Initialize the binding with your API access token:

var Ubivar    = require("ubivar")
  , ubivar    = new Ubivar("YOUR_API_ACCESS_TOKEN")

A. Send transactions

ubivar.transactions.create({
  "user_id"     : "test_phahr3Eit3_123"           // your client's id
, "user_email"  : "[e-mail]" // your client email
, "gender"      : "M"                             // your client's gender
, "first_name"  : "John"                          // your client's first name
, "last_name"   : "Doe"                           // your client's last name
, "type"        : "sale"                          // the transaction type
, "status"      : "success"                       // the transaction status 
, "order_id"    : "test_iiquoozeiroogi_123"       // the shopping cart id
, "tx_id"       : "client_tx_id_123"              // the transaction id 
, "tx_timestamp": "2015-04-13 13:36:41"           // the timestamp of this transaction
, "amount"      : "43210"                         // the amount in cents
, "payment_method":{
    "bin"       : "123456"                        // the BIN of the card
  , "brand"     : "Mastercard"                    // the brand of the card
  , "funding"   : "credit"                        // the type of card
  , "country"   : "US"                            // the card country code
  , "name"      : "M John Doe"                    // the card holder's name
  , "cvc_check" : "pass"                          // the cvc check result
},"billing_address":{
    "line1"     : "123 Market Street"             // the billing address
  , "line2"     : "4th Floor"                       
  , "city"      : "San Francisco"
  , "state"     : "California"
  , "zip"       : "94102"
  , "country"   : "US"
},"ip_address"  : "1.2.3.4"                       // your client ip address
, "user_agent"  : "Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36"                        // your client's user agent
}, function(err, res){

  if(err) return err 
  // something unexpected occurred

  txId          = res.data[0].id 
  // keep track of the transaction id 
})

B. Retrieve routing

ubivar.routing.retrieve(txId, function(err, res){

  if(err) return err
  // something unexpected occurred

  status        = res.data[0].status
  // the routing, e.g. {pending, green, orange, red}
})

C. Label as fraud

ubivar.labels.retrieve(txId, {"status": "is_fraud"}, function(err, res){

  if(err) return err
  // something unexpected occurred

  status        = res.data[0].status
  // the label of the transaction
})

Resources, actions, and arguments

Every resource is accessed via your ubivar instance and accepts an optional callback as the last argument. In the matrix below we list the resources (rows), the actions (columns) and the arguments (cells). The full documentation is available at https://ubivar.com/docs/nodejs.

Resource	C	R	U	D	L	Summary	Test Specs
Accounts	{}	id	{}	id	{}
Items	{}	id	{}	id	{}
Labels	{}	id	{}	id	{}
Login	{}	id		id	{}
Logout	{}	id		id	{}
Me		_	{}
Routing		id	{}		{}
Transactions	{}	id	{}	id	{}

• C: Create
• R: Retrieve
• U: Update
• D: Delete
• L: List
• {}: JSON with query parameters

Filter parameters

Filter	Default	Example	Description
start_after		{"start_after":10}	id after the one specified
end_before		{"end_before":10}	id before the one specified
limit	10	{"limit":10}	At most 10 returned results
gt		{"id":{"gt":10}}	id greater than 10
gte		{"id":{"gte":10}}	id greater than or equal
lt		{"id":{"lt":10}}	id less than
lte		{"id":{"lte":10}}	id less than or equal

Configuration

Extend this ubivar instance with a new resource whose accessibility is controlled by access rights.

var Ubivar    = require("ubivar")
  , ubivar    = new Ubivar("YOUR_API_ACCESS_TOKEN")

ubivar.extend("geoip") // extend with 

Change API access token dynamically:

ubivar.set("auth", "your-api-token")

Define timeout of the binding:

ubivar.set("timeout", 20000) // in ms`, node's default is `120000ms`

Development

To run the tests, you will need a Ubivar test API key (from your Ubivar dashboard)

export UBIVAR_TEST_TOKEN="your-test-api-key"
npm install -g mocha
npm test

Note: on Windows, use SET instead of export for setting the UBIVAR_TEST_TOKEN environment variable.

Issues and feature requests

Author

Originally inspired from stripe-node. Developed and maintained by Fabrice Colas ([e-mail]) for Ubivar.