API Change Log

2019-04-03

  • Enhancements to error handling - We’ve updated several of our API endpoints with more specific error responses and error codes. Following endpoints were updated:
    • /account/create and account/modify
      • When passed an empty name
        • Used to return: HTTP: 500, error code: 1008
        • Will now return: HTTP: 400, error code: 1003, error message: “Account names can't be empty or contain \"WePay\", please try again.”
      • When passed “wepay” as input for name
        • Used to return: HTTP: 400, error code: 1003, error message: “account name cannot contain wepay”
        • Will now return: HTTP: 400, error code: 1003, error message: “Account names can't be empty or contain \"WePay\", please try again.”
      • When there’s a conflicting update request
        • Used to return: HTTP 500, error code: 1008
        • Will now return: HTTP 400, error code: 1003
  • The /account/kyc/create API will now return a more descriptive error message with specific field names when a request fails address validation. This should help identify which specific address fields failed validation when calling /account/kyc/create with multiple addresses
    • e.g. for invalid country name:
      • Used to return: "error_description" : "Malformed address (Country is invalid)."
      • Will now return: "error_description" : "Invalid parameter business.us_entity_compliance.additional_beneficial_owners.0.address.country"
  • When sending an invalid phone number for /user/mfa/send_challenge
    • Used to return: HTTP 500, error code: 1008
    • Will now return: HTTP 400, error code: 1003, error message: “We were unable to send a verification code to the specified phone number, please try again or use a different number”
  • The /user/register API will now only allow alphanumeric characters for first_name and last_name fields. For all requests that do not meet this requirement, we will return a response with HTTP 400, error code: 7004, error message: “Names can only include alpha-numeric characters”
  • The /credit_card/modify API now allows you to modify the optional fields card_on_file and recurring on an existing credit card
  • We’ve removed the disputed_amount from the response for all the /account endpoints. Also, reconciliation will not be accounted for in the calculation of balance and reserved_amount in the response. This change applies to all the responses for /account endpoint
  • In order to standardize naming across request and response, we’ve renamed the optional field virtual_terminal to virtual_terminal_mode in the request body for /credit_card API. The accepted list of values in the request body for virtual_terminal_mode are: mobile, web and null. The default value in the response will be null. This change affects the request body for /credit_card/create and the responses for credit_card, credit_card/authorize, credit_card/find, credit_card/modify endpoints

2018-10-03

  • There are several important enhancements to the /account/kyc/create call.
    • Added new entity types for the US and Canada.
    • Added the job_title field to the Account Owner Structure.
    • Added the legal_form field to the CA and US Compliance Structures.
    • Added the start and limit fields to the /account/find call.
  • Implemented a restricted list of Merchant Category Codes (MCCs). If your platform is using API Version 2018-08-29 (or earlier), the API will continue to accept any 4-digit string.
  • The API will now return the SSN error in a new format and apply to the merchants of all entity types. If the controller or any additional beneficial owners are from the US and their SSN4 doesn’t match, the API will need to collect the full 9-digit SSN for each person.
  • Removed support for the KYC API in the United Kingdom.

2018-08-29

  • The /checkout/create call now supports in-line credit card data. This means you can create a checkout by supplying data using the new inline_credit_card field.
  • Enhanced error responses by returning two additional fields: details and documentation_url.

2018-03-21

  • The /account/kyc/create call now supports additional beneficial owners for business entities in the United States and Canada.
  • The following US region codes are no longer supported while creating an address for the entity or account owner using the /account/kyc/create call: AA, AE, AP, PR, and VI.
  • The EIN value 123456789 is no longer supported.

2017-05-31

2017-02-01

  • Several important changes to /account/kyc/create. To support sole proprietors, ein is a new optional parameter in the us_entity_compliance structure for entity type individual in the US; gst_hst is a new optional parameter in the ca_entity_compliance structure for entity type individual in Canada; and primary_url is a new optional parameter for entity type individual in the US and Canada. For businesses and nonprofit organizations, both ein for US merchants and gst_hst for Canadian merchants are now required fields. social_security_number_last_4 is now accepted for all US merchants upon the first submission of KYC; social_security_number must be submitted for US merchants of type individual that do not pass synchronous KYC validation upon the first submission (this is the full 9 digit social security number).
  • The /account, /account/create, /account/modify, and /account/find calls now have the support contact number parameter.
  • The mcc parameter in /account/create is now type String (4 chars) instead of integer.
  • The /account/kyc/authorize call response is now the same as /account/kyc.

