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 in your use case – keep it handy.

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

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 roadmapping 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

Link Restrictions

Additionally, integrations with WePay’s Link product do not have access to the same endpoints as integrations with WePay’s Clear product. Link does not have access to the following endpoints:

• Legal Entities:
  • POST /legal_entities
  • POST /legal_entities/{id}
  • POST /legal_entities/{id}/verifications
• Accounts:
  • POST /accounts
  • POST /accounts/{id}
  • POST /accounts/{id}/capabilitites
• Payment Methods:
  • POST /payment_methods/{id}/verify_bank_deposits
• Payout Methods:
  • POST /payout_methods
  • POST /payout_methods/{id}
• Disputes:
  • POST /disputes/{id}
  • POST /disputes/{id}/concede

The above endpoints are only restricted when the function is POST. Link integrations will rely on GET calls to these endpoints, and these will be covered in the Link integration guides.

Similarly, while Link integrations will not have access to the above endpoints, Notifications related to those endpoints are still accessible. Subscribing to those Notifications will help keep data in sync between WePay and your platform.

Errors

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

Idempotency

WePay’s API is designed to be idempotent. Making GET calls will not modify resources, and sending a POST to an object will update the fields provided in the POST body. 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 {}, to continue building out the Legal Entity object, and update it when you have the inner fields.

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 in your request header, and a unique value, generated by you. You can use any value for the Unique Key, as long as it’s unique.

If a 500 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 400 or 300 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.

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. 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 username on your platform in the WePayPayment 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 keys and values must be strings. The API will not overwrite data, but continue to append new keys and values. If you’d like to remove keys and values, you can 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:

• Transaction records
• rBits
• Orders
• Items

Questions? Need help? Visit our support page!