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

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:
  • incorporation: address associated with business' incorporation
  • headquarters: main office
  • satellite: a non-headquarters office
  • mail_forwarding: address used to receive mail
  • home: a person's home address
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:
  • user_confirmed: user reviewed and confirmed normalized address as correct
  • user_denied: user reviewed and indicated normalized address is not correct
  • user_did_not_review: user was not shown the normalized address and asked to confirm or deny

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:
  • 1d, 2d, 3d, etc
  • 1w, 2w, 3w, etc
  • 1m, 2m, 3m, etc
  • 1y, 2y, 3y, etc
setup_by No String (32 chars) Who set-up the auto-billing:
  • payer: the payer set up and authorized auto-billing
  • merchant: the merchant set-up auto-billing on the payer's behalf

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:
  • true: indicates that this merchant collects sales tax for each transaction
  • false: indicates that this merchant does not collect sales tax for each transaction

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:
  • legal: this is the legal name of the company
  • dba: this is the Also Known As or Doing Business As name of the company

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"
   }
}

email

The email address associated with an entity. Usually passed in as a related_rbit of type = person.

Parameter Required Type Description
email 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"
       }
    }
  ]
}

external_account

The user’s external accounts, such as Facebook or Twitter.

Parameter Required Type Description
is_partner_account Yes String Possible values:
  • yes: this is an account controlled by you, the WePay partner.
  • no: this is not an account controlled by you, the WePay partner.
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:
  • free_form_entry: user entered or edited line item directly on invoice.
  • timed_billing_at_staff_rate: rate set per staff member and hours timed automatically.
  • timed_billing_at_task_rate: rate set per task and hours timed automatically.
  • timed_billing_at_project_rate: rate set per project and hours timed automatically.
  • hourly_billing_at_staff_rate: rate set per staff member and hours entered manually.
  • hourly_billing_at_task_rate: rate set per task and hours entered manually.
  • hourly_billing_at_project_rate: rate set per project and hours entered manually.
  • flat_project_amount: flat invoicing per project.

Example

{
    "description": "test",
    "item_price": 30.0,
    "quantity": 10,
    "amount": 10.00,
    "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
}