In-Person Payments with Mercado Pago Point Devices

The Mercado Pago Point Integration API lets you orchestrate in-person, card-present payments through physical Point card readers directly from your server-side application. Your backend communicates with the API to push payment intents to a registered device, check their progress, and manage the device fleet — while the Point hardware handles the customer-facing card interaction. This guide walks through every operation exposed by PointClient, from listing devices and switching operating modes to creating, querying, and cancelling payment intents.

Prerequisites

A Mercado Pago account with at least one registered Point device.
A valid access token set in MercadoPagoConfig (or passed per-request via MPRequestOptions).
Maven/Gradle dependency for the Mercado Pago Java SDK.

MercadoPagoConfig.setAccessToken("APP_USR-your-access-token");
PointClient client = new PointClient();

Devices

List devices

Use getDevices(MPSearchRequest) to retrieve all Point devices associated with the authenticated account. The result is paginated — use limit and offset to walk through large fleets, and filters to narrow results by POS or store.

import com.mercadopago.client.point.PointClient;
import com.mercadopago.net.MPSearchRequest;
import com.mercadopago.resources.point.PointDevices;
import com.mercadopago.resources.point.PointDevice;

PointClient client = new PointClient();

MPSearchRequest searchRequest = MPSearchRequest.builder()
    .limit(50)
    .offset(0)
    .build();

PointDevices devices = client.getDevices(searchRequest);

for (PointDevice device : devices.getDevices()) {
    System.out.println("Device ID:      " + device.getId());
    System.out.println("Operating mode: " + device.getOperatingMode());
}

// Pagination metadata
System.out.println("Total: " + devices.getPaging().getTotal());

To filter by store or POS, pass the corresponding key/value pairs in the filters map of MPSearchRequest.

MPSearchRequest searchRequest = MPSearchRequest.builder()
    .limit(10)
    .offset(0)
    .filters(Map.<String, Object>of("store_id", "123456"))
    .build();

Change device operating mode

A Point device can operate in two modes:

Mode	Description
`PDV`	Point-of-Sale mode — the device is linked to a POS system and receives payment intents from your integration.
`STANDALONE`	The device operates independently, accepting payments through its own interface without server coordination.

Switch modes with changeDeviceOperatingMode(deviceId, request):

import com.mercadopago.client.point.PointClient;
import com.mercadopago.client.point.PointDeviceOperatingModeRequest;
import com.mercadopago.client.point.OperatingMode;
import com.mercadopago.resources.point.PointDeviceOperatingMode;

PointClient client = new PointClient();

PointDeviceOperatingModeRequest modeRequest = PointDeviceOperatingModeRequest.builder()
    .operatingMode(OperatingMode.PDV)
    .build();

PointDeviceOperatingMode result = client.changeDeviceOperatingMode("PAX_A910__SMARTPOS123456", modeRequest);

System.out.println("New mode: " + result.getOperatingMode());

Payment intents can only be created while a device is in PDV mode. If the device is in STANDALONE mode, the API will return an error.

Payment Intents

A payment intent is a server-side instruction that tells a specific Point device to prompt the customer to present a card and collect the specified amount.

Create a payment intent

createPaymentIntent(deviceId, request) posts a new payment intent to a device. Build the request with PointPaymentIntentRequest.builder():

import com.mercadopago.client.point.PointClient;
import com.mercadopago.client.point.PointPaymentIntentRequest;
import com.mercadopago.client.point.PointPaymentIntentPaymentRequest;
import com.mercadopago.client.point.PointPaymentIntentAdditionalInfoRequest;
import com.mercadopago.resources.point.PointPaymentIntent;
import java.math.BigDecimal;

PointClient client = new PointClient();

PointPaymentIntentRequest request = PointPaymentIntentRequest.builder()
    .amount(new BigDecimal("150.00"))
    .description("Order #4321 — Coffee Shop")
    .payment(PointPaymentIntentPaymentRequest.builder()
        .type("credit_card")
        .installments(3)
        .installmentsCost("seller")
        .build())
    .additionalInfo(PointPaymentIntentAdditionalInfoRequest.builder()
        .externalReference("order-4321")
        .printOnTerminal(true)
        .ticketNumber("TKT-4321")
        .build())
    .build();

PointPaymentIntent intent = client.createPaymentIntent("PAX_A910__SMARTPOS123456", request);

System.out.println("Payment intent ID: " + intent.getId());
System.out.println("Device ID:         " + intent.getDeviceId());
System.out.println("Amount:            " + intent.getAmount());

Payment type reference

`type`	Description
`credit_card`	Credit card — supports `installments` (1–72) and `installmentsCost`
`debit_card`	Debit card — `installments` not applicable
`voucher_card`	Voucher/meal card — set `voucherType` to `sodexo` or `alelo`

`PointPaymentIntentRequest` fields

Field	Type	Description
`amount`	`BigDecimal`	Required. Positive amount to charge.
`description`	`String`	Short description shown on the device display.
`payment`	`PointPaymentIntentPaymentRequest`	Payment method configuration.
`additionalInfo`	`PointPaymentIntentAdditionalInfoRequest`	Optional metadata and printing preferences.

`PointPaymentIntentPaymentRequest` fields

Field	Type	Description
`type`	`String`	`credit_card`, `debit_card`, or `voucher_card`.
`installments`	`Integer`	Number of installments (1–72). Credit card only.
`installmentsCost`	`String`	`seller` or `buyer`. Credit card only.
`voucherType`	`String`	`sodexo` or `alelo`. Voucher card only.

`PointPaymentIntentAdditionalInfoRequest` fields

