Get Started

Review Supported Platforms

Before getting started, verify that your platform type is supported* by WePay:

1. Small-Medium Business (SMB)
2. E-commerce
3. Point of Sale

WePay's API products are packed full of features and conveniences to help you handle different scenarios, like reducing PCI scope, preventing double charges in case of error, and adding in your own custom data to help maintain things like state.

By the end of this doc, you'll have the right information to build an API call.

Sign Up

We recommend using an aliased email address to sign up (so, something like payments@your-company.com) as this allows for multiple people to access your company's account, instead of tying it to a single person's login. Another benefit is that the person responsible for filling in Know Your Customer (KYC) details can do so at a later time while you onboard to the API and begin making calls.

If you're simply testing the API, it's fine to use your own email address, and create a separate account using an alias at a later time.

Confirm Email Address

A banner reminding you to confirm your email

Generate App Tokens

Note that the Legal Entity and Account IDs displayed with your API credentials are specific to your platform; each merchant will require their own Legal Entity and Account.

You can generate up to 3 tokens. As an example for using multiple tokens, you can think of each as a way to logically separate different components of your system which may interface with different parts of the Clear API. For example, you could have one service that exclusively deals with payment processing, which would have its own token that is revocable at any time. It's not mandatory to generate more than 1 token.

Stage vs. Production

In order to process payments in Production, you must first be assigned an integration manager.

If you are not managed and would like to move to Production, contact our Sales team to move further. We suggest completing this step first to align on integration requirements.

When you are managed and ready to launch, you can begin the process of certification to migrate to the Production environment in the dashboard.

As using production credentials executes actual money movement, we do not allow any account to migrate to the production environment until they have passed certification. We define certification throughout the basic integration process. In addition, WePay requires you to submit personal and business details before you can access the production environment.

Submit Personal and Business Details

To submit personal and business details, first navigate to the Live tab and click the blue button to update your personal information:

Submit your personal and business KYC in the Live tab

Next, identify the country your business is located in:

App entity location

Then, identify the entity type of your application:

App Entity Type

If your application is a business, specify whether your business is a corporation, LLC, or partnership. If your application is a nonprofit, specify whether your nonprofit is a nonprofit corporation or an unincorporated association.

Identify your application's industry category and type to help WePay identify an appropriate merchant category code for your account.

Next, fill in your application's business details:

App business details

Next, supply personal details for a controller of your application's business:

App controller details

A controller is a single individual with significant responsibility to control, manage, or direct a legal entity customer, including an executive officer or senior manager (e.g., a Chief Executive Officer, Chief Financial Officer, Chief Operating Officer, Managing Member, General Partner, President, Vice President, or Treasurer); or any other individual who regularly performs similar functions (i.e., the control prong). This list of positions is illustrative, not exclusive, as there is significant diversity in how legal entities are structured.

Last, supply the personal details for everyone who owns 25% or more of your application's business:

Add app owner details

Add more app business owner details

WePay will verify your information once submitted, typically within 2 business days.

Add Bank Account

Once you've confirmed your account, generated an app token, and submitted all business and personal details, you can add a bank account to receive payouts. As a reminder, you need to fill out KYC information to receive payouts.

Usually, a Controller, VP level, or C-level person is responsible for filling this information by navigating to the Payouts section of the WePay application dashboard and clicking "Add":

Add app's bank account for payouts

If your business is based in Canada, please reach out to your account manager or integration team in order to access the Canadian bank form.

Have your bank account direct deposit routing and account numbers handy:

Add more app bank details

Tell us how often you would like to receive payouts by using the "period" drop down.

While this step isn't necessary to do before making API calls, it's a one-time set up, and lets you receive payouts daily (midnight settlement), weekly (every Monday), or monthly (first of the month). If these days are a bank holiday, it'll be the next day.

Subscribe To API Notifications

Notifications are webhooks sent by the API to deliver information about your merchants, payment processing, and payment operations.

The lifecycle follows this general pattern:

1. Receive a notification from WePay about a payment, merchant, payout, or other operation.
2. Inspect content of the Notification Signature to ensure that the notification is intact and sent from WePay.
3. Inspect payload.create_time to determine chronology, not the event_time of the notification itself