2016-12-07

  • Added backing instrument information and added apple_pay and android_pay as possible input source values on /credit_card and /credit_card/find responses.
  • Added an optional parameter account_id for /credit_card/authorize to have the account name be used in the descriptor of the payer’s bank statement.
  • cvv is now an optional parameter for /credit_card/create if your application has been granted explicit permission to not pass the parameter.
  • postcode can no longer be used in the address structure for /credit_card/create. postal_code will be strictly enforced.
  • Validations on /credit_card/create have been tightened.
  • The /account/kyc response now includes the kyc_state and supporting_documents fields.

2016-08-10

2016-07-13

  • Delayed payouts to merchants for checkouts are now permissioned on a per-application basis.
  • The /checkout/capture endpoint has been renamed to /checkout/release. The functionality remains unchanged.
  • The /checkout/capture endpoint has been repurposed to allow partners to perform a true credit card capture (rather than releasing funds to merchants that was held due the delayed payout feature).
  • Delayed payouts to merchants is now invoked by setting the top-level auto_release parameter of /checkout/create to false. Formally, this top-level parameter was called auto_capture.
  • New parameter, auto_capture, in the credit_card and hosted_checkout blocks of /checkout/create. If this parameter is set to false, this will cause a credit card payment to only be authorized (but not captured) until a call to /checkout/capture is called with the corresponding checkout ID.
  • Former checkout state reserved has been renamed to ‘captured’, the former checkout state of captured has been renamed to released. The state transitions themselves remain unchanged. Please see the checkout documentation. Note that the state names will only reflect the new nomenclature when performing lookups using an API version of 2016-07-13 and later. Also, when viewing checkout data via an application’s data tab (www.wepay.com/apps/manage/{Your_App_ID}/data), the state names will only use the new nomenclature if the API version of the application is of 2016-07-013 or later.
  • The /credit_card/modify response format now matches the response format of the /credit_card and /credit_card/find calls.
  • New /credit_card and /credit_card/find response field, auto_update, of which reports the state of the auto_update field as set by the corresponding request field as specified in the /credit_card/create and /credit_card/modify calls.
  • The /credit_card/transfer endpoint now supports supplying only a postal code and country, rather than requiring a full address.
  • The /credit_card/transfer endpoint can now verify cards by performing a zero-dollar authorization via the new auto_authorize parameter, defaults to false.
  • New policy on Api-Version request header usage. Applications on API versions previous to 2016-07-13 will only be able to use the Api-Version header to hit versions up to (and including) 2016-07-13. For applications on the 2016-07-13 version and later, the Api-Version header value is constrained to current the application version, plus one. The /credit_card/create endpoint is exempt from any contraints on Api-Version header usage.
  • New address structure for all endpoints that use address fields. The zip and postcode parameters have been merged and is now called postal_code. Additionally, the state parameter has been replaced by region for all geos.
  • The prefill_info parameter for /account/get_update_uri now uses the KYC Prefill Info Structure.

2016-06-22

2016-05-18

2016-05-04

  • Added /payment_bank endpoint.
  • /checkout/create payment_method of type bank_account renamed to payment_bank.
  • /checkout/create: the funding_sources list in the hosted_checkout structure has been updated to use payment_bank instead of bank_account.
  • /checkout/create: the payment_error of type bank_account has been updated to be payment_bank.
  • The bank_account_id generated by tokenization.v2.js will now expire in 30 minutes unless a call to /checkout/create is called.

2016-03-30

  • Added payment_error structure to /checkout response.

2016-02-24

  • Added npo information to /checkout response.

2016-01-27

  • Added bank information to /checkout response.
  • /user/mfa/create now requires country_code when setting up an SMS or voice MFA

2015-11-18

  • Added transaction_token optional parameter to /checkout/create.
  • Added EMV receipt information to payment_method field of checkout response.

2015-09-30

  • Added supported_card_types response parameter to /account.

2015-09-09

  • Withdrawal API calls have been restructured and the /withdrawal/create call has been deprecated.

2015-08-15

The /checkout/create parameters have been restructured to allow WePay to support more payment options in the future. Existing apps do not need to switch to this new version, and the current version will be supported for the foreseeable future. We encourage new apps to start using the new version now.

2015-06-17

  • Added expiration_month, expiration_year and last_four response parameters to /credit_card/.

