General

 

How does the API work

 

At a high level, the WePay API allows websites and applications to make calls to WePay’s payment engine. The WePay payment engine handles payment processing, and WePay handles risk, compliance, and operational management.

Any WePay user is free to use the WePay API, although coding experience will be required. To comfortably interact with the API, a user should have a solid background in interfacing with an API, and front-end development. A list of Software Development Kits can be found here for various languages.

WePay’s terms of service apply to the users of the API. If you can’t sell it with the core platform, you won’t be able to sell it with the API.

What is the difference between Stage and Production?

 

The stage server and main production site are completely independent environments and have different databases. All the account ids, user ids, application ids, application tokens, etc. are different between stage and production environments. After you test your application on stage, you will need to create the application on production and use the production application ID and secret to connect to the production environment. Please note that the stage server does not process or move “real” money and, for example, allows the use of fake credit card number for testing.

How do I find my account credentials?

 

You can find your account and API credentials on the ‘API Keys’ tab of the App Center. This is where you will locate your:

Client ID - the ID of your API application.

Client Secret - This is a secret value for your API application. Do not share this with anyone (including us!)

Access_Token - This is the access_token that grants your app permission to do things on behalf of the application owner.

Account_ID - this is the ID of the payment account where you can collect money. All app_fees will be deposited into this account. This is a globally unique account.

WePay will never ask you for your production environment Client Secret or Access_Token.

What if I have a problem with SSL certificate verification?

The SSL certificate verification error reported by cURL library indicates that the cURL client does not have the correct trusted certificates configured:

Uncaught exception 'Exception' with message 'cURL error while making API call to WePay: SSL certificate problem, verify that the CA cert is OK. Details: error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed'