If a Notification fails to reach your servers, we will attempt to retry following this pattern:

• 1st retry will happen 15 minutes after the initial attempt.
• 2nd retry will happen 30 minutes after the 1st retry.
• 3rd retry will happen 1 hour after the 2nd retry.
• 4th retry will happen 6 hours after the 3rd retry.
• 5th retry will happen 12 hours after the 4th retry.
• 6th retry will happen 24 hours after the 5th retry.

When you transition to production on your dashboard, the WePay team will validate your Notifications implementation. Notifications are not stored permanently. If you haven't subscribed to notifications, you won't be able to retrieve older notifications once subscribed. However, once subscribed, Notifications are stored for 30 days.

Subscribe to API Notifications with a POST /notification_preferences request.

Recommended API Notification Subscriptions:

• accounts.created
• accounts.capabilities.updated
• payouts.failed
• disputes.created
• disputes.resolved
• legal_entities.verifications.updated
• payments.completed
• payments.canceled
• payments.failed

Supply Risk Information

As a platform, it's extremely important to make sure you're providing WePay with Risk information about your merchants, payers, and transactions.

If required by the WePay team, you may need to send Items and Orders in addition to rBits, to augment your risk data. By providing this data, you'll provide the WePay Risk team with richer data to continue leveraging our sophisticated risk algorithms, and ultimately better protect you and your merchants.

Refer to the Risk Certification to identify standard required rBits, and be sure to work with your WePay integration team to be sure there are no custom modifications which WePay may require.

Add Rbits

We'll first walk through the inline flow. Let's say you're processing payments. All these calls accept an array of rBits, that you define inline.

For example, let's say you want to attach the Transaction Details object to your Payments. You've noticed a significant increase in payments, of which a bunch were spam. As such, you now add in Transaction Details as an rBit to get ahead of the problem.

{
  "rbits": [{
    "receive_time": 1367958263,
    "type": "transaction_details",
    "source": "user",
    "transaction_details": {
      "itemized_receipt": [
    	{
    	"amount": 105,
    	"currency": "USD",
    	"description": "Premium lawn service package",
    	"item_price": "100",
    	"project_name": "Lawn service at 123 Fake St.",
    	"quantity": 1,
    	"service_billing_method": "hourly_billing_at_project_rate"
    	}],
      "note": "returning customer, new payment method"
    }
  }]
}

You'll notice that at creation time of a new Payment, an rBit array was included. If you choose to do so, you can pack more rBits into the array.

It's also not necessary to do the inline flow, as you can first create a Payment, and update it with rBits after creation.

Next, we'll walk through the 2-step flow. Let's say you're onboarding merchants and you define rBits after onboarding.

For example, you want to attach the External Account object to merchant Accounts. Once you receive an Account ID from WePay, create an rBit by sending a POST /rbits request like this:

{
  "address": {
    "account_type": "facebook",
    "connections": "2000",
    "create_time": 1235635140,
    "feedback_score_percent_positive": 0.87,
    "feedback_scores_provided": "476",
    "is_partner_account": false,
    "uri": "facebook.com.merchantblob"
  },
  "associated_resource": {
    "id": "{merchant-account-id}", // insert the merchant's account ID here
    "resource": "accounts"
  },
  "receive_time": 1367958263,
  "source": "guidestar",
  "type": "address"
}'

View the Full API reference to see where you can add rBits. In general, the more you add to your Accounts and Payments, the better overall experience and minimization of loss for your end merchants and payers.

Resource IDs

Resource IDs returned by WePay's APIs are case-sensitive. For instance, if the following is returned by WePay as an Account ID:

• d3f61e56-5d99-4895-af2d-a07ab48476e9

And you can later lookup that same account by making a GET request, even with just one letter in the wrong case:

curl -X GET \
  --url 'https://stage-api.wepay.com/accounts/D3f61e56-5d99-4895-af2d-a07ab48476e9' \
  -H 'Accept: application/json'\
  -H 'App-Id: XX'\
  -H 'App-Token: {}'\
  -H 'Api-Version: 3.0'

