API
Log In Support
  • Clear

    • Get Started

      • Overview

      • Platform Sign Up

      • API Basics

    • Integration

      • Setup Platform

      • Onboard Merchants

      • Enable Merchants

      • Process Payments

      • Payout Merchants

      • Manage Payment Operations

      • Test and Launch

  • Link

    • Get Started

      • Overview

      • Platform Sign Up

      • API Basics

    • Integration

      • Setup Platform

      • Onboard Merchants

      • Process Payments

      • Manage Payment Operations

      • Test and Launch

    • CARD PRESENT SOLUTIONS

      • Get Started

        • Overview

      • Terminals

        • Acquire Terminals

        • Onboard Terminals

        • Authorize Cards

        • Process Payments

        • Test and Launch

      • Mobile Card Readers

        • Build Mobile App Prerequisites

        • Acquire Mobile Card Readers

        • Pair A Device

        • Authorize Cards

        • Process Payments

        • Test and Launch

      • Card Present Resources

        • Provide Receipts

    • API Reference

    • Resources

      • Payment Life Cycles

      • Server to Server Integration

      • Platform Legal Certification

      • Security Certification

      • Risk Certification

      • CIP and KYC Certification

      • Card Network Rules

      • Disputes Deep Dive

    • Cookbooks

      • Build Payment Support Tools

      • Reporting

      • Implement Merchant IC+ Pricing Model

      • Recurring Billing

      • Level 2 & Level 3 Processing

      • Style Credit Card iFrames

      • Support Merchants Outside the United States

      • Support Multilocation Merchants

      • Connect Merchants With SSO

      • Design A Retry Strategy

    • Release Notes

Home / Clear Overview / API Basics

 

API Basics

 

In This Section
  • Resource IDs
  • API Headers
  • API Versions
  • API Rate Limits
  • Default Permissions
  • Idempotency
    • Using Magic Headers
  • Errors
  • Custom Data

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.


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

 

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

All API calls require the below headers:

Header Key Header Value (example)
App-ID 123456
API-Version 3.0
App-Token stage_MzBfNzM2ZmEwYTItZmQ1My00MYg1LEEwYmMtYzE2MmMzNDIyZDIz
Content-Type application/json

POST calls to the payment (/payments) and refund (/refunds) endpoints require “Unique-Key”, in addition. The value for Unique-Key is defined by you, and we outline strategies in the below Idempotency section.

Finally, send “Client-IP” and “WePay-Risk-Token” if you are not using the WePay JS, for the below endpoints:

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

Note

If you’re sending the WePay risk headers on the above server to server requests (as opposed to using the WePay JS), please be sure to follow our Server to Server Integration guide for Clear.

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.

 

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.

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

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 endpoint per 10 seconds. The rate limit is calculated using the sliding window algorithm, meaning that API requests are measured on a rolling basis.

Throttling per endpoint ensures that if a single service (like creating payments) sees a spike, then other services will not be impacted (such as looking up accounts).

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.

 

Upcoming Enhancements
Starting mid-Q2 2021, WePay will implement account-based and endpoint-based throttles in addition to the existing app-based. This will help ensure that:

  1. If a single merchant sees a spike in API requests, your other merchants won’t be impacted
  2. If your app sees a spike in reaching the POST /payments endpoint, your ability to reach other endpoints won’t be impacted

If a throttle limit is exceeded, then the error reason will identify which throttle is in play.

Summary of changes

Old throttle Current throttle mid-Q2, 2021 throttle
  • An app could make 30 API requests per 10 seconds
  • Calculated with the dripping bucket algorithm
  • Each app can make 30 API requests per 10 seconds
  • Calculated with the sliding window algorithm
  • (Account-based throttle) Each merchant (API Account ID) can reach the POST /payments endpoint 30 times per 10 seconds
  • (Endpoint-based throttle) Each app can reach the POST /payments endpoint 30 times per 10 seconds
  • (App-based throttle) Each app can make 30 API requests per 10 seconds
  • Calculated using the sliding window algorithm

Default Permissions

 

When you register for API credentials with WePay, your credentials will have access to pre-built components by default. In order to get additional permissions for custom components, work with your WePay integration team.

Sending calls to endpoints or with parameters which are not included in the default permissions 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

When you register for API credentials with WePay, your app will automatically be configured to use Pre-Built Components (found in the Default Permissions column below). If you want to use any Custom Components (or other restricted features), you’ll need to work with your WePay integration team to configure your app with those permissions. Endpoints and parameters which require enablement from WePay in order to use are listed in the Custom Permissions column.

Default Permissions Custom Permissions
Legal Entities
  • /legal_entities GET, POST
  • /legal_entities/{id} GET, POST
  • /legal_entities/{id}/verifications GET
  • /legal_entities/{id}/set_controller_password POST
  • /legal_entities/{id}/verifications POST
Accounts
  • /accounts GET, POST
  • /accounts/{id} GET, POST
  • /accounts/{id}/capabilities GET
  • /accounts DELETE
  • /accounts/{id}/capabilities POST
    • application_block
  • beneficiary_legal_entity_id on either of the following POST requests:
    • /accounts
    • /accounts/{id}
