WLB Assets Data API — Functional Documentation

Table of contents

• Overview
• Actors and context
• Operations
• Payment terminal field catalog
• Business rules and constraints
• Resilience and limits
• Traceability
• Error meanings

Overview

Using this API, a consumer can:

• List the payment terminals currently active for a merchant, with capture/communication method, brand, model and commercial mode.
• Know whether a terminal sold under the VENDA commercial mode is still under warranty.

Actors and context

The merchant identifier appears in the path of the business endpoint:

Text

{base_url}/merchant/{merchant_id}/payment-terminals

Text

1

{base_url}/merchant/{merchant_id}/payment-terminals

Authentication is enforced by the API gateway; requests without a valid token are rejected before reaching the service.

Operations

1. List the active payment terminals of a merchant

Returns the payment terminals currently active for the merchant. The response mirrors the SAP Equipment API record field by field (same names and values); only the documented fields are forwarded.

Bash

curl --location 'https://apigee-gtw-hti.getnet.com.br/wlb/assets-data/v1/merchant/51578987/payment-terminals' \ --header 'Authorization: Bearer <TOKEN>' \ --header 'X-Correlation-Id: 3f1a7c0e-2b6e-4d2a-9c1b-9b2f1e7a8d34'

Bash

1

2

3

curl --location 'https://apigee-gtw-hti.getnet.com.br/wlb/assets-data/v1/merchant/51578987/payment-terminals' \ --header 'Authorization: Bearer <TOKEN>' \ --header 'X-Correlation-Id: 3f1a7c0e-2b6e-4d2a-9c1b-9b2f1e7a8d34'

JSON

{ "merchant_id": "51578987", "equipments": [ { "payment_terminal_sku": "302890", "payment_terminal_serial_number": "903191104705597687", "capture_method_code": "10", "capture_method_des": "POS", "communication_method_code": "000000004", "communication_method_des": "WI FI", "activation_datetime": "2025-05-13 10:50:32", "payment_terminal_brand": "INGENICO", "payment_terminal_model": "MOVE 5000 ESSENTIAL", "commercial_mode": "ALUGUEL", "warranty_available": false } ] }

JSON

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

{ "merchant_id": "51578987", "equipments": [ { "payment_terminal_sku": "302890", "payment_terminal_serial_number": "903191104705597687", "capture_method_code": "10", "capture_method_des": "POS", "communication_method_code": "000000004", "communication_method_des": "WI FI", "activation_datetime": "2025-05-13 10:50:32", "payment_terminal_brand": "INGENICO", "payment_terminal_model": "MOVE 5000 ESSENTIAL", "commercial_mode": "ALUGUEL", "warranty_available": false } ] }

Response fields:

Notes:

• Merchant without active terminals → 200 with equipments: [].
• Unknown merchant → 404.
• The success body is returned as is (no success/data/meta envelope).

Payment terminal field catalog

Business rules and constraints

• Read-only. The API never changes data; every business operation is an idempotent GET.
• Active terminals only. Only the payment terminals currently active for the merchant are listed.
• Merchant validation. merchant_id must be alphanumeric with 1 to 20 characters; otherwise 400 is returned before any downstream call.
• Unknown merchant. The upstream signals an unknown merchant with an empty merchant_id (200) or with 404/422; the API always maps these to 404.
• Merchant without terminals returns 200 with an empty equipments list.
• Selective exposure. Only the documented fields are forwarded; any undocumented attribute added by the acquirer is never leaked to consumers.
• Neutral error messages. Downstream service names, hosts and response bodies are never relayed to the consumer; the full detail is kept only in the service logs, correlated by X-Correlation-Id.
• CORS is controlled by the CORS_ALLOWED_ORIGINS setting of each environment.
• Sensitive data must be transmitted over HTTPS, and all requests require authentication at the gateway.

Resilience and limits

Traceability

• X-Correlation-Id — optional request header. If the value is a safe identifier (letters, digits, ., _, :, -, up to 128 chars) it is reused; otherwise a UUID is generated. The final value is echoed in every response and propagated to the downstream.
• X-Request-Id is accepted as a fallback when X-Correlation-Id is absent.
• W3C traceparent is accepted and propagated; a new span is created for each request and returned in the response traceparent header.

Error meanings

Error responses share a common shape:

JSON

{ "code": "NOT_FOUND", "message": "Merchant not found" }

JSON

1

{ "code": "NOT_FOUND", "message": "Merchant not found" }

JSON

{ "code": "BAD_REQUEST", "message": "Request validation failed", "merchant_id": "must be an alphanumeric merchant code with up to 20 characters" }

JSON

1

2

3

4

5

{ "code": "BAD_REQUEST", "message": "Request validation failed", "merchant_id": "must be an alphanumeric merchant code with up to 20 characters" }

Messages returned to the consumer are always sanitized: internal identifiers, downstream names, hosts and response bodies are never relayed.