Risk Certification

 

WePay provides integrated payment processing APIs in addition to risk and compliance overhead management. As a partner platform to WePay, following these certifications will enable WePay to make the best risk decisions for you and your merchants.

rBits

An rBit, or Risk Bit, is a piece of information that a platform can send to WePay through the rBits API, providing more detail about a merchant or a specific transaction.

WePay tailors its policies and procedures to the needs of WePay's partners and the risk profiles of their merchants. WePay risk processing considers information received from platform partners in evaluating and mitigating payment and account-level risk. WePay's rBits API enables smooth and secure sharing of contextual data such as rBits. This data may help increase conversion rates and reduce risk friction for both Payers and Merchants.

WePay's models are continuously learning to stop rapidly changing fraud patterns. Here's how our numbers stack up against the industry:

Industry AverageWePay Average
Online Fraud0.90%<0.10%
Manual Review Rate7-8%1%
Decline Rate2.9%0.37%

Account-level rBit data help with improving the accuracy of WePay's risk solution, reducing manual review times, and reducing the amount of documentation requests from WePay to Merchants.

Payment-level rBit data provide granular detail about the transaction, again, helping to improve the accuracy of WePay's risk solutions and avoiding false positives. Contextual data about a payment help WePay's Risk team verify that the payment adheres to WePay's Terms of Service and compliance requirements. The inclusion of payment-level rBits reduces the frequency and duration of manually reviewed payments as well as allows WePay's Risk team to accurately action a payment.

Note

Any payments or settlement in risk review is subject to a delay of funds up to 1-2 business days.

The following standard rBits for SMB and Fundraising platforms outline the kind of data your platform should sent us in rBits. These standard rBits typically use the same rBit types, and the text points to the specific information that should be provided.

Standard rBits for SMB Platforms


Account-level rBits

InformationrBit parameter
Business Information
Business namebusiness_name.name
Principal nameperson.name.first
person.name.last
person.role: employee
Business addressaddress.address_type
address.origin_address
Business descriptionbusiness_description.description
Business phone numberphone.country_code
phone.phone_number
phone.phone_type: business
Industryindustry_code.code
industry_code.code_type
Relationship Information
Sign-up dateexternal_account.is_partner_account
external_account.account_type
external_account.create_time
external_account.connections
external_account.uri
Subscription plan namepartner_service.service_name
Subscription monthly amountpartner_service.service_monthly_cost

Payment-level rBits

InformationrBit parameter
Transaction Line-Item Details
Service item descriptiontransaction_details.itemized_receipt.description
Pricetransaction_details.itemized_receipt.item_price
Quantitytransaction_details.itemized_receipt.quantity
Sub-total amounttransaction_details.itemized_receipt.amount
SMB terms of service texttransaction_details.terms_text
Additional notestransaction_details.note
Client/Payer Invoice Information
Payer full nameperson.name.first
person.name.last
person.role: other_third_party
Service addresstransaction_details.service_address
Payer phone numberphone.country_code
phone.phone_number
phone.phone_type: personal OR mobile

Standard rBits for Fundraising Platforms


Account-level rBits

InformationrBit parameter
Campaign Organizer Information
Campaign organizer nameperson.name.first
person.name.last
person.role: fundraiser
Campaign organizer social media linksexternal_account.account_type
external_account.uri
external_account.is_partner_account: false
external_account.connections
Campaign page URLfundraisng_event.uri
fundraising_event.name
Non-profit namebusiness_name.name
Non-profit descriptionbusiness_description.description
Non-profit addressaddress.origin_address
address.address_type: headquarters OR satellite
Relationship Information
Sign-up dateexternal_account.is_partner_account
external_account.account_type
external_account.create_time
Subscription plan namepartner_service.service_name
Subscription monthly amountpartner_service.service_monthly_cost

Payment-level rBits