2015-06-03

  • Added input_source response parameter to /credit_card/.
  • Added virtual_terminal_mode response parameter to /credit_card/.
  • Added payment_method_type response parameter to /checkout/.
  • Added payment_method_id response parameter to /checkout/.

2015-02-25

  • Renamed user/resend_confirmation call to /user/send_confirmation/.

2014-08-27

  • Added optional state parameter to /withdrawal/find/.

2014-06-18

  • Added owner_user_id parameter to /account response.

2014-04-23

  • Successful /checkout/create now returns the full checkout object.
  • Added callback_uri parameter to /user response.
  • Updated WePay Python SDK version number, added error_code parameter before message parameter (when the WePayError is raised), and added changelog file.

2014-03-12

  • In our 2014-04-02 release, we will be rolling out a new UI for merchants on wepay.com to get information about withdrawals to answer the question: Where is my money?.

2014-02-12

  • Added optional tos_acceptance_time parameter to /user/register.
  • Removed the title on iframe versions of the /account/get_update_uri page.
  • When passing the email_message parameter to /user/resend_confirmation it will remove the default text provided by WePay.

2014-02-05

  • Simplifying checkout, subscription_charge and withdrawal states by removing state settled. All checkouts will now go to a final state captured. We will migrate existing checkouts on 02/19/2014 from state settled to state captured. You can find more info here.

2014-01-08

  • Released new WePay API Version 2014-01-08 with backwards-incompatible changes. Upgrade soon to get the latest and greatest WePay API functionality.
  • Added optional country and currencies parameters to /account/create call and returning them for /account, /account/find calls.
  • Added optional currency parameter to /checkout/create, /preapproval/create, /withdrawal/create, and /subscription_plan/create calls. Returning currency for /withdrawal, /withdrawal/find, /subscription_plan, /subscription_plan/find, and /subscription_charge calls.

2013-12-11

  • Added ability to delete Google Analytic domains associated with an account by submitting an empty array for gaq_domains parameter to /account/modify call.

2013-11-13

  • Added fallback_uri parameter to /withdrawal/create call.

2013-11-06

  • Added original_ip and original_device parameters to /credit_card/create call.
  • Added capture_time parameter to the /withdrawal call. This parameter shows the time this withdrawal was sent to the user’s bank account.
  • Simplifying withdrawal states to only include 6 instead of 9 states. Removed states authorized, cancelled and refunded.

2013-10-30

  • Added amount_charged_back and amount_refunded parameters to /subscription_charge call.
  • Added batch call tutorial.
  • Added iframe tokenization tutorial.
  • Added iframe section to withdraw tutorial.
  • Released WePay iOS SDK.

2013-10-23

  • Added amount_charged_back parameter to /checkout call.
  • Added state parameter to /app call.
  • Added subscriptions related error_codes on error responses to /developer/reference/errors.
  • Renamed transition_expire_time parameter to transition_expire_days /subscription_plan/modify call.
  • Renamed transition_expire_time parameter to transition_expire_days /subscription/modify call.

2013-10-16

  • Added Subscriptions related magic numbers $22.61, $222.61, $2622.61 to help with testing: see testing page.
  • Launching zip-only billing address for US payments. You can enable this option on your app dashboard -> configure tab.

2013-10-09

  • Added prorate parameter to /subscription/modify call.
  • Added transition_prorate, transition_quantity and transition_subscription_plan_id parameters to /subscription call.
  • Returning a new type prorated_charge for /subscription_charge.
  • Added end_time, prorate_time and amount_refunded parameters to /subscription_charge.
  • Changed state parameter returned by /subscription_plan, /subscription, /subscription_charge calls to be lowercase. It was incorrectly returning Proper case. Example: state will now be returned as active instead of Active.

2013-10-02

  • Released WePay Java SDK.
  • Mobile iframe optimizations - wider and taller input fields on mobile screens. Only available for iframe size 300px by 600px.

2013-09-25

  • Added soft_descriptor as a new response parameter for /checkout lookup call. It shows the descriptor that will appear on the payer’s credit card statement.

2013-09-18

  • Introduced the new Subscriptions API (beta release).
  • Added an ability to whitelist application IP addresses on the app dashboard’s Configure tab to provide additional security protection.
  • Added new Event column to IPN data tab on app dashboard.
  • Added throttle limits for API calls on the app dashboard.

2013-09-04

  • Added create_time as a return parameter for /account lookup call.

