The Risk API calls

The Risk API provides a way to communicate risk-related account and transaction level information between an application and WePay. An application and WePay will use this information to improve its risk decisioning process on both sides and provide better information to the user. Please review our Risk Certification guide for more information on WePay’s risk management.

An rbit contains risk related information about your users, their accounts, and their transactions. The following calls let you create, view, and modify rbit objects on WePay:

• /rbit
• /rbit/find
• /rbit/create
• /rbit/delete
• Embedded rBits

Version: v2 2019-04-03

POST Endpoint

https://wepayapi.com/v2/rbit

/rbit

This call allows you to lookup the details of a specific rbit on WePay using the rbit_id.

Arguments

Parameter	Required	Type	Description
rbit_id	Yes	Integer (64 bits)	The unique ID of the rbit you want to look up.

Example

{
    "rbit_id": 12345
}

Response

Response	Type	Description
rbit_id	Integer (64 bits)	The unique ID of the rbit.
associated_object_type	String (255 chars)	The type of object that this rbit is associated with. Possible values are: account: for information about a payee. user: for information about a payer with a WePay user id. checkout: for information about a checkout transaction or checkout payer. preapproval: for information about a preapproval transaction or preapproval payer. credit_card: for information about the owner of a credit card.
associated_object_id	Integer (64 bits)	The unique ID of the object that this rbit is associated with.
type	String (255 chars)	The type of rbit (see rbit types).
properties	Object	The properties of the rbit will depend on the type (see rbit types for a list of properties that you can set for each type).
receive_time	Integer(64 bits)	The Unix time when the data in this rbit was first obtained.
source	String (255 chars)	Source of the information (see standard source values).
note	String (65535 chars)	Free form note giving more context about the information. Used by Risk Analysts during manual review.
related_rbits	Array of rbit types	Array of rbits associated with this object.

Example

{
    "rbit_id": 123456,
    "associated_object_type": "account",
    "associated_object_id": 123456788,
    "receive_time": 1367958263,
    "type": "business_report",
    "source": "guidestar",
    "properties": {
        "report_url": "http://www.guidestar.org/organizations/53-0196605/american-national-red-cross.aspx"
    },
    "related_rbits": [
        {
            "rbit_id": 123457,
            "receive_time": 1367958263,
            "type": "tax_id",
            "source": "guidestar",
            "properties": {
                "tax_id": "53-0196605",
                "tax_id_country": "US",
                "tax_id_type": "business"
            }
        },
        {
            "rbit_id": 123458,
            "receive_time": 1367958263,
            "type": "phone",
            "source": "guidestar",
            "properties": {
                "phone_number": "+1-800-733-2767",
                "phone_type": "work"
            }
        }
    ]
}

/rbit/find

Use this call to search the rbits of the user associated with the access token used to make the call. Returns an array of matching rbits. Each element of the array will include the same data as returned from the /rbit call.

Arguments

Parameter	Required	Type	Description
associated_object_type	No	String (255 chars)	The type of object that this rbit is associated with. Possible Values: account: for information about a payee. user: for information about a payer with a WePay user id. checkout: for information about a checkout transaction or checkout payer. preapproval: for information about a preapproval transaction or preapproval payer. credit_card: for information about the owner of a credit card.
associated_object_id	No	Integer (64 bits)	The unique ID of the object that this rbit is associated with. For example, for a checkout, this is the checkout_id returned when making the /checkout/create API call.
type	No	String (255 chars)	The type of rbit (see standard type values).
source	No	String (255 chars)	Source of the information (see standard source values).

Example

{
    "associated_object_type": "account",
    "associated_object_id": 344444,
    "type": "tax_id",
    "source": "guidestar"
}

Response

Response	Type	Description
rbit_id	Integer (64 bits)	The unique ID of the rbit.
associated_object_type	String (255 chars)	The type of object that this rbit is associated with. Possible values are: account: for information about a payee. user: for information about a payer with a WePay user id. checkout: for information about a checkout transaction or checkout payer. preapproval: for information about a preapproval transaction or preapproval payer. credit_card: for information about the owner of a credit card.
associated_object_id	Integer (64 bits)	The unique ID of the object that this rbit is associated with.
type	String (255 chars)	The type of rbit (see rbit types).
properties	Object	The properties of the rbit will depend on the type (see rbit types for a list of properties that you can set for each type).
receive_time	Integer(64 bits)	The Unix time when the data in this rbit was first obtained.
source	String (255 chars)	Source of the information (see standard source values).
note	String (65535 chars)	Free form note giving more context about the information. Used by Risk Analysts during manual review.
related_rbits	Array of rbit types	Array of rbits associated with this object.

Example

