/rbit standard 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 will 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 will need to make the /rbit/create api call with the following required parameters:

  • A "type" parameter is a one-word describing the kind of risk information the rbit contains. i.e. type = "phone" for phone number
  • A "properties" parameter set to the key value pair of properties for this type. The properties of the rbit will depend on the type.
  • An associated_object_type, associated_object_id, receive_time, and source parameter as listed in the documentation.

Below is a list of standard types and their properties associated with users, accounts, and transactions that you can pass into the type and properties parameters respectively when making the /rbit/create api call.

type = "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 (for example, an employee of a company who provided information).

Rbits of type "person" are usually associated with the following related rbits: phone, tax_id, address, other_web_content, external_profiles, employment, conversation, and other_document.

Parameter Required Type Description
name Yes String (255 chars) The full name of the person
birthdate No String (10 chars) The birth date of the person. Must be in YYYY-MM-DD format. i.e 1989-08-10
role No String (255 chars) Standard values include:
  • employee
  • fundraiser
  • fundraising_team_captain
  • other_third_party

Example arguments for /rbit/create api call:

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

type = "email"

Email 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 api call:

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

type = "business_name"

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) 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 api call:

{
   "associated_object_type": "account",
   "associated_object_id": 1234,
   "receive_time": 1367958263,
   "type": "business_name",
   "source": "user",
   "properties": {
      "business_name": "Wefarm Company",
      "name_type": "legal"
   }
}

type = "address"

A mailing address associated with /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 api call:

Mailing address information for owner of the account with id #123456788:

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

type = "phone"

A phone number associated with /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
  • mobile

Example arguments for /rbit/create api call:

{
   "associated_object_type":"account",
   "associated_object_id":123456788,
   "receive_time":1367958263,
   "type":"phone",
   "source":"user",
   "properties":{
      "phone": "+1-555-555-5555",
      "phone_type": "home"
   }
}

type = "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 api call:

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

type = "website_uri"

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 api call:

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

type = "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 api call:

Send employment information for payer of checkout id #1234 

{
  "associated_object_type": "account",
  "associated_object_id": {{account_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"
        }
    }
  ]
}

type = "industry_code"

Parameter Required Type Description
industry_code_type Yes String (32 chars) Possible values:
industry_code Yes String (32 chars) The industry code for the industry_type set. Either the mcc, sic, 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 api call:

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

type = "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
  • 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 api call:

{
   "associated_object_type":"account",
   "associated_object_id":123456788,
   "receive_time":1367958263,
   "type":"business_description",
   "source":"user",
   "properties":{
      "business_description":"We sell produce to customers."
   }
}

type = "external_account"

Any external accounts like Facebook or Twitter the user has.

Parameter Required Type Description
is_partner_account Yes String Two 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.

Here are some possible values you can use for this parameter:

facebook, linkedin, klout, twitter, ebay, googleplus, yelp, 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 timestamp when external account was created (unix seconds since Jan 1st 1970 UTC)
modify_time No Integer (64 bits) The 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 api call:

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

type = "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 
{
   "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"
   }
}

type = "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 Yes String (2083 chars) URL of the website content 
{
   "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"
   }
}

type = "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)
 
{
   "associated_object_type": "account",
   "associated_object_id": 123456,
   "receive_time":1367958263,
   "type":"revenue",
   "source":"user",
   "properties":{
      "revenue": 500300000.50,
      "currency": "USD",
      "start_time": 1325376000,
      "end_time": 1356912000
   }
}

type = "expenses"

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

type = "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 api call:

Send rbit about conversation with the payer of checkout id #1772434382 

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

type = "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 api call

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

type = "other_document"

Parameter Required Type Description
uri No String (2083 chars) URL of the document content 
{
   "associated_object_type": "account",
   "associated_object_id": 1234,
   "receive_time": 1367958897,
   "type": "other_document",
   "source" : "user",
   "properties": {
        "uri": "http://www.example.com/other-document"
   }
}

type = "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 
{
   "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"
    }
}

type = "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 user name shown as posting the comment
uri No String (2083 chars) The URI of the page where the comment is posted 
{
   "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"
    }
}

type = "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)/td> 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. 
{
   "associated_object_type": "checkout",
   "associated_object_id": 1234,
   "receive_time": 1367958897,
   "type": "risk_score",
   "source" : "partner_database",
   "properties": {
        "score_int": 50
    }
}

type = "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 
{
   "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.00,
        "currency": "USD",
        "uri": "http://example.com/project"
    }
}

type = "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 unixtime of when the event starts.
giving_deadline No Timestamp The unixtime 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 (default "USD")
uri No URI URI that points to the fundraising event page 
{
   "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"
   }
}

type = "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.

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

type = "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 No String (2083 chars) URI pointing to a page containing message details 
{
   "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"
   }
}

type = "acquisition_channel"

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

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

type = "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. 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 
{
   "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
	   }
	}
   ]
}

type = "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) 
{
   "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"
    }
}

type = "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
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)
status Yes String (255 chars) Two possible values:
  • open
  • closed
notes No Array of risk_review_steps structures Notes for each stage of the risk_review (see below for structure) 
{
   "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."
        }
     ]
   }
}

type = "risk_review_steps"

Parameter Required Type Description
create_time No Integer (64 bits) Time when this step of the risk-review was created (in unix seconds since Jan 1st 1970 UTC)
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

type = "transaction_details"

Parameter Required Type Description
receipt_uri No String (2083 chars) The buyer agreement or transaction's 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/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/address 
{
   "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
        }
      ]
   }
}

type = "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 
{
   "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"
   }
}

type = "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 
{
   "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"
   }
}

type = "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 
{
   "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"
   }
}

type = "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. 
{
   "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
   }
}

type = "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. 
{
   "associated_object_type": "account",
   "associated_object_id": 123456,
   "receive_time": 1367958263,
   "type": "social_media_shares",
   "source": "user",
   "properties": {
      "facebook_shares": 500,
      "twitter_shares": 30
   }
}

type = "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. 
{
   "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"
   }
}

type = "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 = 1. If the second, payment_number = 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 = 3. If there is no scheduled end to the auto-billed payments, do not include this property.
payment_frequency No String (32 chars) One of the following:
  • "weekly"
  • "monthly"
  • "quarterly"
  • "annually"

Alternately, you can specify the number of 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": payer set up and authorized auto-billing
  • "merchant": merchant set-up auto-billing on the payer's behalf
 
{
   "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"
   }
}