Skip to main content

Quick Start Guide

Use this guide to quickly install Terminal API, configure your terminal, and process your first payment transaction. For detailed instructions, refer to Getting Started, Integration, and API Reference sections.

Note: Terminal API uses a cloud-to-cloud integration model. Requests are sent from your backend application to Worldline services, which route them to the payment terminal.

For S1U2 terminals, tap the software MENU button after a restart until the terminal ID (TID) and password are displayed. You will need these details when configuring Terminal API.

1
Become a Partner
  • Complete the Worldline onboarding process. Refer to Become a Partner section.
  • Register your merchant account.
  • Obtain your UMID, UTID, and API credentials.
2
Gather Your Credentials

Before you begin, ensure you have:

  • UMID (Unique Merchant ID)
  • UTID (Unique Terminal ID)
  • API Bearer Token
  • A registered payment terminal
  • Internet connectivity
3
Install Terminal API

If Terminal API is already installed, skip this step.

1. Open the terminal launcher.

2. Open the App Drawer.

3. Launch SmartPOS Store.

4. Open the All tab.

5. Select and install Terminal API.

4
Configure Terminal API
  1. Open the Terminal API application.
  2. Enter UMID and UTID
  3. Select INTEGRATION for testing, and PRODUCTION for live transactions
  4. Activate Terminal API.
  5. Verify the cloud icon turns green.

5
Initialize the Terminal
  1. Click on the Setup menu.

2. Enter the terminal password.

3. Navigate to Configuration>Initialisation.

6
Send Your First Payment

Send a synchronous payment request:

POST /api/v1/merchants/{MERCHANT_ID}/terminals/{TERMINAL_ID}/payments/sync

Required headers:

Content-Type: application/json
Authorization: Bearer <TOKEN>

Minimal request:

To process a payment, you'll send a POST request to:

/api/v1/merchants/{MERCHANT_ID}/terminals/{TERMINAL_ID}/payments/sync
7
Verify the Result

A successful transaction returns a response from the terminal.

Review the transaction outcome:

Success

The payment was processed successfully.

Failure

Review:

  • ResponseReason
  • AdditionalResponseInformation

Example failure reasons:

  • Refusal
  • WrongPIN
  • UserCancel
  • DeviceOut
8
Configure Asynchronous Processing

After successfully processing a synchronous transaction, configure asynchronous processing for production use.

  1. Create a publicly accessible HTTPS endpoint.
  2. Configure a valid WebhookUrl.
  3. Configure NumberOfRetries (0-3).
  4. Ensure the endpoint accepts HTTP POST requests.
  5. Ensure the endpoint returns a 20x response.
  6. Test webhook delivery.

Quick references​