Get Started

Sign Up

Core partners will need to work with their WePay integration team to get your API credentials.

Review API Basics

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:

Copy

Copied

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

A set of headers are required for all API calls, and certain endpoints conditionally require more. As a reminder, access API credentials here.

All API calls require the below headers:

Header Key	Header Value (example)
App-ID	`123456`
Api-Version	`3.0`
App-Token	`stage_MzBfNzM2ZmEwYTItZmQ1My00MYg1LEEwYmMtYzE2MmMzNDIyZDIz`

API Header Responses

Response headers from WePay will contain an X-Correlation-Id. At a minimum, it should be stored for each /payments and /refunds request, though storing the correlation ID for requests to every endpoint is recommended. These IDs will help with debugging should the need arise.

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.

The endpoint API rate limit ensures that if a single service (like creating information with POST /accounts/id) sees a spike, then other services will not be impacted (such as finding accounts with GET /accounts).The account API rate limit ensures that if a single merchant's Account ID sees a spike in a single endpoint (like POST /accounts/id requests), other merchants' ability to reach that endpoint will not be impacted.The rate limit is calculated using the sliding window algorithm, meaning that API requests are measured on a rolling basis. If the limit is exceeded, an API error will return and the details will indicate which throttle (endpoint or account) was activated.Example
If your app attempts to send a total of 31 requests to a single endpoint in a sampling period of 10 seconds, then the last request in chronological order will receive the THROTTLE_EXCEEDED API error. If 31 requests were sent in the first second, you will be able to successfully send new requests at 11 seconds. On the other hand, if 15 requests were sent on second 9, and 16 requests were attempted on second 10 (1 would be throttled on second 10), you will then be able to send 15 un-throttled requests on second 19 (once second 9 is no longer included in the sliding window), and another 15 on second 20.

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.

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.

Subscribe to Notifications

Notifications are Webhooks sent by the WePay system to you, the PayFac. For Onboarding as a PayFac, it is not mandatory to subscribe to any API Notifications. That being said, they will help you understand a sub-merchant's onboarding progression. For example, an API Notification can update you about a sub-merchant's entered KYC data, and whether more information needs to be supplied.

Subscribe to API Notifications with a POST /notification_preferences request. In general, the topics used for Onboarding as a PayFac are:

legal_entities.*accounts.*

If a Notification fails to reach your servers, we retry with the following pattern:

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

WePay defines “failing to reach your servers” as receiving any HTTP code other than 200 or 201, and this includes network retries. API Notifications are stored on WePay's end for 30 days, and so aren't permanently kept. If you haven't subscribed to API Notifications, you won't be able to retrieve older API Notifications once subscribed.

Questions? Need help? Visit our support page!