MercadoPago

Sarah integrates with MercadoPago to process online payments in your store. This integration allows your customers to pay with credit card, debit card, bank transfer, and other payment methods available in MercadoPago.

Initial Configuration

1. Create Application in MercadoPago

1. Log in to your MercadoPago Developers account
2. Go to Your integrations > Create new application
3. Complete your application data
4. Copy your Access Token (public and private according to environment)

2. Configure in Sarah

1. Log in to Sarah
2. Go to Settings > Integrations > MercadoPago
3. Enter your MercadoPago Access Token
4. Select environment (Test or Production)
5. Save configuration

3. Configure Webhook

To receive payment notifications, configure webhook in MercadoPago:

1. In MercadoPago panel, go to Webhooks
2. Add URL: https://sarah.ar/api/mp/webhook
3. Select events to receive:
   • payment
   • order (if using QR)

Payment Flow

1. Create Payment Preference

When a customer starts checkout, Sarah creates a payment preference in MercadoPago:

javascript
// Example of created preference
{
  "items": [
    {
      "title": "Product 1",
      "quantity": 2,
      "unit_price": 1500.00
    }
  ],
  "back_urls": {
    "success": "https://your-store.com/checkout/success",
    "failure": "https://your-store.com/checkout/failure",
    "pending": "https://your-store.com/checkout/pending"
  },
  "external_reference": "sale_123",
  "metadata": {
    "sales_id": 123,
    "box_id": 5
  }
}

2. Redirect to Checkout

Customer is redirected to MercadoPago to complete payment.

3. Webhook Notification

MercadoPago sends a notification to Sarah when payment changes status:

Webhook URL:

POST /api/mp/webhook

Webhook structure:

json
{
  "type": "payment",
  "data": {
    "id": "1234567890"
  }
}

4. Payment Processing

Sarah processes the webhook and updates sale status:

• Approved: Sale is marked as paid
• Rejected: Sale remains as pending or is canceled
• Pending: Sale remains as pending (e.g., cash payments)

Payment States

Webhooks

Event: payment

Triggered when a payment changes status.

Structure:

json
{
  "type": "payment",
  "data": {
    "id": "1234567890"
  }
}

Processing:

1. Sarah gets payment details from MercadoPago API
2. Verifies external_reference (sale ID)
3. Updates sale status according to payment status
4. If approved, marks sale as paid

Event: order

Triggered when a QR or Point order changes status.

Structure:

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

Processing:

1. Sarah gets order details
2. Verifies external_reference (sale ID)
3. If order is processed, marks sale as paid

Supported Payment Methods

MercadoPago supports multiple payment methods:

• 💳 Credit/debit card
• 🏦 Bank transfer
• 💵 Cash (Rapipago, Pago Fácil)
• 📱 MercadoPago account money
• 🔄 Interest-free installments (if enabled)

Security

Webhook Validation

Sarah validates MercadoPago webhooks:

1. Origin verification: Webhooks must come from MercadoPago servers
2. Data validation: Verifies payment exists and belongs to company
3. Idempotency: Avoids processing same webhook multiple times

Access Token

• Never share your Access Token publicly
• Rotate token periodically if you suspect compromise
• Use different tokens for test and production

Use Cases

1. Online Sale with Checkout Pro

1. Customer adds products to cart
2. Starts checkout
3. Sarah creates payment preference
4. Customer is redirected to MercadoPago
5. Customer completes payment
6. MercadoPago sends webhook
7. Sarah updates sale to paid

2. Payment with QR

1. QR code is generated in POS
2. Customer scans with MercadoPago
3. Customer confirms payment
4. MercadoPago sends order webhook
5. Sarah updates sale to paid

3. Rejected Payment

1. Customer attempts payment
2. Payment is rejected (insufficient funds, etc.)
3. MercadoPago sends webhook with rejected status
4. Sarah keeps sale as pending
5. Customer can retry payment

Troubleshooting

Webhook doesn't arrive

1. Verify URL: Ensure https://sarah.ar/api/mp/webhook is accessible
2. Review logs: Check in MercadoPago if there are errors sending
3. Test manually: Use MercadoPago webhook testing tool

Payment approved but sale doesn't update

1. Verify external_reference: Must match sale ID
2. Review logs: Look for errors in webhook processing
3. Verify Access Token: Must have permissions to query payments

Duplicate payment

1. Idempotency: Sarah avoids processing same webhook multiple times
2. Verify in MercadoPago: Check if there are really two payments or it's the same

Error: "Invalid payment"

1. Verify payment ID: Must exist in MercadoPago
2. Verify Access Token: Must have access to payment
3. Verify environment: Token must correspond to correct environment

Best Practices

1. Configure webhooks in production: Essential to receive notifications
2. Handle all states: Not only approved, also pending and rejected
3. Implement retries: If webhook fails, MercadoPago will retry
4. Log events: Save logs of all received webhooks
5. Validate amounts: Verify payment amount matches sale
6. Use external_reference: Always include sale ID to correlate

Additional Resources

• Official MercadoPago Documentation
• Payments API
• MercadoPago Webhooks
• MercadoPago POS - Integration with physical terminals

Support

If you need help:

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