April API direct integration migration guide
As part of our rebranding from Limepay to April Solutions, we also took the opportunity to expand and simplify our direct integration API. We've consolidated authentication, improved consistency and discoverability of features and expanded available functionality.
For merchants integrating using our ecommerce plugins, all you need to do is make sure you're on the latest release for your platform. Keeping up to date with your plugin comes with other benefits, like access to the latest features and bug fixes, so it's worth updating regularly.
For merchants and marketplaces upgrading from the Limepay API to the new April API, this guide will let you know what's changed and how to upgrade.
info
As a major version upgrade to our API, there are some breaking changes to the API integration that we deemed necessary to simplify the integration going forward. The existing Limepay API will continue to be available as is for the time being on:
| Environment | Domain name |
|---|---|
| Production | api.limepay.com.au |
| Sandbox | api.sandbox.limepay.com.au |
The changes described below only apply to the new April API now hosted on:
| Environment | Domain name |
|---|---|
| Production | api.au.meetapril.io |
| Sandbox | api.sandbox.au.meetapril.io |
Main changes
Simplified authentication
We support many ways to authenticate with our API. This includes merchant
public and secret keys, marketplace API keys, along with JWTs for people logged in via a browser.
Previously we used different HTTP request headers
to specify each of these different types of credentials. In April API we have changed this
so all authentication methods use the same Authorization: Bearer HTTP request header to provide credentials.
Terminology updates
We made some updates to our terminology and field names in the API to make their intention cleare and to improve consistency.
| Limepay API | April API | Notes |
|---|---|---|
| Platform | Marketplace | An abstraction for businesses that sell products and services through other businesses (B2B2C). Platform was deemed too generic a term. |
| emailAddress | Now consistently use emailAddress throught the API | |
| phoneno | phoneNumber | |
| internalOrderId | referenceOrderId | The identifier for the order in the merchant's systems. Internal was confusing as it wasn't obvious if it was internal to Limepay or the merchant. |
| internalCustomerId | referenceCustomerId | The identifier for the customer in the merchant's systems. |
| firstName/lastName | givenName/familyName | For identifying customers, given and family name are clearer terms as the ordering of these names can depend on the culture. |
Domain context now inferred wherever possible
In Limepay API, almost all calls required you to specify a customer or merchant identifier on the path.
In April API, we only require identifiers on the path if you are directly operating on that entity.
For instance when updating a merchant, the path used would be /merchants/<merchant-id>.
In most other cases, we can infer the identifiers either from the credentials provided or the resource
you are operating on. For instance an existing pay plan is always associated with a customer and a merchant,
so these now don't need to be provided explicitly.
In April API, the way integrators can provide this additional context is via the following HTTP headers:
Marketplace-Id, Merchant-Id or Customer-Id. Headers, if provided, take priority over any context inferred from the credentials,
however the call will only succeed if the client is authorised to act on behalf of the entity provided.
An example where you'd use one of these header is a marketplace creating an order on behalf of a sub-merchant.
In this case, there is no reference to the merchant in the order itself, and the marketplace credentials aren't
specific to any one merchant, so the Merchant-Id header must be provided.
POST https://api.sandbox.au.meetapril.io/orders
Authorization: Bearer sandbox_api_32i4jlisdf...
Content-Type: application/json; charset=utf-8
Accept: application/json
Merchant-Id: mcht_ZBTfqybt-gDzDe6KWhen querying resources, all filters, including identifiers, are provided as query parameters which may repeat. For instance the following call queries all pay plans for the given merchant identifiers:
GET https://api.sandbox.au.meetapril.io/payplans?merchantId=mcht_ZBTfqybt-gDzDe6K&merchantId=mcht_ZBTf6A3GhUZfytKf
Authorization: Bearer sandbox_api_32i4jlisdf...
Accept: application/jsonConsolidated endpoints
In Limepay API, we typically provided different endpoint paths for every feature exposed in the API, Additionally, if a feature was provided to multiple different types of clients, we would often have one endpoint per type of credential. In April API, all endpoints support every type of credential. As long as the caller is authorised to perform the action represented by the endpoint, they can call any endpoint in the April API. For Marketplace integrators, this means they don't have to flip between using their marketplace API key for some calls, and the merchant keys in other places - they can now use their marketplace API key for all server to server calls.
Additionally, we now use the convention of having all actions on an entity available via a PATCH call on the entity itself.
Each individual action uses a different discriminator field to differentiate it from other actions.
This makes it easy to see all available actions on an entity as they are all available in one place in the API docs.
The [Update Merchant]](/openapi/april-public/operation/UpdateMerchant/) is an example of this approach where
all the ways of updating a merchant are grouped together in one endpoint.
Public pay plan and card capture APIs 🆕
Under Limepay API, the only way for merchants to create pay plans was by having a customer create one via our Limepay checkout web component. This is still possible with April API, but integrators now have the additional option of establishing payments completely via the API including the capture of raw card details. See Payment Capture API for details.
API mapping
For all the API calls on the Limepay API, the following table shows the equivalent call under the April API and any changes you will need to take into account in the request and response payloads.