2013-08-21

  • Added WePay Status website to notify developers about upcoming releases, scheduled maintenance, and un-scheduled issues with stage/production environment.

2013-08-14

  • Added mode response parameter to /checkout and /preapproval calls.
  • Added splash screen when users verify their email after registering using OAuth2

2013-07-24

  • Added callback_uri parameter to /user/register call.
  • Returning state for /account, /account/modify, /account/delete and /account/find calls: active, disabled or deleted.
  • Sending IPN for account state changing to active, disabled or deleted.

2013-07-17

  • Added last_checkout_id and last_checkout_time as new response parameters for the /preapproval call.
  • Added last_checkout_id paramater to /preapproval/find call.
  • Added shipping_fee paramater to /preapproval/find and /checkout/find calls.
  • Started using the pending value for verification_state for /account calls.
  • Enforced automatic refunds/cancellation for checkouts with auto_capture=false.
  • Responsive withdrawal flow

2013-07-10

  • Added sort_order parameter to all /xxx/find calls. This allows you to sort the results of the search by time created.

2013-07-03

  • Added dispute_uri response parameter for the /checkout call. Users can visit that uri to dispute a captured or settled checkout.
  • Added new API call: /batch. This allows you to make up to 50 API calls within a single API call.
  • Expanded the /preapproval/find call to allow you to search for preapprovals on an application level instead of just an account level.
  • Added a “Charge a customer” tutorial specifically for platforms.

2013-06-26

  • Added 3 more retries for IPNs 6, 12 and 24 hours.
  • Added mcc parameter to /account/create call. Read more about the mcc parameter at the mcc reference page.
  • Added payee_from_app and payer_from_app as options for the fee_payer parameter for the /checkout/create and /preapproval/create calls.

2013-06-19

  • Added new /account call: /account/add_bank. This allows a user to directly add a bank to their account. Also lets a user change their bank account if one was previously set.
  • Added reason parameter to /account/delete call so that you can now specify a reason for why you are deleting an account.

2013-06-12

  • Added start_time and end_time parameters to /checkout/find call so that you can find all checkouts within a time range.
  • Added more magic numbers to help with testing: see testing page.

2013-03-13

  • Releasing a popup version of the OAuth2 flow that will allow you to register your users without them ever leaving your site.

2013-02-27

  • If a charge fails on an auto_recur preapproval we will now automatically retry the payment one day later before sending the failure email to the payer and putting the payment into state stopped. While the preapproval is waiting to be retried, it will be in the new retrying state.
  • Payers can now make payments with a bank account in the iframe payment flow.

2013-02-20

  • Added fallback_uri to /preapproval/create and /checkout/create. The uri that the payer will be redirected to if cookies cannot be set in the iframe; will only work if mode is iframe.
  • Added mode paramater for /withdrawal/create to allow withdrawing in iframe mode. This feature is currently in beta mode.

2013-02-13

  • Credit card payment descriptors will now be WPY-account_name instead of WePay-account_name to give more space to the account name to increase payment recognition. Please make sure your account names are something recognizable by the payer!
  • We are now exposing specific error_codes on all error responses. This feature is in beta. /developer/reference/errors
  • Adding disputed_amount response parameters to the /account/balance call that will let you track the amount of money an account has that is disputed (ex. in chargeback process).

2013-02-06

  • Adding the /credit_card/find call.
  • The shipping_address will now be persisted from the preapproval object to checkouts created with /checkout/create and a preapproval_id.
  • Onsite checkout and preapproval flow will now support themes.

2013-01-16

  • Adding a type response parameter to the /withdrawal call so you can tell whether the withdrawal is a check or ach withdrawal.
  • Adding pending_amount and reserved amount response parameters to the /account/balance call.

2012-12-05

  • Access tokens have prefixes depending on the environment. Existing access tokens will still work and should not be affected.

2012-11-21

  • Preapprovals will be put into state completed once their end_time has passed to indicate that they can no longer be used.

2012-11-07

  • Added refund_reference_id parameter to /checkout/refund call to provide idempotence guarantee for the call.

2012-10-31

  • Happy Halloween! - Customers who are registered on WePay, now have the ability to use saved payment methods inside the iframe. The Log In link in the iframe will now let customers log in via a popup rather than a full redirect.

2012-10-24

  • The /account call now returns a verification_uri that you can send the user to to verify their account. - Adding country, region, and postcode parameters to the standard prefill_object. - Adding app_fee parameter to checkout/refund.

2012-10-17

  • Adding an EVENT type parameter for checkout objects.

