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. Please be sure to review our Risk Certification guide for more information on WePay’s risk management.

The different standard types of nodes that are associated with users, accounts, or transactions are defined below.

Rbit standard types

Associated rbit structures

An rbit contains risk-related information about your users, their accounts, and their transactions. To create an rbit, you can make the /rbit/create API call. Alternatively, you can create rBits embedded in another request.

The above list of standard types and their properties associated with users and transactions can be passed into the type and properties parameters respectively when creating independent or embedded rBits.

acquisition_channel

This type describes how a user or account was first acquired by your platform.

Parameter Required Type Description
acquisition_channel_type Yes String (255 chars) Standard values include:
  • website_organic
  • website_paid_advertising
  • from_payer_to_third_party
  • website_affiliate
  • outbound_sales_call
referring_uri No String (2083 chars) If channel is website, the URI that referred the user.
affiliate_name No String (1024 chars) If affiliate that referred the user.

Example arguments for /rbit/create

{
    "associated_object_type": "account",
    "associated_object_id": 1234,
    "receive_time": 1367958897,
    "type": "acquisition_channel",
    "source": "partner_database",
    "properties": {
        "acquisition_channel_type": "website_organic",
        "referring_uri": "http://example.com/test"
    }
}

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."
    }
}
Parameter Required Type Description
business_type No String (255 chars) Possible values:
  • sole_proprietorship
  • partnership
  • llc
  • s_corp
  • c_corp
  • non_profit
  • non_profit_501c3
country_of_incorporation No String (2 chars) The 2-letters ISO-3166-1 country code of the country of incorporation (default = US).
state_of_incorporation No String (2 chars) If country_of_incorporation = US, two digit code for state of incorporation.
incorporation_uris No Array of website_uris URLs pointing to incorporation documents (such as PDFs) or incorporation records (such as pages on secretary of state websites).

Example arguments for /rbit/create

