Rbit Types
The Risk API provides a way to communicate risk-related account and transaction level information between an application and WePay using rbits. An application and WePay use this information to improve its risk decision making process on both sides and provide better information to the user.
An rbit contains risk-related information about your users, their accounts, and their transactions. To create an rbit, you need to make the /rbit/create API call with the following required parameters:
Parameter | Required | Description |
type | Yes | A one word value describing the kind of risk information the rbit contains (e.g., type is set to phone for phone number). |
properties | Yes | A parameter set to the key value pair of properties for this type . The properties of the rbit will depend on the type . |
associated_object_type | Yes | Details of the associated_object_type parameter are listed in the /rbit/create documentation. |
associated_object_id | Yes | Details of the associated_object_type parameter are listed in the /rbit/create documentation. |
receive_time | Yes | Details of the receive_time parameter are listed in the /rbit/create documentation. |
source | Yes | Details of the source parameter are listed in the /rbit/create documentation. |
The following is a list of standard types and their properties associated with users and transactions that you can pass into the type
and properties
parameters respectively when making the /rbit/create call.
The different standard types of nodes that are associated with users, accounts, or transactions are defined below.
Rbit standard types
- address
- auto_billing
- business_description
- business_name
- event_or_conference
- external_account
- fundraising_event
- industry_code
- partner_service
- person
- phone
- transaction_details
Associated rbit structures
address
A mailing address associated with a user or account.
Rbits of type address should be sent either as a related rbit of type
= person
or as a top level rbit for an account (see example below).
Parameter | Required | Type | Description |
address | Yes | Address Structure | An address associated with a user or account |
address_type | No | String (255 chars) |
Possible values:
|
normalized_address | No | Address Structure | Normalized version of address . |
normalized_source | No | String (255 chars) | String with vendor for address normalization. |
normalized_address_status | No | String (255 chars) | Possible values:
|
Example arguments for /rbit/create
{
"associated_object_type": "account",
"associated_object_id": 123456788,
"receive_time": 1367958263,
"type": "address",
"source": "partner_database",
"properties": {
"address": {
"address1": "20 Main Street",
"city": "Sunnyvale",
"zip": "94085",
"state": "CA",
"country": "US"
}
}
}
auto_billing
If the transaction is set-up for auto-billing (where the users card is charged automatically every month), include this rbit to provide details of the auto-billing.
Parameter | Required | Type | Description |
autobill_setup_time | No | Integer (32 bits) | Unix timestamp when auto-bill was first set up or last updated by the user. |
payment_number | No | Integer (32 bits) |
If this is the first payment of the auto-billing, payment_number should be set to 1 . If the second, payment_number should be set to 2 , etc.
|
total_payments_scheduled | No | Integer (32 bits) |
The number of payments that are scheduled to be auto-billed. For example, if a payer is paying for an item over three installments, total_payments_scheduled should be set to 3 . If there is no scheduled end to the auto-billed payments, do not include this parameter.
|
payment_frequency | No | String (32 chars) |
Possible values: weekly , monthly , quarterly , and annually .
Alternately, you can specify the number of days / weeks / months / years as follows:
|
setup_by | No | String (32 chars) |
Who set-up the auto-billing:
|
Example arguments for /rbit/create
{
"associated_object_type": "account",
"associated_object_id": 123456,
"receive_time": 1367958263,
"type": "auto_billing",
"source": "user",
"properties": {
"autobill_setup_time": 1209600,
"payment_number": 1,
"total_payments_scheduled": 5,
"payment_frequency": "monthly",
"setup_by": "payer"
}
}
business_description
Rbts of type “business_description” should be sent as a top-level rbit for an account.
Parameter | Required | Type | Description |
business_description | Yes | String (10000 chars) | Text description of the business. |
number_of_employees | No | Integer (32 bits) | Number of employees employed by the business. |
sales_tax_liability_flag | No | Boolean | Possible values:
|
Example arguments for /rbit/create
{
"associated_object_type": "account",
"associated_object_id": 123456788,
"receive_time": 1367958263,
"type": "business_description",
"source": "user",
"properties": {
"business_description": "We sell produce to customers."
}
}
business_name
The business name associated with an account.
Parameter | Required | Type | Description |
business_name | Yes | String (255 chars) | The full name of the business. |
name_type | No | String (32 chars) | The kind of name used for the business.
There are two possible values for this parameter:
|
Example arguments for /rbit/create
{
"associated_object_type": "account",
"associated_object_id": 1234,
"receive_time": 1367958263,
"type": "business_name",
"source": "user",
"properties": {
"business_name": "Wefarm Company",
"name_type": "legal"
}
}
The email address associated with an entity. Usually passed in as a related_rbit
of type
= person
.
Parameter | Required | Type | Description |
Yes | String (255 chars) | Email address |
Example arguments for /rbit/create
{
"associated_object_type": "account",
"associated_object_id": 1234,
"receive_time": 1367958263,
"type": "person",
"source": "user",
"properties": {
"name": "Bill Clerico"
},
"related_rbits": [
{
"receive_time": 1367958263,
"type": "email",
"source": "user",
"properties": {
"email": "test@wepay.com"
}
}
]
}
event_or_conference
Information about an event (i.e. conference, trade show, festival) that can be passed as an rbit with a checkout or an account.
Parameter | Required | Type | Description |
name | Yes | String (255 chars) | Name of the event. |
category | No | String (255 chars) | Category of the event. Possible values include:
|
currency | No | String (3 chars) | The currency used at the event. (Default is USD .)
|
description | No | String (255 chars) | Description of the event. |
end_time | No | Timestamp | The UNIX time of when the event ends. |
event_time | No | Timestamp | The UNIX time of when the event starts. |
uri | No | String (2083 chars) | The user's profile URL on the external service. |
Example arguments for /rbit/create
{
"associated_object_type": "account",
"associated_object_id": 1234,
"receive_time": 1367958263,
"type": "event_or_conference",
"source": "partner_database",
"properties": {
"name": "Pepe Silvia",
"category": "conference",
"currency": "USD",
"description": "A conference on how to manage and organize a mail room.",
"end_time": 1399521651,
"event_time": 1399410291,
"uri": "http://www.example.com"
}
}
external_account
The user’s external accounts, such as Facebook or Twitter.
Parameter | Required | Type | Description |
is_partner_account | Yes | String | Possible values:
|
account_type | Yes | String (255 chars) |
Name of the provider of the account (for example, "facebook").
If this is an account controlled by you, set this parameter to the name of the company where the account was created.
Possible values: facebook , linkedin , klout , twitter , ebay , googleplus , yelp , and etsy .
|
user_id | No | String (255 chars) | The user's ID of the external account. |
uri | No | String (2083 chars) | The user's profile URL on the external service. |
create_time | No | Integer (64 bits) | The Unix timestamp when external account was created (unix seconds since Jan 1st 1970 UTC). |
modify_time | No | Integer (64 bits) | The Unix timestamp when external account was modified (unix seconds since Jan 1st 1970 UTC). |
following | No | Integer (32 bits) | The number of people the user is following (Twitter) or has in his/her circles (Google+). |
followers | No | Integer (32 bits) | The number of followers (Twitter) or the number of members in his/her circles (Google+). |
connections | No | Integer (32 bits) | The number of friends (Facebook) or connections (LinkedIn). |
feedback_scores_provided | No | Integer (32 bits) | Number of times this user has received feedback. |
feedback_score_percent_positive | No | Float | Percentage of feedback which is positive (for positive / negative scoring systems). |
feedback_average_score | No | Float | Average feedback score for this user (for star rating feedback systems) normalized between 0.0 (worst) and 1.0 (best). |
Example arguments for /rbit/create
{
"associated_object_type": "user",
"associated_object_id": 1234,
"receive_time": 1367958263,
"type": "external_account",
"source": "partner_database",
"properties": {
"is_partner_account": "no",
"account_type": "facebook",
"connections": 200,
"uri": "https://www.facebook.com/bill.clerico"
}
}
industry_code
A code from one of several sources that indicates the industry associated with the business.
Parameter | Required | Type | Description |
industry_code_type | Yes | String (32 chars) | Possible values: mcc , sic , and naics .
|
industry_code | Yes | String (32 chars) |
The industry code for the industry_type set. Either the MCC, SIC, or NAICS industry code.
|
industry_detail | No | String (1024 chars) | Additional text describing the industry code. For example, this may be category or actual drop-down text selected by the end user that maps to a particular industry code. |
Example arguments for /rbit/create
{
"associated_object_type": "account",
"associated_object_id": 123456788,
"receive_time": 1367958263,
"type": "industry_code",
"source": "user",
"properties": {
"industry_code_type": "mcc",
"industry_code": "2741",
"industry_detail": "Details of the industry"
}
}
fundraising_event
Information about an event that is the context for a donation transaction or donation account. It can therefore be passed as an rbit associated with a checkout or an account.
Parameter | Required | Type | Description |
name | Yes | String (255 chars) | Name of the fundraising event. |
event_time | No | Timestamp | The Unix time of when the event starts. |
giving_deadline | No | Timestamp | The Unix time of deadline for when donations will no longer be accepted. |
fundraising_goal | No | Decimal | The fundraising goal established by the event organizers |
currency | No | String (3 chars) |
The currency used.
Possible values: USD , CAD , and GBP .
Default: USD
|
uri | No | URI | URI that points to the fundraising event page |
Example arguments for /rbit/create
{
"associated_object_type": "checkout",
"associated_object_id": 1234,
"receive_time": 1367958897,
"type": "fundraising_event",
"source": "partner_database",
"properties": {
"name": "Red",
"event_time": 1399410291,
"giving_deadline": 1399410291,
"fundraising_goal": 5000,
"uri": "http://example.com/test"
}
}
partner_service
This type describes one type of service or product the user has signed up for on the partner site. This should be passed as a related rbit of the external_account rbit that contains partner site information. If the user is signed up for multiple services, you can pass multiple related rbits.
Parameter | Required | Type | Description |
service_name | Yes | String (1024 chars) | The name of the service or product the user has signed up for on the partner s site. |
service_monthly_cost | No | Decimal | Monthly cost of the service. If billed annually, provide the average monthly amount. |
currency | No | String (3 chars) |
The currency used.
Possible values: USD , CAD , and GBP .
Default: USD
|
modules_used | No | Array of partner_service |
Array of partner_services for each module the user has signed up for in the partner's site
|
Example arguments for /rbit/create
{
"associated_object_type": "user",
"associated_object_id": 1234,
"receive_time": 1367958263,
"type": "external_account",
"source": "partner_database",
"properties": {
"is_partner_account": "yes",
"account_type": "company name",
"connections": 200,
"uri": "https://www.companyname.com/bill.clerico"
},
"related_rbits": [
{
"receive_time": 1367958897,
"type": "partner_service",
"source": "partner_database",
"properties": {
"service_name": "Service Name",
"service_monthly_cost": 30
}
}
]
}
person
Information about a person associated with a user or account. It could be a person who does not have formal access to the user or account (e.g., an employee of a company who provided information).
Rbits of type person
are usually associated with the following related rbits: phone and address.
Parameter | Required | Type | Description |
name | Yes | String (255 chars) | The full name of the person |
birthdate | No | String (10 chars) | The birthdate of the person. Must be in YYYY-MM-DD format. i.e 1989-08-10 |
role | No | String (255 chars) | Possible values: employee , fundraiser , fundraising_team_captain , and other_third_party . |
Example arguments for /rbit/create
{
"associated_object_type": "account",
"associated_object_id": 1234,
"receive_time": 1367958263,
"type": "person",
"source": "user",
"properties": {
"name": "Bill Clerico"
},
"related_rbits": [
{
"receive_time": 1367958263,
"type": "tax_id",
"source": "user",
"note": "This is the ssn user provided.",
"properties": {
"tax_id": "087-97-8888",
"tax_id_country": "US",
"tax_id_type": "personal"
}
},
{
"receive_time": 1367958263,
"type": "email",
"source": "user",
"properties": {
"email": "test@wepay.com"
}
},
{
"receive_time": 1367958263,
"type": "address",
"source": "user",
"properties": {
"address": {
"address1": "380 Portage Avenue",
"city": "Palo Alto",
"zip": "94085",
"state": "CA",
"country": "US"
}
}
},
{
"receive_time": 1367958263,
"type": "phone",
"source": "user",
"note": "This is the phone number user provided.",
"properties": {
"phone": "+1-415-555-5555",
"phone_type": "work"
}
}
]
}
phone
A phone number associated with a user or account. Rbits of type phone should be sent either as a related rbit of type
= person
or as a top level rbit for an account (see example below).
Parameter | Required | Type | Description |
phone | Yes | String (32 chars) | Phone number, ideally including country code prefix (+1 for US) |
phone_type | No | String (32 chars |
Possible values: home , work , and mobile . |
Example arguments for /rbit/create
{
"associated_object_type": "account",
"associated_object_id": 123456788,
"receive_time": 1367958263,
"type": "phone",
"source": "user",
"properties": {
"phone": "+1-555-555-5555",
"phone_type": "home"
}
}
transaction_details
Information regarding a specific transaction.
Parameter | Required | Type | Description |
receipt_uri | No | String (2083 chars) | The buyer agreement or transactions page URL on the application's website or service (e.g. receipt page). It can be HTML, PDF, image, or any other type of file. |
itemized_receipt | No | Array of receipt_line_item structures | Array of receipt_line_item structures providing all the line item details of the transaction (including tax and shipping line items). |
terms_uri | No | String (2083 chars) | URL of the terms of service for the transaction. |
shipping_address | No | Address Structure | The shipping address for this transaction (if transaction is shipped). |
shipping_info | No | Array of shipping_info structures | Array of shipping_info structures that describe the shipment status. |
service_address | No | Address Structure | Optional address of where the service is consumed. |
terms_text | No | String (2083 chars) | Terms associated with the invoice or transaction. |
po_number | No | String (2083 chars) | Purchase order number. |
discount | No | String (2083 chars) | Discount (if any) on the order. |
note | No | String (10000 chars) | Optional note on the invoice or address. |
Example arguments for /rbit/create
{
"associated_object_type": "checkout",
"associated_object_id": 123456,
"receive_time": 1367958263,
"type": "transaction_details",
"source": "user",
"properties": {
"receipt_uri": "http://example.com/receipt-uri",
"terms_uri": "http://example.com/terms-uri",
"shipping_address": {
"address1": "Main Street",
"city": "Sunnyvale",
"state": "CA",
"country": "US",
"zip": "94085"
},
"shipping_info": [
{
"expected_delivery_time": 1397510245,
"shipping_time": 1397510245,
"carrier": "USPS",
"tracking_number": "YX-33333",
"tracking_uri": "http://www.example.com",
"actual_delivery_time": 1397510245
}
]
}
}
Receipt line item structure
Contains details about a specific line item on a receipt.
Parameter | Required | Type | Description |
description | Yes | String (1024 chars) | Line item description. Could be a normal line item, a discount line item, tax, or shipping. |
item_price | Yes | Decimal (64 bits) | Item price per unit. |
quantity | Yes | Decimal (64 bits) | Quantity of the line items. |
amount | Yes | Decimal (64 bits) | Amount (item_price x quantity) |
currency | No | String (3 chars) | The currency used.
Possible values: USD , CAD , and GBP .
Default: USD |
project_name | No | String (1024 chars) | Name of project this item is related to. If a separate "project" rbit is provided, this should match the project name in that rbit. |
service_billing_method | No | String (255 chars) |
Possible values:
|
Example
{
"description": "test",
"item_price": 30.0,
"quantity": 10,
"amount": 10.0,
"currency": "USD"
}
Shipping Info Structure
Contains details about a shipment of goods or services.
Parameter | Required | Type | Description |
expected_delivery_time | No | Integer (64 bit) | The Unix timestamp when goods or services are expected to be delivered (seconds since Jan 1st 1970 UTC). |
shipping_time | No | Integer (64 bit) | The Unix timestamp when goods have been shipped (seconds since Jan 1st 1970 UTC). |
carrier | No | String (255 chars) | The shipping carrier (USPS, FEDEX, etc). |
tracking_number | No | String (255 chars) | The tracking number for the shipping carrier. |
tracking_url | No | URL | The URL for the tracking information. |
actual_delivery_time | No | Integer (64 bit) | The Unix timestamp when goods or services were actually delivered (seconds since Jan 1st 1970 UTC). |
Example
{
"expected_delivery_time": 1397510245,
"shipping_time": 1397510245,
"carrier": "USPS",
"tracking_number": "YX-33333",
"tracking_url": "http://www.example.com",
"actual_delivery_time": 1397510245
}