The account you are attempting to lookup will not be returned.

API Headers

All API calls require the below headers:

• POST /legal_entities
• POST /legal_entities/{id}
• POST /accounts -- When the payout structure is being sent
• POST /accounts/{id} -- When the payout structure is being sent
• POST /payment_methods

API Header Responses

API Versions

When interfacing with the WePay API, you can select which API version to pass. API versions are compatible with other versions, so you could make a call to certain endpoints using v3.1, and to others as v3.0.

If you do not need to use different versions, it's completely fine to use a single version. The latest version is 3.0.

API Rate Limits

By default, the API rate limit is 30 requests per endpoint and per account every 10 seconds on a sliding window.

As another example, say your app hit the same endpoint with 3 requests per second for seconds 1-9, and then sent 4 requests on second 10. The last request to come in would receive an error, and you would be able to send another successful request on second 11.

Default Permissions

When you register for API credentials with WePay, your credentials will have access to certain components by default. In order to get access to permissioned features, work with your WePay integration team.

{
	"error_code": "NOT_AUTHORIZED",
	"error_message": "FEATURE_NOT_ENABLED_FOR_APPLICATION"
}

• Your platform's stage app-id
• A high-level description of your business
• Your business use case for the specific feature(s) being requested

When you register for API credentials with WePay, your app will automatically be configured with Default Permissions. If you want to use any features with Gated Permissions, be sure to work with your WePay integration team to get access. Keep in mind that Gated Permission features may have prerequisites or other requirements that you must meet.

Idempotency

In error scenarios, retrying a payment and refund can lead to overcharging a payee or drawing too much from a merchant. In order to safeguard against these scenarios, you will use the "Unique-Key" key and unique value (generated by you) in the request header. You can use any value for the Unique Key, as long as it's unique.

As an example, let's say your platform handles rent between landlords and tenants. A good unique key could be the tenant's payment date, so that double payments do not occur.

For all POST calls made to /payments and /refunds, you are required to send "Unique-Key" in the header. The Unique-Key requirement makes these POST requests idempotent and safe, nullifying duplicate successful requests. For all other POST calls, the Unique-Key is optional. In general, a Unique-Key is valid for 24 hours.

Using Magic Headers

Errors

Avoid Hanging API Requests

Our API services will timeout after 30 seconds if no response is returned within that timeframe. It is recommended that you adjust your timeout settings to reflect this, in the case that your API request takes a little longer to process.

Handle 500s

Note that 503 errors indicate that a known issue caused the error, but that the request can be retried at a later time.

In the case of a 500 returned on /payments or /refunds, you will need to implement proper retry logic, depending on a Card Present (CP) or Card Not Present (CNP) transaction flow.

Card Not Present transactions

In general, you should implement a back-off strategy upon receiving the first 5xx error code (like an exponential back-off). If a 5xx HTTP error returns for a request with a unique key the first time, resend the request with the same unique key, and carry on until you reach the threshold for your exponential back-off window (or the payment succeeds with a non 5xx error code).

If you reach the end of your retry window for back-off, grab the correlation-ID in the response header, and escalate the payment issue to WePay.

Card Present transactions

Handle 400s

Custom Data

Custom data refers to a key-value object that can be passed in most API calls. The point of custom data is to add any additional metadata you need to store for resources, that you can't store using predefined fields. There is a limit of 10kb for custom data objects.

As an example, let's say you wanted to create a Payment resource, and wanted to store the payer's user name on your platform in the WePay Payment API object. You could add a key value pair to custom data, like so:

"custom_data": {
    "merchant_username": "merchant1"
}

Custom Data is available on all API resources, except:

• rBits
• Orders
• Items

Handle Communications

WePay will handle payment-related communications to your end users. There are a few exceptions:

• Micro deposit emails for manually verified bank account payment methods

Despite that, it is beneficial to subscribe to Notifications just to be aware of what communication is being sent to Merchants and payers on your platforms. When deciding which notifications to subscribe to, it is important to note that implementing Notification Signatures ensures a higher level of security by validating that all notifications are coming from WePay.

Below are recommended Notification event topics to subscribe to related to end user email communications: