MercadoPago POS

Sarah integrates with MercadoPago Point and QR to process payments on physical terminals directly from the point of sale system.

Initial Configuration

1. Connect MercadoPago Account

1. Log in to Sarah
2. Go to Cash Registers > Settings
3. Select a cash register
4. Click Connect MercadoPago
5. Authorize connection with your MercadoPago account

2. Configure Terminals (Point)

1. In cash register settings, go to Terminals
2. Select Point terminals you want to use
3. Each terminal must be previously configured in MercadoPago

3. Configure QR

QR is automatically configured when you connect your account. No additional configuration required.

Integration Types

MercadoPago Point

Physical terminals that accept credit and debit cards.

Features:

• Accepts physical and contactless cards
• Real-time processing
• Immediate payment confirmation
• Supports installments

Flow:

1. Customer selects products in POS
2. Salesperson selects Point terminal
3. Order is created in MercadoPago
4. Terminal shows amount to pay
5. Customer inserts/taps card
6. Terminal processes payment
7. Sarah receives notification and updates sale

MercadoPago QR

Payments via QR code scanned with MercadoPago app.

Features:

• Customer scans QR with phone
• Confirms payment in app
• Real-time processing
• No physical terminal required

Flow:

1. Customer selects products in POS
2. Salesperson selects QR payment
3. QR order is created in MercadoPago
4. QR code is displayed on screen
5. Customer scans with MercadoPago app
6. Customer confirms payment
7. Sarah receives notification and updates sale

API Endpoints

Get Point Terminals List

GET /api/mp/pos?box_id=<box_id>

Headers:

x-user: <base64-encoded-user>

Response:

json
{
  "pos": [
    {
      "id": "POS_123",
      "name": "Terminal 1",
      "external_id": "ext_123"
    }
  ]
}

Create QR Order

POST /api/mp/qr-order

Headers:

http
x-user: <base64-encoded-user>
Content-Type: application/json

Body:

json
{
  "box_id": 5,
  "sale_id": 789,
  "amount": 15000.00,
  "external_pos_id": "POS_123"
}

Response:

json
{
  "success": true,
  "order_id": "ORD01KBGJBJR73YSRQEHJWMQJKF7R",
  "qr_data": "https://www.mercadopago.com.ar/checkout/v1/qr/...",
  "status": "pending",
  "status_detail": "pending_waiting_payment"
}

Webhooks

Event: order.processed

Triggered when a Point or QR order is processed (payment approved).

Webhook structure:

json
{
  "type": "order",
  "action": "order.processed",
  "data": {
    "id": "ORD01KBGJBJR73YSRQEHJWMQJKF7R",
    "external_reference": "789",
    "status": "processed"
  }
}

Processing:

1. Sarah receives webhook
2. Gets order details from MercadoPago
3. Verifies external_reference (sale ID)
4. If order is processed, marks sale as paid
5. Updates sale status in real time

Event: order.canceled

Triggered when an order is canceled.

Structure:

json
{
  "type": "order",
  "action": "order.canceled",
  "data": {
    "id": "ORD01KBGJBJR73YSRQEHJWMQJKF7R",
    "external_reference": "789",
    "status": "canceled"
  }
}

Processing:

1. Sarah receives webhook
2. Marks sale as cancelled or keeps as pending
3. Allows salesperson to process another payment method

Complete Flow: Point

1. Create Sale

javascript
// In POS, sale is created
const sale = {
  items: [...],
  total: 15000.00,
  payment_method: "mercadopago_point"
};

2. Select Terminal

javascript
// Get list of available terminals
const response = await fetch(`/api/mp/pos?box_id=${boxId}`);
const { pos } = await response.json();

// User selects terminal
const selectedTerminal = pos[0];

3. Process Payment

javascript
// Order is created in MercadoPago
// Terminal shows amount
// Customer inserts/taps card
// Terminal processes automatically

4. Confirmation

javascript
// MercadoPago sends webhook
// Sarah updates sale to "paid"
// POS shows confirmation

Complete Flow: QR

1. Create Sale

javascript
const sale = {
  items: [...],
  total: 15000.00,
  payment_method: "mercadopago_qr"
};

2. Generate QR

javascript
// Create QR order
const response = await fetch('/api/mp/qr-order', {
  method: 'POST',
  body: JSON.stringify({
    box_id: 5,
    sale_id: 789,
    amount: 15000.00,
    external_pos_id: "POS_123"
  })
});

const { qr_data } = await response.json();
// qr_data contains QR URL

3. Display QR

javascript
// QR is displayed on screen
// Customer scans with MercadoPago app
// Customer confirms payment in app

4. Confirmation

javascript
// MercadoPago sends webhook
// Sarah updates sale to "paid"
// POS shows confirmation

Order States

Order Cancellation

You can cancel an order before it's processed:

javascript
// Cancel QR order
const response = await fetch(`/api/mp/orders/${orderId}/cancel`, {
  method: 'POST'
});

Note: Once processed, order cannot be canceled from Sarah. You must do it from MercadoPago.

Security

Webhook Validation

Sarah validates MercadoPago webhooks:

1. Origin verification: Webhooks must come from MercadoPago
2. Data validation: Verifies order exists
3. Idempotency: Avoids processing same webhook multiple times

Access Token

• Token is stored securely in cash register configuration
• Used to authenticate requests to MercadoPago API
• Not exposed in frontend

Troubleshooting

Point Terminal doesn't appear

1. Verify connection: Ensure account is connected
2. Check in MercadoPago: Verify terminals are configured
3. Update list: Refresh terminal list

QR doesn't generate

1. Verify amount: Must be greater than 0
2. Verify cash register: Must be connected to MercadoPago
3. Review logs: Look for errors in order creation

Payment doesn't confirm

1. Verify webhook: Ensure it's configured correctly
2. Review external_reference: Must match sale ID
3. Verify status: Check order status in MercadoPago

Order canceled unexpectedly

1. Review logs: Look for cancellation reason
2. Check in MercadoPago: Review order status
3. Contact support: If problem persists

Best Practices

1. Configure webhooks: Essential to receive confirmations
2. Handle cancellations: Allow retry with another method
3. Show real-time status: Update UI when webhook arrives
4. Log events: Save logs of all orders
5. Validate amounts: Verify amount matches before processing
6. Use external_reference: Always include sale ID

Additional Resources

• MercadoPago Point Documentation
• Orders API
• MercadoPago Online - Integration for online payments

Support

If you need help:

1. Review webhook logs
2. Verify configuration in Sarah and MercadoPago
3. Contact Sarah support with error details