InformationrBit parameter
Transaction Line-Item DetailsIf the platform allows donors to leave a comment with their donation,
then the platform can pass the transactions_details rBit at the checkout level.
Service item descriptiontransaction_details.itemized_receipt.description
Pricetransaction_details.itemized_receipt.item_price
Quantitytransaction_details.itemized_receipt.quantity
Sub-total amounttransaction_details.itemized_receipt.amount
SMB terms of service texttransaction_details.terms_text
Additional notestransaction_details.note
Campaign Organizer Information
Campaign page URLfundraising_event.uri
fundraising_event.name
fundraising_event.description
Donor InformationIf an account runs multiple campaigns through one account, then the
platform must pass the fundraising_event rBit at the checkout level.
Payer full nameperson.name.first
person.name.last
person.role: other_third_party
Payer addresstransaction_details.shipping_address.line1
transaction_details.shipping_address.line2
transaction_details.shipping_address.city
transaction_details.shipping_address.line2
transaction_details.shipping_address.postal_code
transaction_details.shipping_address.country
Payer social media linksexternal_account.account_type
external_account.uri
external_account.is_partner_account: false
external_account.connections

Standard rBits for Leasing Platforms

Note
Be sure to use the Pre-Release version 3.1.rc.1.3 in the Version header parameter for your requests to POST /payments, POST /accounts amd POST /rbits endpoints.
BETA
Rental Surcharge Fees are currently a closed BETA offering on API version 3.1.rc.1.3.
EndpointScopeDescription
POST /rBitsproperty, landlord, rental_infocreates a property, landlord or rental rBit
GET /rbitsproperty, landlord, rental_infoRetrieves all existing rBits for the associated resource.
GET /rbits/{id}property, landlord, rental_infoGet specific rBit when rBit id is known
POST /paymentsproperty, rentalThe property and rental rBits are initialized as part of the payment request
POST /accountslandlordThe landlord rBit is initialized as part of account creation request

Landlord rBit

The landlord rBit will be sent as a new rBit type -- landlord with a call to POST /accounts.

Landlord rBit Attributes

ActionEndpoint ExampleAttributes
Retrieve
Landlord rBits
GET /rbits?owner_id=
3cd20b3c-4008-400b-
b708-2b844ce7be84&
owner_type=accounts
landlord.sign_up_time
landlord.number_of_property_listings
landlord.number_of_properties_rented
landlord.is_rental_insured
landlord.risk_score
Copy
Copied
<other account creation details>
"rbits" : [
  {<other existing rBit for payment>},
  {<other existing rBit for payment>},
  {// Landlord rBit
    "receive_time" : 13456789012,
    "type": "landlord",
    "source" : "partner_database",
    "landlord":{
      "sign_up_time" : 13456789012,
      "number_of_property_listings" : 2,
      "number_of_properties_rented": 1,
      "is_rental_insured" : true,
      "risk_score" : 20
    }
  } // End Landlord rBit
]
Alternatively the landlord rBit can be created with a POST /rbits API call:
Copy
Copied
POST /accounts?account_id="f48cd8e6-e802-4500-a0f9-3ab6228c6f23"&account_type=accounts
Landlord rBit Request Body
Copy
Copied
{
  "landlord": {
    "sign_up_time": 13456789012,
    "number_of_property_listings": 2,
    "number_of_properties_rented": 1,
    "is_rental_insured": true,
    "risk_score": 20
  },
  "associated_resource": {
    "id": "f48cd8e6-e802-4500-a0f9-3ab6228c6f23",
    "resource": "accounts"
  },
  "receive_time": 1367958263,
  "source": "partner_database",
  "type": "landlord"
}
Landlord rBit Response
Copy
Copied
{
  "landlord": {
    "sign_up_time": 1345678901,
    "number_of_property_listings": 2,
    "number_of_properties_rented": 1,
    "is_rental_insured": true,
    "risk_score": 20
  },
  "create_time": 1390656130,
  "id": "f48cd8e6-e802-4500-a0f9-3ab6228c6f23",
  "owner": {
    "id": "d7608b20-fea5-4eb5-bd30-d3f58435e78b",
    "path": "/accounts/d7608b20-fea5-4eb5-bd30-d3f58435e78b",
    "resource": "accounts"
  },
  "path": "/rbits/f48cd8e6-e802-4500-a0f9-3ab6228c6f23",
  "receive_time": 1367958263,
  "resource": "rbits",
  "source": "partner_database",
  "state": "active",
  "type": "landlord",
  "api_version": "3.0"
}

Property and Rental rBits

The Property and Rental rBits are sent as part of creating a payment.

Alternatively the property and rental rBits can be created with a POST /rbits API call.

Property rBit