{
   "associated_object_type": "account",
   "associated_object_id": 1772434382,
   "receive_time": 1367958263,
   "type": "business_legal",
   "source": "partner_employee",
   "properties": {
      "business_type": "llc",
      "country_of_incorporation": "US",
      "state_of_incorporation": "FL",
      "incorporation_uris": [
        {
            "uri": "http://www.example.com"
        },
        {
            "uri": "http://www.example.com/1"
        }
     ]
}

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

business_report

Information from a 3rd party source / database with information about a business (for example, an Experian Business IQ business credit report).

Parameter Required Type Description
business_id No String (255 chars) Business identification number provided by the 3rd-party data source.
report_uri No String (2083 chars) URL pointing to a copy of the report (for example, a PDF file of the report).

Example arguments for /rbit/create

Send WePay information regarding a Guidestar report found for a WePay account. The rbit also includes a tax_id and phone number associated with the WePay account and phone verification done on the phone number. The phone verification is a PIN delivered by phone by a partner employee.

{
    "associated_object_type": "account",
    "associated_object_id": 1234,
    "receive_time": 1367958897,
    "type": "business_report",
    "source": "guidestar",
    "properties": {
        "report_uri": "http://www.guidestar.org/organizations/53-0196605/american-national-red-cross.aspx"
    },
    "related_rbits": [
        {
            "type": "tax_id",
            "receive_time": 1367958897,
            "source": "guidestar",
            "properties": {
                "tax_id": "087-97-8888",
                "tax_id_country": "US",
                "tax_id_type": "business"
            }
        },
        {
            "receive_time": 1367958897,
            "type": "phone",
            "source": "guidestar",
            "properties": {
                "phone": "+1-800-733-2767",
                "phone_type": "work"
            }
        },
        {
            "receive_time": 1367958897,
            "type": "control_verification",
            "source": "PARTNER_EMPLOYEE",
            "properties": {
                "verification_type": "PIN_delivered_by_phone",
                "verified_phone": "+1-800-733-2767"
            }
        }
    ]
}

comment

This type documents a comment that the user posted. For example, in a donation-based crowdfunding site, a user may post a comment on the site to go along with their donation.

Parameter Required Type Description
comment_text Yes String (1024 chars) The text of the posted comment.
username No String (255 chars) The URI of the page where the comment is posted.
uri No String (2083 chars) The URI of the page where the comment is posted.

Example arguments for /rbit/create

{
    "associated_object_type": "account",
    "associated_object_id": 1234,
    "receive_time": 1367958897,
    "type": "comment",
    "source": "user",
    "properties": {
        "comment_text": "This was a good comment.",
        "user_name": "barney",
        "uri": "http://example.com/test"
    }
}

control_verification

Verification of an associated_rbit resource (like a phone number or e-mail address) that demonstrates the user in question has control of that resource.

Parameter Required Type Description
verification_type Yes String (255 chars) Possible values are:
  • pin_delivered_by_phone: PIN delivered by an outbound phone call, then entered in a web flow.
  • pin_entered_into_phone: PIN delivered by web flow then entered into a phone after an outbound call.
  • pin_delivered_by_sms: PIN delivered by SMS message to the phone number, then entered into a web flow.
  • email_confirmation_link: User clicked on a link sent to their e-mail address.
  • email_bounced_negative: e-mail sent to the e-mail address bounced (showing lack of control by the user).
verified_email No String (255 chars) Email address verified (for email verifications).
verified_phone No String (255 chars) Phone number verified (if phone or SMS verification)

Example arguments for /rbit/create

{
    "associated_object_type": "account",
    "associated_object_id": 1234,
    "receive_time": 1367958897,
    "type": "control_verification",
    "source": "user",
    "properties": {
        "verification_type": "pin_delivered_by_sms",
        "verified_phone": "+1-555-555-5555"
    }
}

conversation

Conversation rbits document discussions between you, the partner, and the user. They should be passed as a related rbit of a “person” rbit with the name of the user you had the conversation with. If it is a phone conversation, a phone number rbit should also be passed as a related rbit to the person object. If it is a site visit, an address rbit of the location visited should also be passed as a related rbit of the person object. Please see example below.

Parameter Required Type Description
conversation_type Yes String (32 chars) Possible values:
  • call: phone conversation.
  • site_visit: in-person visit to user's business location.
  • other_visit: in-person meeting at a different location.
person_making_call_or_visit Yes String (255 chars) Full name of person from the partner's organization who had the conversation with someone in the account's organization.
call_notes No String (255 chars) Text notes from the call.

Example arguments for /rbit/create

{
    "associated_object_type": "checkout",
    "associated_object_id": 1772434382,
    "receive_time": 1367958263,
    "type": "person",
    "source": "partner_employee",
    "properties": {
        "name": "Bill Clerico"
    },
    "related_rbits": [
        {
            "type": "conversation",
            "receive_time": 1367958263,
            "source": "partner_employee",
            "properties": {
                "conversation_type": "call",
                "person_making_call_or_visit": "Barney Barney"
            }
        },
        {
            "type": "phone",
            "receive_time": 1367958263,
            "source": "partner_database",
            "properties": {
                "phone": "+1-555-555-5555",
                "phone_type": "work"
            }
        }
    ]
}

device_info

If the app partner uses WePay javascript for a transaction or credit card flow, many of these values can be obtained automatically. Otherwise, please provide whatever device id info is available regarding a user access.

Parameter Required Type Description
ip No String (37 chars) The IP address associated with the user or transaction.
user_agent No String (255 chars) The browser user-agent string (if a web session).
IMEI No String (255 chars) Mobile device identifier.
true_ip No String (37 chars) Proxy-pierced IP address (as available from various vendors).
third_party_device_id No String (255 chars) Unique ID from a third-party device ID algorithm.
third_party_device_type No String (255 chars) Name of the third-party vendor providing a device ID.

Example arguments for /rbit/create

{
   "associated_object_type": "account",
   "associated_object_id": 1234,
   "receive_time": 1367958897,
   "type": "device_info",
   "source" : "user",
   "properties": {
        "ip": "50.193.26.23",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/34.0.1847.116 Safari/537.36"
    }
}

editorial_review

A review of the business created by an independent journalistic source.

Parameter Required Type Description
review_uri No String (2083 chars) URL of the editorial review.

Example arguments for /rbit/create

{
    "associated_object_type": "user",
    "associated_object_id": 123456,
    "receive_time": 1367958263,
    "type": "editorial_review",
    "source": "partner_database",
    "properties": {
        "review_uri": "http://example.com/review-uri"
    }
}

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

employment

Information associated with a person regarding their employment. This is helpful for both payer and payee.

Rbits of type “employment” should be sent either as a related rbit of type = “person” (to provide information about the person in question) or as a related rbit of type “business_name” (to provide information about the company in question). See example below.

Parameter Required Type Description
timing No String (255 chars) Two possible values:
  • current: the person is currently employed at the business.
  • past: the person used to be employed at the business.
title No String (255 chars) Title of the person at the company.

Example arguments for /rbit/create

{
  "associated_object_type": "account",
  "associated_object_id": ,
  "receive_time": 1367958263,
  "type": "person",
  "source": "user",
  "properties": {
    "name": "Bill Clerico"
  },
  "related_rbits": [
    {
        "receive_time":1367958263,
        "type":"employment",
        "source":"user",
        "properties":{
            "timing": "current",
            "title":"CEO"
        }
    }
  ]
}

expected_volume

Parameter Required Type Description
expected_volume Yes Integer (64 bit) Expected volume in cents for the specified currency
currency Yes String (3 chars) The currency used, default "USD".
volume_period No String (32 chars) There are two possible values for this parameter:
  • monthly: expected volume as a monthly average (default).
  • annual: expected volume as an annual average.

Example arguments for /rbit/create

{
    "associated_object_type": "account",
    "associated_object_id": 123456,
    "receive_time": 1367958263,
    "type": "expected_volume",
    "source": "user",
    "properties": {
        "expected_volume": 52300000,
        "currency": "USD",
        "volume_period": "monthly"
    }
}

event_or_conference

Parameter Required Type Description
expenses Yes Integer (64 bit) Expenses amount in cents for the specified time-frame, segment, and currency
currency Yes String (3 chars) The currency used, default "USD".
start_time Yes Integer (64 bits) Start time of the expense measurement period (i.e. for CY2013 expenses, start-time would be 1/1/2013 00:00)
end_time Yes Integer (64 bits) End time of the expense measurement period (i.e. for CY2013 expenses, end-time would be 1/1/2014 00:00)

Example arguments for /rbit/create

{
    "associated_object_type": "account",
    "associated_object_id": 123456,
    "receive_time": 1367958263,
    "type": "expenses",
    "source": "user",
    "properties": {
        "expenses": 97230000,
        "currency": "USD",
        "start_time": 1325376000,
        "end_time": 1356912000
    }
}

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.

Note

Please use fundraising_event for events related to fundraising or donations.

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:
  • conference
  • indoor_and_recreational
  • other
  • outdoor_and_recreational
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:
  • 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"
    }
}