Payouts & Payout Methods
  • /payouts GET
  • /payouts/{id} GET
  • /payout_methods GET
  • /payout_methods/{id} GET
  • /payouts/{id} POST
  • /payout_methods POST
    • paper_check
  • /payout_methods/{id} POST
Payments & Payment Methods
  • /payments GET, POST
  • /payments/{id} GET, POST
  • /payments/{id}/cancel POST
  • /payments/{id}/capture POST
  • /payment_methods GET, POST
  • /payment_methods/{id} GET, POST, DELETE
  • /payment_methods/{id}/verify_bank_deposits POST
  • /payments POST with any of:
    • payment_method.credit_card
      • auto_update
      • optional cvv
      • virtual_terminal_mode
    • payment_method.payment_bank_us
  • /payment_methods POST with any of:
    • credit_card
    • payment_bank_us
Note: By default, Payment Methods can only be tokenized via the credit card and payment bank iFrames. Requests sent with tokens from any source other than the iFrames will result in error.
Refunds, Disputes, Adjustments, & Recoveries
  • /refunds GET, POST
  • /refunds/{id} GET, POST
  • /disputes GET
  • /disputes/{id} GET
  • /adjustments GET
  • /adjustments/{id} GET
  • /recoveries GET
  • /recoveries/{id} GET
  • /refunds/{id} POST
  • /disputes/{id} POST
  • /disputes/{id}/concede POST
  • /adjustments/{id} POST
  • /recoveries/{id} POST
Transaction Records and Billing Statements
  • /transaction_records GET
  • /transaction_records/{id} GET
  • /billing_statements GET
  • /billing_statements/{id} GET
  • /billing_statements/{id}/fees_summary GET
  • /billing_statements/{id}/transactions_summary GET
Orders, Items, & rBits
  • /orders GET, POST
  • /orders/{id} GET, POST, DELETE
  • /items GET, POST
  • /items/{id} GET, POST, DELETE
  • /rbits GET, POST
  • /rbits/{id} GET, DELETE
Terminals & Session Tokens
  • /terminals GET
  • /terminals/{id} GET, POST
  • /terminals POST
  • /terminals/{id} DELETE
  • /terminals/{id}/activate POST
  • /terminals/{id}/deactivate POST
  • /session_tokens POST
Notifications & Notification Preferences
  • /notifications GET
  • /notifications/{id} GET
  • /notification_preferences GET, POST
  • /notification_preferences/{id} GET, POST, DELETE



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.

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.

For more information on error handling and retry strategies, see the Design A Retry Strategy article.

Using Magic Headers

Magic header values trigger a given behavior by including a magic value for the WePay-Magic-Behavior key in the call header. These calls will return static responses, regardless of the API request body that you send, and are intended to provide the full structure of a response under certain circumstances for you to model additional testing and development against.

Making idempotent POST/ payments requests to test your application is made easy with the use of Idempotency_Downtime_xxx and Idempotency_Retry_xxx as Magic Headers. Idempotency_Retry_xxx will delay the next xxx requests by returning simulated 500 errors. Requests sent with this unique key, Idempotency_Downtime_xxx, will return simulated 500 errors over the next xxx seconds. Notes, that you are responsible for defining xxx with the amount of requests or seconds you’d like the Magic Header to effect.


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.

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

 

In general, 500 HTTP errors indicate that an unknown error occurred and are safe to implement your retry logic for. See Design A Retry Strategy to create the best retry logic for your particular integration with WePay.

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 use a different unique-key during your back-off, you run the risk of double-authenticating a payment. If you receive the API Error Code CONCURRENT_UNIQUE_KEY_REQUEST_IS_PROCESSING, you can keep retrying safely.

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

Like CNP transactions, in general, you should implement some type of back-off strategy when handling 5xxs. With CP transactions, however, a successful authentication at the terminal is sufficient to let a payer walk away from the terminal. Put another way, if you receive an encoded_payment_method, an authentication has happened and you can attempt to execute a payment with the same error handling as the above Card Not Present section.

Handle 400s

 

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.

Note

If you receive the API Error Code THROTTLE_EXCEEDED.APPLICATION_REQUEST_THROTTLE_EXCEEDED or CONCURRENT_UNIQUE_KEY_REQUEST_IS_PROCESSING, you can handle either of them as a 5xx HTTP error.


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

Warning

custom_data may not appear in the notification payload for any given notification event topic. To lookup the custom_data parameter for a specific notification, send an API request with the resource ID to the endpoint you would like to access.


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

 

Setup Platform

 


Questions? Need help? Visit our support page!

Company

  • About
  • Careers
  • Blog
  • News & Events

Resources

  • Knowledge Center
  • Terms of Service
  • Privacy Policy
  • Security
  • Support

Developers

  • Documentation
  • Engineering Blog

Customers

  • Case Studies

Product

  • Link
  • Clear
  • Core
  • Contact Sales
© 2020 WePay Inc.