API Basics

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. This page is a full list of features to use depending on your use case – keep it handy.

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

Resource IDs

It is important to note that resource IDs returned by WePay are case-sensitive. For instance, if the following is returned by WePay as an Account ID:

• d3f61e56-5d99-4895-af2d-a07ab48476e9

And you later send a GET request for that same account like so, 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: 12121'\
  -H 'App-Token: '\
  -H 'Api-Version: 3.0'

Then the account you are attempting to fetch will not be returned.

API Headers

As with all API calls, you need to pass required headers. First, let’s cover the required headers for all API calls to WePay, across products. As a reminder, you created your API credentials during account sign-up. Access them here.

In order to safely retry payment (/payment) or refund (/refunds) calls, you need to use the “Unique-Key” header, which is a uniquely defined value. Read the Idempotency section below for more information.

Additionally, the “Client-IP” and “WePay-Risk-Token” headers are required on the following endpoints if your platform is not using the WePay JS for tokenization:

• Clear only POST /legal_entities
• Clear only POST /legal_entities/{id}
• Clear only POST /payout_methods
• Clear only POST /accounts – When the payouts structure is being sent
• Clear only POST /accounts/{id} – When the payouts structure is being sent
• POST /payments – When the payment method is being sent in-line
• POST /payment_methods

Finally, look to the table below to see the base URLs you will interface with. All resources found on the API reference are appended to the base URLs.

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

As a default, we have a rate limit across endpoints of 30 requests per 10 seconds. If you have a business use case that requires a higher rate limit, please speak to your account manager or API Support, at api@wepay.com.

Permissions Based Features

When road-mapping your integration with WePay, it’s important to remember that certain endpoints and parameters require permission for use. Sending calls to restricted endpoints or with restricted parameters will result in the following error:

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

During your planning, take note of each feature you’d like access to and submit a request to your account manager, technical account manager, or WePay’s developer support (api@wepay.com). Your request should include:

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

Restricted Features

Errors

WePay’s API follows standard API conventions with errors. You can view the API reference documentation for an exhaustive list of error codes. Throughout the integration guide, we will also highlight special errors and remediation strategies.

In general, 500 HTTP errors indicate that an unknown error occurred. If a 500 HTTP error is received, check the WePay Status page. If no current issues are reported there, then reach out to API Support or your technical account manager (if applicable).

That said, 503 HTTP errors indicate that a known error occurred, and that the request can be re-tried after some time. Implement your own re-try logic so that if a 503 HTTP error is received, you can programmatically handle it.

Idempotency

Making GET calls will not modify resources, and sending a POST to an endpoint will update the fields provided in the POST body only. If you’d like to delete a field in an object, send a POST with the field set to NULL. For complex objects, like beneficial owners– where you may not have all data at once–pass an empty object, like {}. This lets you progressively update the Legal Entity object.

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.

If a 5xx HTTP error returns for a request with a unique key, try resolving the issue with the request and resending it with the same unique key.

If a 4xx HTTP error returns for a request with a unique key, that Payment cannot be processed. This means that new information must be submitted by the user, and a new unique key should be used on the new request. Refer to error code documentation here for further information on error responses.

For all POST calls made to /payments and /refunds, you are required to send “Unique-Key” in the header. For all other POST calls, it is optional. In general, Unique-Key is valid for 24 hours.

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

And any time you retrieve or update this payment, the custom data will be stored and returned. Custom data is a JSON object, and allows for nesting. The API will not overwrite custom data, and will append new keys/values. If you’d like to remove keys and values, assign existing keys to null, or, to remove the keys, set custom_data to null, and re-add data. Do not send personally identifiable information (PII) through custom data.

Custom Data is available on all API resources, except:

• rBits
• Orders
• Items

Next Up: Setup Platform

Align your app’s configurations with the type of integration you want.

• Use the Javascript library
• Send risk information programmatically
• Send required emails to end-users

Questions? Need help? Visit our support page!