fundraiser_beneficiary_relationship

For this sub-type, you can provide one or more of the industry codes, below.

Parameter Required Type Description
fundraiser_beneficiary_relationship Yes String (32 chars) Standard values include:
  • family_member
  • friend
  • co_worker
  • spouse_partner
  • neighbor
  • caregiver
  • do_not_know_them_but_want_to_help
  • myself - fundraiser and beneficiary is the same person.
  • other
additional_relationship_info No String (65535 chars) Any additional information about the fundraiser / beneficiary relationship.

Example arguments for /rbit/create

{
    "associated_object_type": "account",
    "associated_object_id": 123456,
    "receive_time": 1367958263,
    "type": "fundraiser_beneficiary_relationship",
    "source": "user",
    "properties": {
        "fundraiser_beneficiary_relationship": "family_member",
        "additional_relationship_info": "This family member is my younger sister"
    }
}

fundraising_campaign

Parameter Required Type Description
description No String (10,000 chars) Full text of the campaign description.
photo_uris No Array of Strings (2083 chars) Array of URIs that point to images that are in the campaign page
uri No String (2083 chars) URI pointing to the campaign website

Example arguments for /rbit/create

{
    "associated_object_type": "account",
    "associated_object_id": 123456,
    "receive_time": 1367958263,
    "type": "fundraising_campaign",
    "source": "user",
    "properties": {
        "description": "Description of the fundraising campaign",
        "photo_uris": [
            {
                "uri": "http://www.example.com/1.jpg"
            },
            {
                "uri": "http://www.example.com/2.png"
            }
        ],
        "uri": "http://www.example.com/campaign"
    }
}

fundraising_team

Information about a team of fundraisers 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.c

Parameter Required Type Description
name Yes String (255 chars) Name of the fundraising event.
uri No URI URI that points to the fundraising event page

Example arguments for /rbit/create

{
    "associated_object_type": "account",
    "associated_object_id": 1234,
    "receive_time": 1367958897,
    "type": "fundraising_team",
    "source": "partner_database",
    "properties": {
        "name": "Fight Cancer",
        "uri": "http://example.com/"
    }
}

fundraising_update

Information about an update to a fundraising campaign.

Parameter Required Type Description
description No String (10,000 chars) Full text of the campaign update.
photo_uris No Array of Strings (2083 chars) Array of URIs that point to images that are in the campaign update.
uri No String (2083 chars) URI pointing to the campaign website.

Example arguments for /rbit/create

{
    "associated_object_type": "account",
    "associated_object_id": 123456,
    "receive_time": 1367958263,
    "type": "fundraising_update",
    "source": "user",
    "properties": {
        "description": "The fundraising update",
        "photo_uris": [
            {
                "uri": "http://www.example.com/1.jpg"
            },
            {
                "uri": "http://www.example.com/2.png"
            }
        ],
        "uri": "http://www.example.com/campaign"
    }
}

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

member_to_member_message

Details about messages sent between users (e.g. between buyers and sellers) using a member-to-member messaging system available on the partner site. Messages are typically sent in reference to a particular transaction, so this rbit type will typically be attached to an /checkout/create or a /checkout/modify call.

Parameter Required Type Description
message_direction Yes String (255 chars) Standard values include:
  • from_payer_to_payee
  • from_payer_to_payer
  • from_payer_to_third_party
  • from_third_party_to_payer
  • from_payee_to_third_party
  • from_third_party_to_payee
  • from_third_party_to_third_party
message_subject No String (1024 chars) Subject of the message.
message_text No String (6400 chars) Text of the message.
uri String (2083 chars) URI pointing to a page containing message details.

Example arguments for /rbit/create

{
    "associated_object_type": "checkout",
    "associated_object_id": 1234,
    "receive_time": 1367958897,
    "type": "member_to_member_message",
    "source": "user",
    "properties": {
        "message_direction": "from_payer_to_payee",
        "message_subject": "Hello",
        "message_text": "message text",
        "uri": "http://example.com/test"
    }
}

member_to_member_stats

Summary statistics about member-to-member communications for an account (such as “contact seller,” “contact fundraiser,” or equivalent functions).

Parameter Required Type Description
inbound_messages No Integer (32 bits) # of messages sent from payers to account owner through the member-to-member messaging system.
inbound_messages_to_txn_ratio No Float Inbound messages / total number of transactions. Do not include if there have been no transactions yet.
outbound_messages No Integer (32 bits) # of messages sent from account owner to payers through the member-to-member messaging system.
outbound_messages_to_txn_ratio No Float Outbound messages / total number of transactions. Do not include if there have been no transactions yet.

Example arguments for /rbit/create

{
    "associated_object_type": "account",
    "associated_object_id": 123456,
    "receive_time": 1367958263,
    "type": "member_to_member_stats",
    "source": "user",
    "properties": {
        "inbound_messages": 30,
        "inbound_messages_to_txn_ratio": 2.5,
        "outbound_messages": 30,
        "outbound_messages_to_txn_ratio": 2.5
    }
}

other_document

Parameter Required Type Description
uri String (2083 chars) URL of the document content.

Example arguments for /rbit/create

{
    "associated_object_type": "account",
    "associated_object_id": 1234,
    "receive_time": 1367958897,
    "type": "other_document",
    "source": "user",
    "properties": {
        "uri": "http://www.example.com/other-document"
    }
}

other_web_content

Rbits of type “other_web_content” should be sent either as a “related_rbit” of type “person” or as a top level rbit for an account.

Parameter Required Type Description
uri No String (2083 chars) URL of the website content.

Example arguments for /rbit/create