ActionEndpoint ExampleAttributes
Retrieve Property rBitsGET /rbits?owner_id=
3cd20b3c-4008-400b-b708-2b844ce7be84&
owner_type=payments
property.managed_by
property.listing_time
property.listing_uri
property.type
property.address
Property rBit Request Body
Copy
Copied
"rbits": [
  {// Property rBit
    "receive_time": 13456789012,
    "type": "property",
    "source": "partner_database",
    "property": {
      "managed_by": "property_management",
      "listing_time": 251143022,
      "listing_uri": "https://www.zillow.com/b/alta-civic-station-gresham-or-BjbYvQ/",
      "type": "residential",
      "address": {
        "postal_code": "37547",
        "city": "Gardena",
        "country": "US",
        "line1": "6351 Fringilla Avenue",
        "line2": "",
        "region": "CO"
      }
    }
  },//End Property rBit
]

Rental rBit

ActionEndpoint ExampleAttributes
Retrieve
Rental rBits
GET /rbits?owner_id=
3cd20b3c-4008-400b-b708-2b844ce7be84&
owner_type=payments
rental.sign_up_time
rental.contract_start_time
rental.contract_end_time
rental.contract_amount.amount
rental.contract_amount.currency
rental.payment_frequency
rental.is_first_payment
Rental rBit Request Body
Copy
Copied
{
  // Rental rBit
  "receive_time": 13456789012,
  "type": "rental",
  "source": "partner_database",
  "rental": {
    "sign_up_time": 13456789012,
    "contract_amount": {
      "amount": 150000,
      "currency": "USD"
    },
    "payment_frequency": "monthly",
    "is_first_payment": true,
    "contract_start_time": 13456789012,
    "contract_end_time": 13445678012
  }
} // End Rental rBit

Detailed Examples

Property rBit POST /payments Request/Response Example
General notes
  • A create payment request is sent to POST /payments.
  • The payments request accepts an array of rBit values as a parameter.
  • The property and rental optional rBits are sent as part of payment creation.

The request body has this general schema structure:

Copy
Copied
{
  "account_id": "abc123",
  "amount": 1000,
  "auto_capture": true,
  "currency": "USD",
  "custom_data": {
    "my_key": "invoice #54321"
  },
  "fee_amount": 30,
  "payment_method": {
    "credit_card": {
      "auto_update": false,
      "card_holder": {
        "address": {
          "city": "Redwood City",
          "country": "US",
          "line1": "350 Convention Way",
          "postal_code": "94025",
          "region": "CA"
        },
        "email": "example@wepay.com",
        "holder_name": "John Snow"
      },
      "card_number": "5496198584584769",
      "cvv": "007",
      "expiration_month": 4,
      "expiration_year": 2030,
      "virtual_terminal_mode": "web",
      "card_on_file": true,
      "recurring": false
    },
    "custom_data": {
      "my_key": "invoice #54321"
    },
    "type": "credit_card"
  },
  "initiated_by": "customer",
  "rbits": [
    { "example1": "<some other existing rBit for payment>" },
    { "example2": "<some other existing rBit for payment>" },
    {
      // Property rBit
      "receive_time": "13456789012",
      "type": "property",
      "source": "partner_database",
      "property": {
        "managed_by": "property_management",
        "listing_time": 251143022,
        "listing_uri": "https://www.zillow.com/b/alta-civic-station-gresham-or-BjbYvQ/",
        "type": "residential",
        "address": {
          "postal_code": "37547",
          "city": "Gardena",
          "country": "US",
          "line1": "6351 Fringilla Avenue",
          "line2": "",
          "region": "CO"
        }
      }
    }, //end of Property rBit
    {
      //Rental rBit
      "receive_time": "13456789012",
      "type": "rental",
      "source": "partner_database",
      "rental": {
        "sign_up_time": 13456789012,
        "contract_amount": {
          "amount": "150000",
          "currency": "USD"
        },
        "payment_frequency": "monthly",
        "is_first_payment": "true",
        "contract_start_time": 13456789012,
        "contract_end_time": 13445678012
      }
    }, //end of Rental rBit
    { "example3": "<another existing rBit for payment>" },
    { "example4": "<yet another existing rBit for payment>" }
  ],
  "reference_id": "dfeb052b-ae8c-4a69-b909-8d9ecdd7c742"
}

The reponse body will be similar to the following schema structure:

