Checkout Developer Portal

The Littlepay Checkout APIs and SDKs provide a simple and secure way to accept online payments from your front of office web and native mobile applications. Easily build secure web and mobile ticketing applications leveraging Littlepay’s network of transit acquirers.

Guides    API Reference

Shared Documentation

Documentation that is shared between Littlepay Checkout sdks

Documentation that is shared between Littlepay Checkout sdks

  1. Errors - information about errors returned by Littlepay SDKs/API.
  2. Test Cards - credit/debit numbers used for testing paying by card in Littlepay SDKs.
  3. Test Cases - cases for testing the Littlepay Checkout system.

Errors

This page contains information about errors returned by Littlepay SDK. These errors are categorised to make it easier for apps using the SDK to handle them.

SDK error handling

  • All errors (including network and API errors) are sent back as error result containing an error type according to the list below.
  • All unexpected errors are treated as CLIENT_INTERNAL_ERROR.

Merchant responsibility

An app using the SDK is completely free in how to handle errors. According to the error type the SDK returns, it might display a message or initialise a retry of the payment. It is the responsibility of the merchant's app to provide a meaningful user experience.

Error types

These errors are communicated to a caller of Littlepay SDK via an error result containing the error type.

Error TypeError Condition
CLIENT_SECURITY_ERRORLittlepay SDK client detect security warnings and decline the transaction. This is a permanent condition, i.e. retrying the same request will result in the same error.
CLIENT_INTERNAL_ERRORLittlepay SDK client internal failure, e.g. misconfiguration, etc. This is a permanent condition, i.e. retrying the same request will result in the same error.
CLIENT_CONNECTION_ERRORLittlepay SDK client failed to connect to Littlepay Web API, e.g. due to network conditions, Littlepay Web API is unavailable, etc. This is a transient condition, i.e. client can retry.
CLIENT_AUTHORIZATION_ERRORLittlepay SDK client failed to authenticate to Littlepay Web API. This is a permanent condition.
CLIENT_RATE_LIMIT_ERRORClient has exceeded number of allowed requests. This is a transient condition, client can re-submit a request after waiting for an appropriate backoff period.
CLIENT_REQUEST_ERRORLittlepay Web API responded to Littlepay SDK client with HTTP response code indicating a client error. This is a permanent condition.
SERVER_TRANSIENT_ERRORLittlepay Web API responded to Littlepay SDK client with HTTP response code indicating a server error. This is a transient condition, i.e. client can retry.
SERVER_PERMANENT_ERRORAn error that occurred while Littlepay server side tried to process this request. This is a permanent condition.
PAYMENT_TRANSIENT_ERRORA request from Littlepay server to an external party failed. This is a transient condition, i.e. app can advise the end user to retry later.
PAYMENT_PERMANENT_ERRORA request from Littlepay server to an external party failed. This is a permanent condition, i.e. retrying the same request will result in the same error. The app can advise the end user to:
- contact her/his financial institution (to check if the card has been reported lost or stolen, if there are sufficient funds in the account, etc).
- choose an alternative payment method.
CLIENT_OUTDATED_SDK_ERRORSDK version is no longer supported. This is a permanent condition, client has to update SDK.

Test Cards

These are credit/debit card numbers that should be used for testing paying by card using the Littlepay SDKs.

When testing payment card fields:

  • cardholder name - Use any name
  • card number - Use one of the test card numbers below
  • cvv - use any 3 digit number
  • expiry - Use any future month year combination (MM/yy)

What is 3DS (Three D Secure)?

3DS (or Three D Secure) is a globally adopted authentication solution designed to make online transactions more secure. There are two major 3DS versions in use - here we refer to them as 3DS1 and 3DS2. The supported versions are determined by the card issuer (e.g. a bank).

3DS2 Challenge Card

4000000000001091

Using this card number will elicit a 3DS2 challenge experience. A successful response to the challenge will result in a successful payment.

3DS2 Frictionless Card

4000000000001000

Using this card number will result in a successful payment experience. Here 'frictionless' means 'no challenge'.

3DS1 Challenge Card

4000000000000002

Using this card number will elicit a 3DS1 challenge experience. A successful response to the challenge will result in a successful payment.

Failed Payment Card

4000000000001018

Using this card number will cause a failed payment.


Test Cases

This page contains information on test cases for testing the Littlepay Checkout system.

#TypeDescriptionRequired inputsExpected outputs
1Events WebhookRegister a URL to receive event notifications for events:
  • charge.capture.succeeded
  • charge.capture.failed
URL Registered with Littlepay Webhook200 Response; successful registration of a URL
2Payment Intent10 Payment Intents to capture a customer payment, each resulting in Success10 Payment Intents as per descriptionSuccessfully receive 10 event notifications of charge.capture.succeeded
3Payment Intent10 Payment Intents to capture a customer payment, each resulting in Failure10 Payment Intents as per descriptionSuccessfully receive 10 event notifications of charge.capture.failed
4Payment Intent10 Payment Intents to capture a customer payment, where:-2 payments made via 3DS2 Challenge Card-3 payments made via 3DS2 Frictionless Card-3 payments made via 3DS1 Challenge Card10 Payment Intents as per descriptionSuccessfully receive 10 event notifications, one for each scenario listed in description
5Error HandlingEvidence that web checkout has implemented error handling in place for transient and permanent errors. Plan should cover scenarios when: - checkout would re-try or not the request; or- checkout would present an advice to an end user in case of failures.Input / Output not applicable. Required is a set of transaction flows or documentation demonstrating that error handling would be implemented, for which failure scenarios, with clear articulation of what advice is sent to end user in each failure scenario.n/a
6Fetch EventsFetch all events from Test Cases [2,3,4] after the creation of payment intents1 Fetch command covering the tests listed in descriptionPage of results that matches the query criteria, ordered by descending event time

Updated 6 months ago

Shared Documentation


Documentation that is shared between Littlepay Checkout sdks

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.