[
    {
        "rbit_id": 123456,
        "associated_object_type": "account",
        "associated_object_id": 123456788,
        "receive_time": 1367958263,
        "type": "business_report",
        "source": "guidestar",
        "properties": {
            "report_url": "http://www.guidestar.org/organizations/53-0196605/american-national-red-cross.aspx"
        },
        "related_rbits": [
            {
                "rbit_id": 123457,
                "receive_time": 1367958263,
                "type": "tax_id",
                "source": "guidestar",
                "properties": {
                    "tax_id": "53-0196605",
                    "tax_id_country": "US",
                    "tax_id_type": "business"
                }
            },
            {
                "rbit_id": 123458,
                "receive_time": 1367958263,
                "type": "phone",
                "source": "guidestar",
                "properties": {
                    "phone_number": "+1-800-733-2767",
                    "phone_type": "work"
                }
            }
        ]
    },
    {
        "rbit_id": 123457,
        "associated_object_type": "checkout",
        "associated_object_id": 123456788,
        "receive_time": 1367958263,
        "type": "person",
        "source": "user",
        "properties": {
            "name": "Bill Clerico"
        },
        "related_rbits": [
            {
                "rbit_id": 123459,
                "receive_time": 1367958263,
                "type": "tax_id",
                "source": "user",
                "note": "This is the ssn user provided.",
                "properties": {
                    "tax_id": "53-0196603",
                    "tax_id_country": "US",
                    "tax_id_type": "personal"
                }
            },
            {
                "rbit_id": 123458,
                "receive_time": 1367958263,
                "type": "phone",
                "source": "user",
                "note": "This is the phone number user provided.",
                "properties": {
                    "phone_number": "899",
                    "phone_type": "work"
                }
            }
        ]
    }
]

/rbit/create

Use this call to create a new rbit for a user, account, or transaction.

Arguments

Response	Required	Type	Description
associated_object_type	Yes	String (255 chars)	The type of object that this rbit is associated with. Possible values are: account: for information about a payee. user: for information about a payer with a WePay user id. checkout: for information about a checkout transaction or checkout payer. preapproval: for information about a preapproval transaction or preapproval payer. credit_card: for information about the owner of a credit card.
associated_object_id	Yes	Integer (64 bits)	For checkout, set to the checkout_id returned when making the /checkout/create API call. For preapproval, set to the preapproval_id returned when making the /preapproval/create API call. For user, set to the user_id returned when making the /user/register API call. For account, set to the account_id returned when making the /account/create API call. For credit_card, set to the credit_card_id returned when making the /credit_card/create API call.
type	Yes	String (255 chars)	The type of rbit (see standard type values).
properties	Yes	Object	The properties of the rbit will depend on the type (see standard type values for a list of properties that you can set for each type).
receive_time	Yes	Integer (64 bits)	The Unix time when the data in this rbit was first obtained.
source	Yes	String (255 chars)	Source of the information (see standard source values).
note	No	String (65535 chars)	Free form note giving more details about the information. Used by Risk Analysts during manual review.
related_rbits	No	Array of rbit types	An array of rbits that are related to this rbit. For example, a person rbit can have address (type = "address") and social security number (type = "tax_id") rbits associated with that person sent as related rbits. If an rbit is primarily associated with an associated object, then it should be passed as a top-level rbit and not as a related rbit. For example, a business phone number should be passed as a top-level for the account, whereas a home phone number for one employee should be passed as a related rbit associated with the person rbit. You do not need to specify the parameters, associated_object_type and associated_object_id for rbits sent as related rbits.

Example

Send phone and address rbits about a payee associated with WePay account ID 123456788.

{
    "associated_object_type": "account",
    "associated_object_id": 123456788,
    "receive_time": 1367958263,
    "type": "person",
    "source": "guidestar",
    "properties": {
        "name": "Bill Clerico"
    },
    "related_rbits": [
        {
            "receive_time": 1367958263,
            "type": "phone",
            "source": "user",
            "properties": {
                "phone": "555-555-5555",
                "phone_type": "home"
            }
        },
        {
            "receive_time": 1367958263,
            "type": "address",
            "source": "user",
            "properties": {
                "address": {
                    "address1": "380 Portage Avenue",
                    "city": "Palo Alto",
                    "state": "CA",
                    "zip": "93036",
                    "country": "US"
                }
            }
        }
    ]
}

Response