Copy
Copied
{
  "amount": 1000,
  "amount_refunded": 1000,
  "amount_disputed": 1000,
  "auto_capture": false,
  "capture_at": null,
  "create_time": 1510080179,
  "currency": "USD",
  "custom_data": null,
  "failure_reason": null,
  "fee_amount": 0,
  "id": "00000000-0000-0000-0000-0000767bf5cd",
  "order": null,
  "owner": {
    "id": "be2b42e5-b808-40ae-9bbe-3291ab493f57",
    "path": "/accounts/be2b42e5-b808-40ae-9bbe-3291ab493f57",
    "resource": "accounts"
  },
  "path": "/payments/00000000-0000-0000-0000-0000767bf5cd",
  "payment_method": {
    "id": "00000000-6363-0000-0000-000008b93a6e",
    "path": "/payment_methods/00000000-6363-0000-0000-000008b93a6e",
    "resource": "payment_methods"
  },
  "pending_reasons": [
    {
      "details": [],
      "reason_code": "PENDING_CAPTURE",
      "reason_message": "Payment pending capture."
    }
  ],
  "resource": "payments",
  "status": "pending",
  "authorization_code": "0224241",
  "txnr_app_fee": null,
  "txnr_merchant": null,
  "initiated_by": "customer",
  "api_version": "3.0",
  "reference_id": "dfeb052b-ae8c-4a69-b909-8d9ecdd7c742"
}
An API call to GET /rbits will list the rBits associated with this account owner, and payments resource.
Copy
Copied
GET /rbits?owner_id=be2b42e5-b808-40ae-9bbe-3291ab493f57&owner_type=payments
Landlord rBit /accounts Request/Response Example

The merchant/account onboarding/creation - "Create an account" will include an API request to POST /accounts containing the optional rBit for Landlord.

The request body has this general schema structure:

Copy
Copied
{
    "description": "Foo Bar Shop on 5th ave.",
    "industry": {
        "category_detail": "Website design",
        "merchant_category_code": "7333"
    },
    "legal_entity_id": "3cd20b3c-4008-400b-b708-2b844ce7be84",
    "name": "Foo Bar Shop",
    "payout": {
        "currencies": {
            "USD": {
                "payout_method_id": "0102b1c6-2bc7-448a-aa1d-0d180a1d982a",
                "period": "daily"
            }
        }
    },
    "reference_id": null,
    "statement_description": "Purchase from Foo Bar Shop",
    "projected_monthly_transaction_volume": 500,
    "rbits" : [
        {<other existing rBit for accounts>},
        {<other existing rBit for accounts>},
        { // Landlord rBit
            "receive_time" : "13456789012",
            "type": "landlord",
            "source" : "partner_database",
            "landlord":{
                "sign_up_time" : 13456789012,
                "number_of_property_listings" : "2",
                "number_of_properties_rented": "1",
                "is_rental_insured" : "true",
                "risk_score" : 20
            }
        }// end of landlord rBit
    ]
}

The response body has this schema structure:

Copy
Copied
{
  "balances": {
    "currencies": {
      "USD": {
        "balance": 100000,
        "incoming_pending": 5000,
        "outgoing_pending": 21200,
        "reserve": 10000
      }
    }
  },
  "create_time": 1480700534,
  "api_version": "3.0",
  "beneficiary": {
    "id": "295f2816-07b9-4d9e-a035-4f0884ef228b",
    "resource": "legal_entities",
    "path": "/legal_entities/295f2816-07b9-4d9e-a035-4f0884ef228b"
  },
  "custom_data": null,
  "description": "Foo Bar Shop on 5th ave.",
  "documents": [],
  "enhanced_review": "not_requested",
  "id": "d3f61e56-5d99-4895-af2d-a07ab48476e9",
  "incoming_payments": {
    "accepted_methods": ["payment_bank", "mastercard", "visa", "amex"]
  },
  "industry": {
    "category_detail": "Website design",
    "merchant_category_code": "7333"
  },
  "name": "Foo Bar Shop",
  "owner": {
    "id": "3cd20b3c-4008-400b-b708-2b844ce7be84",
    "path": "/legal_entities/3cd20b3c-4008-400b-b708-2b844ce7be84",
    "resource": "legal_entities"
  },
  "path": "/accounts/d3f61e56-5d99-4895-af2d-a07ab48476e9",
  "payout": {
    "currencies": {
      "USD": {
        "next_payout_time": 14987382982,
        "payout_method_id": "0102b1c6-2bc7-448a-aa1d-076b1637547c",
        "period": "daily"
      }
    },
    "default_currency": "USD"
  },
  "pricing": {
    "currencies": {
      "USD": {
        "credit_card": null,
        "payment_bank": null,
        "recurring_fee": null,
        "other_fees": {
          "debit_failure_fee": null
        }
      }
    }
  },
  "reference_id": null,
  "resource": "accounts",
  "statement_description": "Purchase from Foo Bar Shop",
  "platform_onboarding_time": null,
  "projected_monthly_transaction_volume": 500
}
An API call to GET /rbits will list the rBits associated with payments, or associated with the merchant accounts resource.

GET Property and Rental rBits

Copy
Copied
GET /rbits?owner_id=3cd20b3c-4008-400b-b708-2b844ce7be84&owner_type=payments

GET Landlord rBits

Copy
Copied
GET /rbits?owner_id=3cd20b3c-4008-400b-b708-2b844ce7be84&owner_type=accounts

Risk Headers

The WePay API accepts Risk HTTP headers on every request which provide WePay with risk-related information about that request. While optional, partners are strongly encouraged to provide this data when possible to improve the accuracy in WePay's risk solutions and to help streamline decisioning.

The combination of rBit data and Risk Header information equips WePay's Risk team with information necessary for review and underwriting purposes. As with rBits, Risk Header data helps to reduce the frequency and duration of manually reviewed payments, thereby increasing fund availability.

WePay's Risk Engine keys off of Risk Header data to help with more accurate and effective decisioning. Some of this information is passed to WePay on POST /accounts and POST /payments. Having said that, passing that data as an rBit can help to improve the accuracy of WePay's risk solution, reduce manual review times, and reduce requests for additional documentation.

Read more about Risk Headers.

There are two types of risk-related request headers:

Client IP

This HTTP header value should be the public IP address of the client whom the API call is made on behalf of. For example, if a partner is making a /credit_card/create call, this would be the IP address of the user who triggered the API request on the partner's system

WePay Risk Token

This HTTP header value should be the risk token UUID generated by the WePay JavaScript library on the webpage where the API request on the platform's system is triggered.

Note

The Risk Token header is required when the tokenization JS library is not being used.


Settlement Limits

Settlement Limits are funds that are not available for the merchant to settle until a given period of time passes. WePay implements a settlement limit policy to protect the company and the merchant against account debits associated with refunds, chargebacks and disputes.

Weekly Settlement Limit

WePay's current settlement product begins with a platform-level default settlement limit value that takes several factors into consideration. These factors include the platform's average payment amount, MCCs serviced on the platform, platform-wide refund and chargeback rates, and several other variables.

The Weekly Settlement Limit is comprised of two components; a dollar value and a rolling time value. A Settlement limit of $500/1week indicates that a Merchant can settle up to $500 within a 7-day time period and all additional payments processed within that time period will be available for withdrawal after 7 days.

To illustrate, this table shows how the dollar value and rolling time value interact with a custom weekly settlement limit of $100,000.00:

DayAmount ProcessedAmount Available for Settlement (Payout)
1
(start of week 1)
$120,000.00$100,000.00
2$150,000.00$0.00
3$170,000.00$0.00
4$100,000.00$0.00
5$110,000.00$0.00
6$120,000.00$0.00
7$200,000.00$0.00
8
(start of week 2)
$50,000.00$70,000.00
($20,000.00 from Day 1 + $50,000.00 from current day)
9$30,000.00$180,000.00
($150,000.00 from Day 2 + $30,000.00 from current day)
10$20,000.00$190,000.00
($170,000.00 from Day 3 + $20,000.00 from current day)
11$70,000.00$100,000.00
($100,000.00 from Day 4 + $0.00 from current day since the weekly settlement limit has been reached)
12$100,000.00$110,000.00
($110,000.00 from Day 5 + $0.00 from current day)
13$130,000.00$120,000.00
($120,000.00 from Day 6 + $0.00 from current day)
14$120,000.00$200,000.00
($200,000.00 from Day 7 + $0.00 from current day)

Exceptions

Any deviations or exceptions to above-established policy and procedure need approval from WePay. Please reach out to your Account Manager or api@wepay.com for any exception proposals.