Typically, this means that you have a very old (pre 7.18.0) version of cURL (see explanations in cURL docs. You should update your Curl package and check if it solves the problem by running the following command:

curl -G -v https://wepayapi.com/v2/account

If it works then webserver or php-fpm restart everything should work just fine. Otherwise,you can configure the trusted certificates manually as it is explained in this article.

What is an access token?

The access_token is a long string of letters and numbers that you include in API calls to let us know what user you are making the API call and what permissions your app has for that user. Each access token is associated with:

  • A user
  • An API application
  • The permissions that the Api Application has to do things for the user

So when you make an API call with an access token, the WePay API will be able to tell what App you are and what user you are making the call for just from the access token. If you want to make a call for user #1 you need to use the access_token you have for user #1, and if you want to make an API call for user #2, you should use the access token you have for user #2. For security reasons, the access token should NEVER be passed as a get or post argument. The access token should be passed in the ‘authorization’ HTTP request header. For more information on how to make an API call with an access_token see this tutorial: Making API calls

What will the credit card statement look like?

For API payments, the credit card statement will always be of the form “WPY*account_name”. Here the account_name is the name of the account created using the WePay API for a particular user. The character limit varies from bank to bank, but it usually is 14 to 20 characters.

Please note that if a payment is not in captured state and is only authorized, most banks use the Merchant of Record’s name on the credit card statement. In this case, the credit card statement will simply say “WEPAY, INC.” This also applies to auth requests and for AmEx payments where the receiving merchant has not completed KYC.

How can an access_token get revoked?

Access tokens can be revoked two ways:

  • The user goes to their user settings on WePay and manually revokes the access_token.
  • Your app requests a new access_token via the /oauth2/token call. Each time you make the /oauth2/token call, we revoke all access_tokens for that user that were previously issued to your app. You should only make the /oauth2/token call if the current access_token does not work.

Should I email you my access token or client secret? NO!

NO! Please always keep any access tokens you have secret. They should be handled with the same care that you handle a user’s password. Email is not a secure communication medium, so you shouldn’t include any non-public user information in any emails that you send to us.

What information CAN you send us? The following public information is fine, and will better help us solve any problems you have:

  • client_id
  • account_id
  • user_id
  • checkout_id
  • preapproval_id
  • withdrawal_id

How can I hide the fees from the payer during the checkout flow?

If you set the fee_payer parameter to payee on the /checkout/create and/or /preapproval/create calls, then the WePay fee will be charged to the recipient of the funds and will not be displayed to the payer.

Where can I view the current WePay API status?

The real-time WePay Status page displays the current status of our stage and production environments, scheduled maintenance, and upcoming releases.

What happened to the settled checkout state?

We are always improving our API, and to streamline the checkout and withdrawal states, we are removing the “settled” state. This will also allow us to process chargebacks in very rare cases that occur outside our current settled state timelines. In these rare cases, a transaction can be reversed more than 180 days after the date it was recorded as “captured”.

If you would like to read the relevant MasterCard rules, please refer to section 1.7.3 of MasterCard’s Chargeback Manual.

To support this change, we will be migrating all “settled” transactions to the “captured” state in the 02/19/14 release to our production environment. This is to allow for rare cases in which a merchant may receive a chargeback beyond 180 days (previously the “settled” date).

If you store the “settled” state in your database, you can migrate it to “captured”. Fortunately, this is not a breaking change, as your integration will not be affected, but we recommend this change for proper reporting. This change will also enable us to better support partner and merchant requests for refunds and transaction updates.

Can I create subscription payments?

 

Yes, WePay’s API gives you a flexible way to create recurring charges. You can use it for anything from yearly product subscriptions to recurring rent charges. Most subscription charges are created using the /preapproval call.

Can I let my users accept payments into their own accounts?

 

Yes, a use case in which you need your own users to be able to accept payments is the WePay API’s specialty. WePay’s own flexible account structure makes it very easy to quickly provision accounts to your users via an Oauth2 connect. Money collected through your application can easily be stored in these accounts until your users are ready to access it.

What’s the best way to test out the WePay API?

 

Use WePay’s staging server! You can create an application on stage.wepay.com and run tests just as you would on our production server. Quick note, though - you will need two sets of login credentials - one for staging and one for production.

I am an advanced developer. How do I jump in?

 

You can transition to production by signing up at wepay.com/signup. Normally, you will start by making test calls in the staging environment, which is stage.wepay.com/signup.

What API Languages does the WePay API use

 

WePay’s API is language-agnostic, but we do provide SDKs for the most popular languages, including PHP, Ruby, Python, and NodeJS.

How do refunds to my customers work?

 

You can easily issue refunds to your customers via the checkout/refund call. The WePay API also supports partial refunds, if that applies to your use case.

Do refunds cost me anything?

  Refunds issued via the API don’t cost your account anything, and your customer receives 100% of the original charge back.

Where can I ask a question if I need help?

  Send us an email at api@wepay.com!

Can I put a WePay button on my own fundraising page or website?

 

WePay serves the unique needs of online platforms and marketplaces that seek to offer their users integrated payments. WePay does not currently offer direct merchant services and support. This means that WePay cannot be hosted on individual websites outside of our partner platforms.

Please note that there are many third party services which offer a WePay plugin, but these are not created nor supported by WePay.

If your business model is a platform service connecting payers and recipients, please to reach out and become a partner: https://go.wepay.com/getting-started

What is an IPN

 

Instant Payment Notifications (IPNs) allow you to receive notifications whenever the state on an object changes (or something important happens to that object).

To set up IPNs for an object, set a callback_uri on that object. Whenever something important happens to the object that we think you should be notified of (typically a state change), we will make an HTTP POST request to your callback_uri with the object_id in the body of the request.

IPN HTTP Request Details

The HTTP request that we make to your callback_uri will have the following characteristics:

It will be a POST request The object_id will be in the body of the request (and not added as a url-parameter) The object_id will be named for the type of object (for example checkout_id=12345 or account_id=51232) For checkouts and preapprovals, the reference_id will also be in the body of the request (if a reference_id was set). We will preserve any url-parameters you add to the callback_uri (so you could receive a POST request to http://example.com/ipn?user=12345)

If your callback_uri returns a non-200 response code when we make a HTTP request, we will consider the IPN to have failed. If the IPN fails, we will retry 6 times:

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

Does WePay Share The IP From Where IPNs Originate?

 

WePay does not share that information, unfortunately. Because WePay reserves the right to change the IP at any point in time, we choose to not share it.

How can I choose who pays the app fee?

 

You can specify who pays the app_fee by setting the fee_payer parameter when you make your /checkout/create call. There are four separate fee_payer values you can choose from:

payer - the payer will pay both the application and WePay fees.

payee - the payee will pay both the application and WePay fees.

payer_from_app - the payer will be charged the application fee, and your platform will be charged the WePay fee.

payee_from_app - the payee will pay the application fee, and your platform will be charged the WePay fee.

The fee_payer parameter is not required, and by default all fees will be charged to the payer.

Can I do split payments with WePay?

 

Yes, split or chained payments can be done with WePay. A split or chained payment is when credit card information is collected once and then used in one or more payments for different recipients.

For example, suppose you are a crowdfunding platform and you have fundraisers on your site. When a donation is made, the donor is given the opportunity to donate an additional $5, which will be sent to a second charity.

You can read more about Split and Chained payments here.

How do I issue a full or partial refund?

 

Use our /checkout/refund endpoint to issue full and partial refunds on behalf of your users.

Full Refunds

To issue a full refund via the API, you simply need to make a /checkout/refund call and pass in the checkout_id and refund_reason.

Alternatively, you can issue refunds on behalf of your users by logging in to your WePay Partner Dashboard, navigating to the Data tab, and selecting the Checkouts drop down. From there you can find the relevant transaction, click on it, and use the blue Refund button.

Partial Refunds

You can issue a partial refund by making a /checkout/refund call and passing in the optional amount and app_fee parameters. The amount specifies the total amount refunded to the payer, and the app_fee specifies the portion of the amount that will be refunded by the application.

For example, if the amount is 100,00 and app_fee is 10.00, then the payer will receive a refund of 100.00, where 90.00 is the net refund from the payment account, and 10.00 is the app_fee refund. Note that this value must be less than the remaining balance of the app fee.

Why did this credit card fail to authorize

 

When you make a /credit_card/authorize call to save a credit card for future use, we run all the same checks as an actual payment (with the exception of checking for an available balance). You can think of this like making a payment for $0.

If you receive an error stating that we failed to authorize the card, this means the credit card issuer declined the authorization. The most common reasons for failure include:

  • Address verification (AVS) mismatch
  • Invalid CVV/Expiration
  • Card is flagged as lost or stolen
  • Risk or fraud decisions from the issuing bank

When a card fails authorization, we recommend having the payer verify the card information they entered, and if that is all correct, having them reach out to their card issuer to verify their billing information and attempt the payment again.

Why isn’t all the content shown in the iframe

 

Our standard iframe sizes are outlined here.

For best results, we recommend that you set the following sizes for the iframes when working on your design and integration:

  • Standard Horizontal: 600 x 300 px
  • Standard Vertical: 300 x 600 px
  • Extended Horizontal: 600 x 400 px

How can I customize the iframe, emails, or OAuth2?

 

WePay allows you to customize the OAuth2 Authorization page, the iframe checkout, withdrawal flow, and API emails to match your site’s design. You can add customization through your App dashboard.

  • Log into WePay and go to your App’s dashboard by clicking on the name of your application.
  • Click the “Configure” tab.
  • Scroll down to the Logo section to upload an image.
  • Scroll down to the Colors section and click ‘Customize colors’ to change the primary, secondary, background, and button colors for the iframe.
  • Click ‘Save’ to save your changes.

Customizing Email Messages

Some calls, like /checkout/create, have parameters that let you pass an email message (generally payer_email_message and payee_email_message). These parameters accept a whitelisted set of HTML tags so that you have limited layout/design control over your custom message. Here is the whitelist:

- <strong>
- <em>
- <b>
- <a>
- <br>
- <br />
- <dl>
- <dd>
- <span>
- <table>
- <tr>
- <td>
- <tbody>
- <thead>
- <tfoot>
- <div>
- <img>

What is WePay’s Browser support policy

 

WePay supports most browsers, but javascript and third-party cookies must be enabled. Below is a list of supported browser versions:

Browser Support

  • Chrome 30.0 and later Platforms: Windows 7 and above, OS X (10.7+), Linux, Android (4.0+), iOS(7.0+), Chrome OS

  • Firefox 24 - 26 Platforms: Windows 7 and above, OS X (10.7+), Linux, Android (2.3+), iOS(7.0+). NOTE: TLS1.2 support needs to be enabled for apps. 27+ Platforms: Windows 7 and above, OS X (10.7+), Linux, Android (2.3+), iOS(7.0+)

  • Safari Version 7 Platforms: OS X 10.9 Version 8 Platforms: OS X 10.10 Version 9 OS X 10.11

  • Internet Explorer Version 8-10 Platforms: Windows 7, Windows Server 2008 R2 NOTE: TLS1.2 support needs to be enabled for apps Version 10 Platforms: Windows 8, Windows Phone 8 NOTE: TLS1.2 support needs to be enabled for apps Version 11 Platforms: Windows 7, Windows Server 2008 R2, Windows 8.1, Windows Server 2012 R2, Windows Phone 8.1