{
    "associated_object_type": "user",
    "associated_object_id": 123456,
    "receive_time": 1367958263,
    "type": "other_web_content",
    "source": "partner_database",
    "properties": {
        "uri": "http://example.com/other-web-content"
    }
}
Parameter Required Type Description
total_receipts Yes Integer (64 bit) Receipt amount in cents for the specified time-frame, segment, and currency.
currency Yes String (3 chars) The currency used, default "USD".
start_time Yes Integer (64 bits) Start time of the receipts measurement period (i.e. for CY2013 receipts, start-time would be 1/1/2013 00:00).
end_time Yes Integer (64 bits) End time of the receipts measurement period (i.e. for CY2013 receipts, end-time would be 1/1/2014 00:00).

Example arguments for /rbit/create

{
    "associated_object_type": "account",
    "associated_object_id": 123456,
    "receive_time": 1367958263,
    "type": "paid_invoices",
    "source": "user",
    "properties": {
        "total_receipts": 179300000,
        "currency": "USD",
        "start_time": 1325376000,
        "end_time": 1356912000
    }
}

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

project

Information about a project that an invoice or transaction is related to.

Parameter Required Type Description
name Yes String (255 chars) Name of the project. This should match the project_name property, if provided, in the receipt_line_item structure.
project_description No String (255 chars) Project description.
project_completion_time No Timestamp The unixtime of when the project is scheduled to complete.
billing_method No String (37 chars) Standard values include:
  • hourly_staff_rate
  • hourly_task_rate
  • hourly_project_rate
  • flat_project_amount
project_hourly_estimate No Float Estimated hours needed to complete the project.
project_flat_amount_estimate No Decimal Estimated total cost of the project.
currency No String (3 chars) Currency used.
uri No String (2083 chars) URI that points to a project description page.

Example arguments for /rbit/create

{
    "associated_object_type": "account",
    "associated_object_id": 1234,
    "receive_time": 1367958897,
    "type": "project",
    "source": "user",
    "properties": {
        "name": "Project Red",
        "project_description": "We are raising money to help fight cancer.",
        "project_completion_time": 1410307200,
        "billing_method": "flat_project_amount",
        "project_hourly_estimate": 3000,
        "project_flat_amount_estimate": 30.0,
        "currency": "USD",
        "uri": "http://example.com/project"
    }
}

revenue

Parameter Required Type Description
revenue Yes Integer (64 bit) Revenue amount in cents for the specified time-frame, segment, and currency.
currency Yes String (255 chars) The currency used, default "USD".
start_time Yes Integer (64 bits) Start time of the revenue measurement period (i.e. for CY2013 revenue, start-time would be 1/1/2013 00:00).
end_time Yes Integer (64 bits) End time of the revenue measurement period (i.e. for CY2013 revenue, end-time would be 1/1/2014 00:00).
revenue_fraction No String (255 chars) Two possible values:
  • all: total revenue of the entire business.
  • partial: one segment of the revenue (for example, revenue from just one channel).

Example arguments for /rbit/create

{
    "associated_object_type": "account",
    "associated_object_id": 123456,
    "receive_time": 1367958263,
    "type": "revenue",
    "source": "user",
    "properties": {
        "revenue": 500300000.5,
        "currency": "USD",
        "start_time": 1325376000,
        "end_time": 1356912000
    }
}

risk_review

A risk_review object is a mechanism for WePay and the partner to collaborate on investigating and following-up on issues related to a user, account, or transaction.

Parameter Required Type Description
risk_review_type Yes String (255 chars) Code for the type of risk_review. Standard values include:
  • partner_suspend: partner suspended account
  • wepay_suspend: wepay suspended account
  • partner_review_positive: account was reviewed and overall positive information was found during the review
  • partner_review_neutral: account was reviewed and the information obtained does not substantially affect the risk of the account
  • partner_review_negative: account was reviewed and overall the information obtained was negative, but not enough to suspend the account
status Yes String (255 chars) Two possible values:
  • open
  • closed
subject No String (255 chars) Free text of the subject for the risk_review.
risk_score No Integer (64 bits) Number from 1 (very bad) to 100 (good).
notes No Array of risk_review_steps structures. Notes for each stage of the risk_review (see below for structure).

