Skip to main content

App Integration

The warrify APIs allow deep integration into existing merchant web and mobile applications.

info

As of now we DO NOT provide any SDKs for our APIs. If you are interested please reach out to us at support@warrify.com.

caution

Most of our APIs are NOT intended to be called from a client application. You should always call them from your backend server unless otherwise noted.

Matching Sales to Customers​

In order to display the right sales to the customer that actually made them there needs to be some way of matching the customer to the sale. This depends on whether the customer was "known" at the time of the purchase. A "known" customer is usually someone that shows their loyalty card at the point of sale or has an account in your webshop.

Known Customers​

If a customer showed their loyalty card or was logged into their account in your webshop you should send the customer's ID in the $.attributes.customer.customerId field when creating a sale.

tip

If the number on the loyalty card is NOT the same as the customer's ID in your system you can send the number on the loyalty card in the $.attributes.customer.loyaltyCardNumber field. If the internal customer ID is also available at the point of sale you can send it in the $.attributes.customer.customerId field.

Some examples:

{
  "attributes": {
    "customer": {
      "customerId": "0357a485-d052-4020-a379-1ccb0c1daddb",
      "loyaltyCardNumber": "987654321"
    }
  }
}

Anyway we recommend to always set the $.attributes.customer.customerId field to the internal customer ID in your system. The sales for a customer can subsequently be retrieved by calling the List Sales endpoint with the filter[customer.customerId]=... query parameter. This call then returns a paginated list of sales for the customer sorted from newest to oldest. The raw data in this list can then be used to render a native list of a customers receipts. If a customer clicks on a list item they should then be shown a detailed view of said receipt (see Displaying Receipts).

Unknown Customers​

Matching sales to unknown customers is a little less straightforward. If all customers in your app need to create an account you can look at other ways to handover receipts to them (see Handover). If however also anonymous customers can use your app, you can use a so called "external ID". "External IDs" are IDs that are generated by your systems and are globally unique. E.g.

  1. a random UUID generated by the Point of Sale
  2. the cart ID used for mobile Self Checkout/Scan & Pay (see Scan & Pay)
  3. the (random) order id of the webshop
  4. ...

They can be sent to our API in the $.attributes.externalId field when creating a sale.

tip

To offer anonymous users a similar experience to logged in customers you can store a list of sale IDs locally on the device. This list can then be used to display their purchase history and display the receipt when clicked. Ideally you also inform the customer that losing their device would also mean losing their purchase history and use this as an incentive to create an account.

A common way to hand over receipts to anonymous customers is to have them show a code at checkout. This code could be a "temporary" loyalty card, for which your app generates a new ID every time it is shown or it could be the code used for mobile Self Checkout/Scan & Pay that hands over the cart ID to the Point of Sale (see Scan & Pay). Once the external ID is handed over to the Point of Sale and sent to our API in the $.attributes.externalId field the frontend is able to display the receipt and needs to be notified to do so. For this there are two options:

  1. Recommended: Your app server subscribes to the com.warrify.checkout.sale.created.v1 webhook and notifies the mobile app (e.g. via a Push Nutofication, WebSockets, Server-sent Events) to show the receipt.

  2. The mobile app frequently polls the List Sales endpoint ith the filter[externalId]=... query parameter to check if the sale is already present and then shows the receipt (see Displaying Receipts).

caution

In this scenario it is ideal to proxy these requests through your backend server to avoid exposing your API credentials to the public. If you cannot do that you MUST create a separate set of API credentials for your mobile app. These credentials should only be allowed the checkout:sales:search action on the urn:warrify-com:{tenant_id}:{region}:checkout:dimensions:externalId/equals resource

Scan & Pay​

Digital receipts are a great addition to the digital customer journey offered by mobile Self Checkout/Scan & Pay. To deliver interactive receipts to everyone using mobile Self Checkout/Scan & Pay you need to send a unique ID for the purchase (e.g. the cart ID) to our API in the $.attributes.externalId field when creating a sale. This ID can then be used to retrieve the receipt via the List Sales endpoint with the filter[externalId]=... query parameter and displayed in your app. To display the receipt once the sale is complete there are two options:

  1. Recommended: Your app server subscribes to the com.warrify.checkout.sale.created.v1 webhook and notifies the mobile app (e.g. via a Push Nutofication, WebSockets, Server-sent Events) to show the receipt.

  2. The mobile app frequently polls the List Sales endpoint ith the filter[externalId]=... query parameter to check if the sale is already present and then shows the receipt (see Displaying Receipts).

caution

In this scenario it is ideal to proxy these requests through your backend server to avoid exposing your API credentials to the public. If you cannot do that you MUST create a separate set of API credentials for your mobile app. These credentials should only be allowed the checkout:sales:search action on the urn:warrify-com:{tenant_id}:{region}:checkout:dimensions:externalId/equals resource

Displaying Receipts​

In general there are two ways to display receipts in your app:

  1. Recommended: Show a Web-View that shows the warrify provided interactive receipt. This ensures a consitent experience across all channels and allows us to provide new features without you having to update your app.

  2. Show a custom (native) receipt that you generate from the sale data. This makes you responsible for keeping the receipt up to date with new features and changes to the receipt layout and requires you to have a deep understanding of the receipt data model.

Push Notifications​

A great way to use sales data to drive engagement in a mobile merchant application is to send push notifications to customers when they make a purchase that their interactive receipt is now available. We do not send these notifications ourselves but rather provide webhooks for you to subscribe to. When a sale is made, we will send an HTTP request to your webhook containing the com.warrify.checkout.sale.created.v1 event;

The event data contains the complete sale object and allows you to generate

  1. a deep link to the receipt in your app
  2. an engaging push message to the customer containing information from the sale.

when the push notification is opened, the customer should be taken to the receipt in your app (see Displaying Receipts).