Response	Type	Description
rbit_id	Integer (64 bits)	The unique ID of the rbit.
associated_object_type	String (255 chars)	The type of object that this rbit is associated with. Possible values are: account: for information about a payee. user: for information about a payer with a WePay user id. checkout: for information about a checkout transaction or checkout payer. preapproval: for information about a preapproval transaction or preapproval payer. credit_card: for information about the owner of a credit card.
associated_object_id	Integer (64 bits)	The unique ID of the object that this rbit is associated with.
type	String (255 chars)	The type of rbit (see standard type values).
properties	Object	The properties of the rbit will depend on the type (see standard type values. for a list of properties that you can set for each type).
receive_time	Integer(64 bits)	The Unix time when the data in this rbit was first obtained.
source	String (255 chars)	Source of the information (see standard source values).
note	String (65535 chars)	Free form note giving more details about the information. Used by Risk Analysts during manual review.
related_rbits	Array of rbit types.	Array of rbits associated with this object.

Example

{
    "rbit_id": 123456,
    "associated_object_type": "account",
    "associated_object_id": 123456788,
    "receive_time": 1367958263,
    "type": "business_report",
    "source": "guidestar",
    "properties": {
        "report_url": "http://www.guidestar.org/organizations/53-0196605/american-national-red-cross.aspx"
    },
    "related_rbits": [
        {
            "rbit_id": 123457,
            "receive_time": 1367958263,
            "type": "tax_id",
            "source": "guidestar",
            "properties": {
                "tax_id": "53-0196605",
                "tax_id_country": "US",
                "tax_id_type": "business"
            }
        },
        {
            "rbit_id": 123458,
            "receive_time": 1367958263,
            "type": "phone",
            "source": "guidestar",
            "properties": {
                "phone_number": "+1-800-733-2767",
                "phone_type": "work"
            }
        }
    ]
}

/rbit/delete

Use this call to delete a specified rbit.

Arguments

Parameter	Required	Type	Description
rbit_id	Yes	Integer (64 bits)	The unique ID of the rbit you want to delete.

Example

{
    "rbit_id": 12345
}

Response

Response	Type	Description
rbit_id	Integer (64 bits)	The unique ID of the rbit.
state	String (255 chars)	The state of the rbit.

Example

{
    "rbit_id": 123456,
    "state": "deleted"
}

Embedded rBits

Create rBits embedded in another create or modify request, most commonly /account/create, /account/modify, /checkout/create, and /checkout/modify.

The parameters below will contain an array of rBit types, and these top-level parameters provide context around those types. For instance, the address rBit type can be used on the transaction_details, payer_rbits, and rbits parameters while inherently referencing different addresses. On the transaction_details parameter, the address will reference a service or delivery address, while on the payer_rbits parameter it will specifically reference the payer’s address. These values may be the same, but they could be different. Likewise, on the rbits parameter, the address rBit type will reference the business/merchant address.

For further information on rBits, check out the Risk Certification Guide.

Arguments

Parameter	Required	Type	Description
transaction_details	One Of	Array	Use this parameter on /checkout/create and /checkout/modify requests to provide rBits specifically related to the transaction.
payer_rbits	One Of	Array	Use this parameter on /checkout/create and /checkout/mofify requests to provide rBits specically related to the payer of a transaction.
rbits	One Of	Array	Use this parameter on /account/create and /account/modify requests to provide rBits specifically related to an account.

Checkout Resource Example

{
    "transaction_details": [
        {
            "receive_time": 1367958263,
            "type": "transaction_details",
            "source": "user",
            "properties": {
                "itemized_receipt": [
                    {
                        "description": "Website maintenance for 40 hours",
                        "item_price": 250.0,
                        "quantity": 40,
                        "amount": 10000.0,
                        "currency": "USD"
                    },
                    {
                        "description": "Website SEO Consulting for 4 hours",
                        "item_price": 300,
                        "quantity": 4,
                        "amount": 1200,
                        "currency": "USD"
                    }
                ],
                "note": "Please pay the invoice within 7 days"
            }
        }
    ]
}

Account Resource Example

{
    "rbits": [
        {
            "receive_time": 1367958263,
            "type": "business_name",
            "source": "user",
            "properties": {
                "business_name": "Acme Inc."
            }
        }
    ]
}

Response

rBit IDs are not returned in the response when embedded. If the IDs are needed, send a /rbit/find request with the appropriate associated_object_id.

Standard source values

The source parameter (see /rbit/create API call) can be set to any one of values below:

Value	Description
user	Data provided by the user through a webflow
guidestar	www.guidestar.com
experian_precise_id	www.experian.com
experian_biz_id	www.experian.com
experian_biz_iq	www.experian.com
equifax	www.equifax.com
spokeo	www.spokeo.com
whitepages	www.whitepages.com
irs_tin_check	www.irs.gov
partner_database	Data gathered directly by partner (for example transaction revenue from partner account).
partner_employee	Data gathered from a partner employee (for example, from a customer service or a sales call).
generic_website	Data gathered from a website other than a major data provider.