This version includes breaking changes from the previous version and may require a code change. See below for more details.
Major shift Toward Standard Objects Within Each Call
This API update includes the refactoring of key components of each call into universal objects. Several of our most popular endpoints - Invoice Payment Page, Line Item Payment Page, etc. have converted to this structure.
Fields that determine the customization of the resulting page's style and appearance have all been grouped into the pageOptions object.
Fields used to prepopulate billing address information have all been grouped into the billingAddress object.
The set of fields that governs how an API page should send a response to the integrator once action has been completed on it is all contained within the responseOptions object.
Fields used to manage who gets copies of email receipts generated from actions taken on the API page are all grouped under the emailOptions object.
Other objects have been created as well, but these are the most commonly used. For most applications, this refactor will be the primary breaking change for all looking to upgrade from v1.0
Updated Naming Conventions
While all of the v2.0 endpoints include "/v2/" in their path, we've also updated the other aspects of the paths for consistency moving forward.For example:
Invoice/Forms --> v2/paymentpage/invoice
PaymentPage/Forms --> v2/paymentpage/lineitem
Invoice/Connect --> v2/connect/paymentpage
Enhanced Payer Functionality in Existing Endpoints
Our most popular existing endpoints have gained a lot of flexibility around payer management within ClientPay. Now you can:
Enable Payer Saving | Save payers and payment methods for future use from an API-generated payment page.
payerOrPaymentMethodId | Pass in a payer or a payment method ID in order to surface saved payment methods on the resulting API-generated payment page.
Styling | Allows for custom styling of API-generated pages. First, work with ClientPay directly to establish desired styling choices. Then, ClientPay will assign your template a styling ID. Pass in that ID to the styling field within the pageOptions object to have the resulting page styled exactly to your specifications.
v2.0 introduces several brand new endpoints to accomodate almost any potential payment workflow:
Full Refund/Void | Pass in a paymentId and, if the original payment hasn't settled yet, ClientPay will void it out. If it has settled, ClientPay will issue a refund and respond with full refund details.
Create/Edit/Delete Payer | This No-UI endpoint allows you to pass in Payer information and get back a payerId. Use this payerId in subsequent calls to tie payments to payers and make that payer's payment methods available at time of payment.
Payer Page | This is the UI version of the above bullet point. So, instead of passing in payer information and getting back a payerId, call this endpoint to get a page where all the payer data can be entered. The payerId will be included in the postback once the data is submitted.
Payment Search | Supports complex queries. Pass in query parameters first to the Count endpoint to get back a count of results that match, then pass those same parameters in to the Results endpoint to get back the actual list of payment objects that match the search criteria.