Example arguments for /rbit/create

{
    "associated_object_type": "checkout",
    "associated_object_id": 1234,
    "receive_time": 1367958897,
    "type": "risk_review",
    "source": "guidestar",
    "properties": {
        "risk_review_type": "partner_suspend",
        "subject": "Partner suspended this account for fraud reasons",
        "status": "open",
        "notes": [
            {
                "person_creating": "Mitch Mitch",
                "note": "After further analysis, we can conclude that the credit card was stolen by user."
            },
            {
                "person_creating": "Barney Barney",
                "note": "After further analysis, we can conclude that the credit card was stolen by user."
            }
        ]
    }
}

risk_review_steps

Track any risk reviews and steps being taken in reviews.

Parameter Required Type Description
person_creating Yes String (255 chars) Name of WePay or partner employee creating this note.
note Yes String (255 chars) Notes regarding this step of the risk_review.
create_time No Integer (64 bits) Time when this step of the risk-review was created (in unix seconds since Jan 1st 1970 UTC).

Example arguments for /rbit/create

{
    "notes": [
        {
            "person_creating": "Mitch Mitch",
            "note": "After further analysis, we can conclude that the credit card was stolen by user."
        },
        {
            "person_creating": "Barney Barney",
            "note": "After further analysis, we can conclude that the credit card was stolen by user."
        }
    ]
}

risk_score

Information about a risk score that could be obtained from a model or a third party. In contrast to the “risk_score” property of the “risk_review” type, a “risk_score” type supports giving the risk score in its raw form.

Make sure to fill in the rbit “source” property with the name of the model or third party that provided the score.

Parameter Required Type Description
score_int No Integer (64 bits) Risk score if it comes in the form of an integer.
score_float No Double (64 bit) Risk score if it comes in the form of a floating point number
score_string No String (255 chars) Risk score if it comes in the form of a string.
lowest_risk_score No String (255 chars) The score value that corresponds to the lowest possible risk. This is provided as a way to understand the scale used for the risk score.

Example arguments for /rbit/create

{
    "associated_object_type": "checkout",
    "associated_object_id": 1234,
    "receive_time": 1367958897,
    "type": "risk_score",
    "source": "partner_database",
    "properties": {
        "score_int": 50
    }
}

social_media_shares

Statistics about how often a page or campaign has been shared on various social media sites.

Parameter Required Type Description
facebook_shares No Integer (32 bits) How many times a page or campaign has been shared on facebook.
twitter_shares No Integer (32 bits) How many times a page or campaign has been shared on twitter.

Example arguments for /rbit/create

{
    "associated_object_type": "account",
    "associated_object_id": 123456,
    "receive_time": 1367958263,
    "type": "social_media_shares",
    "source": "user",
    "properties": {
        "facebook_shares": 500,
        "twitter_shares": 30
    }
}

tax_id

User’s tax information.

Rbits of type “tax_id” 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
tax_id Yes String (255 chars) Tax ID (for example, a social-security number or a Federal eIN number) without any punctuation.
tax_id_country Yes String (2 chars) The 2-letters ISO-3166-1 country code of the country for the tax_id.
tax_id_type Yes String (255 chars) Possible values:
  • personal: for example, if tax_id is a SSN.
  • business: for example, if tax_id is a Federal EIN.
note No String (255 chars) Optional note to define the kind of Tax ID.

Example arguments for /rbit/create

{
    "associated_object_type": "account",
    "associated_object_id": 123456788,
    "receive_time": 1367958263,
    "type": "tax_id",
    "source": "user",
    "properties": {
        "tax_id": "933-70-5555",
        "tax_id_country": "US",
        "tax_id_type": "business",
        "note": "VAT number"
    }
}

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

website_uri

The URI to the campaign/website for the associated object.

Parameter Required Type Description
uri Yes String (2083 chars) URL of the website or associated with the business or user.

Example arguments for /rbit/create

{
    "associated_object_type": "account",
    "associated_object_id": 1234,
    "receive_time": 1367958263,
    "type": "website_uri",
    "source": "partner_database",
    "properties": {
        "uri": "http://www.example.com"
    }
}

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