2012-10-10

  • If you do not pass a redirect_uri on the /checkout/create call, we will no longer redirect to your app’s homepage. Instead we will show a payment confirmation page in the iframe and send your app a postMessage indicating that the payment is complete (so you can close the iframe or take some action). This change is to help JS heavy apps that don’t want a full redirect on payment completion.
  • Moderators with edit access on an account can now use their access_token to create checkouts/preapprovals for that account.
  • New magic number $6.61 that can be used to test synchronous authorization failures.

2012-09-12

  • Added type response parameter to /account call. This will be business, personal, or nonprofit.

2012-08-29

  • Adding funding_sources request parameter to the /preapproval/create call.
  • Adding verification_state response parameter to the /account and /account/find calls.
  • Adding IPNs to users and accounts.
  • Adding ability to change callback_uri on users, accounts, checkouts, preapprovals, and withdrawals.
  • The amount parameter on the /preapproval/create call is now optional.

2012-08-21

  • By default apps that make more than 150 API calls over 5 seconds will now be throttled.
  • Analytics tab for the API dashboard. - New streamlined withdrawal flow (this change won’t affect API calls at all but includes a better user experience).

2012-08-08

  • Released the new Credit Card Tokenization API
  • The WePay API application fees have been changed

2012-08-01

  • Standardized the name of all events fired by Google Analytics. All event labels are now in JSON for easy parsing.

2012-07-25

  • Added user_name parameter to the /user call.

2012-07-18

  • IPN search now supported in the app management data tab.

2012-07-11

  • The correct API endpoint is now enforced on stage. https://stage.wepay.com/developer/reference/endpoints We are not enforcing the correct endpoint on production because we do not want to break production apps.
  • App management data tab search and CSV export functionality now supported.

2012-06-20

  • Released new app management dashboard.

2012-06-06

  • The /preapproval/create call now supports custom email messages.
  • All incoming HTTP requests now require a user-agent header.

2012-05-02

  • Publicly releasing our customization engine. See the tutorial for more info.
  • Publicly releasing the new Google Analytics support feature.
  • Fix the /account/balance pending_balance and available_balance response parameters to correctly be of type Number

2012-04-18

  • Added manage_uri parameter to the /preapproval call. You can send the user to this url to let them update their payment method for the preapproval.
  • Added a link to the preapproval manage_uri to payer checkout confirmation emails if the checkout was created from a preapproval.

2012-04-11

2012-04-04

  • Added payer_name and payer_email parameters to the /preapproval call.

2012-03-21

  • Renamed email_message parameter on /checkout/create call to payer_email_message (this call will still accept email_message for backwards compatibility).
  • Added payee_email_message parameter to /checkout/create so you can pass a custom message to the payment recipient as well.
  • The /checkout/create call now allows you to charge tax without a shipping address. Tax amount will be based off of billing address.
  • Added create_time and recipient_confirmed parameters to /withdrawal and /withdrawal/find responeses

2012-03-14

  • Updated buttons in the iframe checkout flow.

2012-03-07

  • Added ability to search by preapproval_id on the /checkout/find call.

2012-02-22

  • API preapprovals can now be auto-recurring (if you pass auto_recur:true then we will execute the payments automatically every period). This is meant for subscription use cases so you don’t need a cron job

2012-02-15

  • Added new API email template. This template is customizable with the API customization system
  • The withdrawal flow is now customizable as well

2012-02-08

  • Adding prefill_info parameter to the onsite checkout flow, and to the preapproval flows
  • Allow no-redirect on user completion of iframe checkout, if you pass a URL fragment in your redirect_uri. Make sure you handle this case correctly
  • Final deprecation of v1 API

2012-02-01

  • Prevent account admins from changing ownership of accounts created by an API app.

2012-01-11

  • Partial refunds support for /checkout/refund call
  • Allow /withdrawal/find to search for non-api initiated withdrawals

2011-12-28

  • Updated error message for invalid account_id

2011-12-21

  • Support for customization in Oauth2 and checkout flows

2011-11-24

  • Fixed & decoding in redirect_uri (/user/register call)
  • Allow /user/resend_confirmation call even if user access token is revoked

2011-11-16

  • Added ability to prefill user information in the checkout flow
  • Added /user/resend_confirmation call
  • Updated error message when making calls from an app that was not yet approved

2011-11-09

2011-11-02

  • Change /account/find to return all user accounts if the user is the app owner