Field	Type	Description
`externalReference`	`String`	Your application’s identifier. Returned in the webhook notification.
`printOnTerminal`	`Boolean`	Whether to print the receipt on the Point device.
`ticketNumber`	`String`	Invoice or ticket number printed on the receipt.

Get payment intent status

Poll the last status event for a payment intent using getPaymentIntentStatus(paymentIntentId):

import com.mercadopago.client.point.PointClient;
import com.mercadopago.resources.point.PointStatusPaymentIntent;

PointClient client = new PointClient();

PointStatusPaymentIntent status = client.getPaymentIntentStatus("your-payment-intent-id");

System.out.println("Status:     " + status.getStatus());
System.out.println("Created on: " + status.getCreatedOn());

Common status values returned by the API include OPEN, FINISHED, CANCELED, and ERROR.

Search a payment intent by ID

Retrieve the full details of a specific payment intent — including its current lifecycle state — using searchPaymentIntent(paymentIntentId):

import com.mercadopago.client.point.PointClient;
import com.mercadopago.resources.point.PointSearchPaymentIntent;

PointClient client = new PointClient();

PointSearchPaymentIntent found = client.searchPaymentIntent("your-payment-intent-id");

System.out.println("ID:          " + found.getId());
System.out.println("State:       " + found.getState());
System.out.println("Amount:      " + found.getAmount());
System.out.println("Description: " + found.getDescription());
System.out.println("Device:      " + found.getDeviceId());

List payment intents by date range

getPaymentIntentList(request) returns all payment intent events whose final states fall within a given date window:

import com.mercadopago.client.point.PointClient;
import com.mercadopago.client.point.PointPaymentIntentListRequest;
import com.mercadopago.resources.point.PointPaymentIntentList;
import com.mercadopago.resources.point.PointPaymentIntentListEvent;
import java.time.LocalDate;

PointClient client = new PointClient();

PointPaymentIntentListRequest listRequest = PointPaymentIntentListRequest.builder()
    .startDate(LocalDate.of(2024, 1, 1))
    .endDate(LocalDate.of(2024, 1, 31))
    .build();

PointPaymentIntentList list = client.getPaymentIntentList(listRequest);

for (PointPaymentIntentListEvent event : list.getEvents()) {
    System.out.println("Intent ID:  " + event.getPaymentIntentId());
    System.out.println("Status:     " + event.getStatus());
    System.out.println("Created on: " + event.getCreatedOn());
}

Cancel a payment intent

To abort a pending payment intent before the customer interacts with the device, call cancelPaymentIntent(deviceId, paymentIntentId):

import com.mercadopago.client.point.PointClient;
import com.mercadopago.resources.point.PointCancelPaymentIntent;

PointClient client = new PointClient();

PointCancelPaymentIntent cancelled = client.cancelPaymentIntent(
    "PAX_A910__SMARTPOS123456",
    "your-payment-intent-id"
);

System.out.println("Cancelled intent ID: " + cancelled.getId());

Cancellation is only possible while the payment intent is still in the OPEN state. Once the customer has started interacting with the device, the cancellation request will be rejected.

Per-request options

Every PointClient method has an overload that accepts MPRequestOptions as a final argument. Use it to supply a different access token, adjust timeouts, or inject custom headers (such as an idempotency key) for a single call:

import com.mercadopago.core.MPRequestOptions;
import java.util.Map;

MPRequestOptions options = MPRequestOptions.builder()
    .accessToken("APP_USR-token-for-this-call")
    .connectionTimeout(10000)
    .socketTimeout(15000)
    .customHeaders(Map.of("x-idempotency-key", "unique-key-for-this-request"))
    .build();

PointPaymentIntent intent = client.createPaymentIntent(
    "PAX_A910__SMARTPOS123456",
    request,
    options
);

Webhooks and notifications

QR Code notifications are not signed by Mercado Pago. Do not attempt to validate WebhookSignatureValidator against QR events — they will always fail signature verification. Signature validation applies only to standard webhook notifications. See the Webhooks guide for full validation details.

When a payment intent reaches a terminal state, Mercado Pago sends a signed webhook to your configured notification URL. The externalReference field you provided in additionalInfo is included in the payload so you can correlate the notification to your own order or transaction.

Get Started

Guides

In-Person Payments with Mercado Pago Point Devices

Prerequisites

Devices

List devices

Change device operating mode

Payment Intents

Create a payment intent

Payment type reference

`PointPaymentIntentRequest` fields

`PointPaymentIntentPaymentRequest` fields

`PointPaymentIntentAdditionalInfoRequest` fields

Get payment intent status

Search a payment intent by ID

List payment intents by date range

Cancel a payment intent

Per-request options

Webhooks and notifications

Build docs developers (and LLMs) love

Get Started

Guides

Documentation Index

​Prerequisites

​Devices

​List devices

​Change device operating mode

​Payment Intents

​Create a payment intent

​Payment type reference

​PointPaymentIntentRequest fields

​PointPaymentIntentPaymentRequest fields

​PointPaymentIntentAdditionalInfoRequest fields

​Get payment intent status

​Search a payment intent by ID

​List payment intents by date range

​Cancel a payment intent

​Per-request options

​Webhooks and notifications

Build docs developers (and LLMs) love

Prerequisites

Devices

List devices

Change device operating mode

Payment Intents

Create a payment intent

Payment type reference

`PointPaymentIntentRequest` fields

`PointPaymentIntentPaymentRequest` fields

`PointPaymentIntentAdditionalInfoRequest` fields

Get payment intent status

Search a payment intent by ID

List payment intents by date range

Cancel a payment intent

Per-request options

Webhooks and notifications