Get Started

Sign Up

Start by heading over to partner.wepay.com.

We recommend using an aliased email address to sign up (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.

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.

Contact our Sales team to confirm the ability of your platform to obtain Production access.

Confirm Email Address

Make sure to confirm your email address once you've finished signing up for an account. If you haven't, be sure to visit here, and click the banner to resend the confirmation email.

A banner reminding you to confirm your email

Sign In

Once sign up has been completed, log in to your account with your confirmed email.

The first screen you will see is set to the Staging environment, and before you can start testing the API, you will need to generate your App Token.

Main App screen

Generate App Tokens

Before you can make an API call, you'll need to grab your App ID, API version, and App Token. You'll need to generate an App Token through the Partner Center. Simply click “Create Token”, enter a unique name, and hit save.

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 three tokens, though it is not necessary to generate more than one token. 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 Core API.

Recommendation

As a security precaution, rotate your App Tokens every 3 months by visiting the Partner Center. Delete your current tokens, create new tokens, and replace your old tokens with your new ones.

Stage vs. Production

Base URL	Environment
`https://stage-api.wepay.com`	Stage
`https://api.wepay.com`	Production

When you finish signing up for an account, you'll begin in the stage environment. Your API credentials will let you make API requests to the https://stage-api.wepay.com base URL, appended with an endpoint. The stage environment is intended for use in the development and prototyping of your application.

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.

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, you're required to submit personal and business details before you can access the production environment.

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 select which API version to use by passing it in the Api-Version request header. 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 our 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.

We define “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 our 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.

Next to Onboard Sub-Merchants

Questions? Need help? Visit our support page!