Mercado Pago Fast Payments

​

Availability

• Yuno SDK 2.0 payment methods list (getPaymentMethodsViews), with the checkout session created with workflow: 'SDK_SEAMLESS'
• Web SDK v1.11 Full checkout (mountCheckout)
• Web SDK v1.11 Lite checkout (mountCheckoutLite) with paymentMethodType: 'MERCADO_PAGO_SUPERTOKEN', supporting both element and modal render modes (Mercado Pago recommends element).

​

Compatibility and platform support

​

Functional limitations

• Recurrence and merchant-initiated transactions (MIT): Fast Payments requires interactive shopper authentication. It cannot be used for recurring subscription billing, tokenized card vaulting for future off-session charges, or MIT flows.
• Coupons and Mercado Pago promotions: In-app Mercado Pago discounts or merchant coupon codes managed inside Mercado Pago cannot be applied through Fast Payments.
• Partial capture or differing amounts: Authorizing an amount and capturing a different or partial amount later is not supported. The captured amount must equal the authorized checkout amount.
• Sub-acquirer fields: Custom sub-acquirer parameters or intermediary processing flags are not passed to Mercado Pago.
• Split payments: 1:1 split payments are not supported. 1:N split payment scenarios are currently under validation and not available for general release.

​

Onboarding and prerequisites

1. Enable Fast Payments (Mercado Pago and merchant, in Mercado Pago Developers). Request Fast Payments activation on your Mercado Pago application through your Mercado Pago account manager.
2. Authorize the connection (merchant, in the Yuno Dashboard). In Settings > Connections, run Connect with Mercado Pago to generate the seller access tokens.
3. Configure public keys (merchant, in the Yuno Dashboard). Add the public key of each Mercado Pago site you sell in, tagged with its country. Add a key tagged GLOBAL as a fallback.
4. Configure the webhook (merchant, in Mercado Pago Developers). Set the Notification URL to https://prod.y.uno/mercadopago-webhook/v1/orders/events and subscribe to the Order (Mercado Pago) event.
5. Enable routing rules (Yuno and merchant, in the Yuno Dashboard). Enable the MERCADO_PAGO_SUPERTOKEN payment method in your checkout routing workflow.

​

How it works for the shopper

​

Full checkout

​

Lite checkout

​

Integration

​

Workflow mapping

​

Integration examples

<script src="https://sdk-web.y.uno/v2.1.2/main.js"></script>

const sdkPayments = await SdkPayments.initialize('YOUR_PUBLIC_API_KEY');

// Checkout session created by your backend with workflow: 'SDK_SEAMLESS'
const transaction = sdkPayments.transaction({
  checkoutSession: 'CHECKOUT_SESSION_ID',
  countryCode: 'AR',
  elementSelector: '#payment-form',
  onStatus: (result) => {
    console.log('Final status:', result.status);
  },
});

let selectedPaymentMethod = null;

const views = transaction.getPaymentMethodsViews({
  types: ['paymentMethodList'],
  onPaymentSelected: (paymentMethod) => {
    selectedPaymentMethod = paymentMethod;
  },
});

await views.paymentMethodList?.mount({ elementSelector: '#payment-list' });

// When the shopper confirms, from your Pay button
payButton.addEventListener('click', async () => {
  if (selectedPaymentMethod) {
    await transaction.start({ paymentMethod: selectedPaymentMethod });
  }
});

// Web SDK v1.11.21+
const yuno = await Yuno.initialize('YOUR_PUBLIC_API_KEY');

await yuno.startCheckout({
  checkoutSession: 'CHECKOUT_SESSION_ID',
  elementSelector: '#root',
  countryCode: 'AR',
  // Mercado Pago recommends element render mode
  renderMode: {
    type: 'element', // or 'modal'
    elementSelector: {
      apmForm: '#apm-form',
      actionForm: '#action-form',
    },
  },
  // ...your callbacks
});

await yuno.mountCheckoutLite({
  paymentMethodType: 'MERCADO_PAGO_SUPERTOKEN',
});

await yuno.startPayment();

​

Lite checkout with several payment methods

• One mounted method at a time. mountCheckoutLite renders the chosen method’s form into renderMode.elementSelector.apmForm (element mode) or into a modal. Calling it again with another paymentMethodType replaces the previous form, so typed data and validation state never carry over from one method to the next.
• Your Pay button. With showPayButton: false the card and other-method forms render no button of their own. onChange tells you when the mounted form is complete, and yuno.submitOneTimeTokenForm() submits it.
• Mercado Pago confirms inside its own component. The Fast Payments component keeps its Continue and Pay buttons, and showPayButton and submitOneTimeTokenForm() do not apply to it. In element mode, hide your Pay button while Mercado Pago is selected.
• A method with nothing to ask pays on mount. When a method renders no form, the SDK creates the one-time token and calls createPayment as soon as the method mounts. Mount those methods when the shopper presses Pay, not when they select the method.

<fieldset id="payment-methods">
  <label><input type="radio" name="payment-method" value="MERCADO_PAGO_SUPERTOKEN" /> Mercado Pago</label>
  <label><input type="radio" name="payment-method" value="CARD" /> Card</label>
  <label><input type="radio" name="payment-method" value="PIX" /> Pix</label>
</fieldset>

<div id="yuno-root"></div>
<div id="payment-form"></div>   <!-- the selected method's form renders here -->
<div id="action-form"></div>    <!-- 3DS and other actions render here -->
<button id="pay-button" type="button" disabled>Pay</button>

// Web SDK v1.11.21+
const yuno = await Yuno.initialize('YOUR_PUBLIC_API_KEY');

const payButton = document.querySelector('#pay-button');
let selectedType = null;
let formIsValid = false;

await yuno.startCheckout({
  checkoutSession: 'CHECKOUT_SESSION_ID',
  elementSelector: '#yuno-root',
  countryCode: 'BR',
  renderMode: {
    type: 'element',
    elementSelector: {
      apmForm: '#payment-form',
      actionForm: '#action-form',
    },
  },
  // Card and other-method forms render no Pay button; yours submits them
  showPayButton: false,
  onChange: ({ form }) => {
    formIsValid = form.isValid;
    refreshPayButton();
  },
  async createPayment(oneTimeToken, tokenWithInformation) {
    // Create the payment from your backend with the one-time token
    await createPaymentOnYourServer({ oneTimeToken, checkoutSession: 'CHECKOUT_SESSION_ID' });
    await yuno.continuePayment();
  },
  paymentResult(status) {
    console.log('Payment result:', status);
  },
  error(message, data) {
    console.error('Error:', message, data);
  },
});

// Methods that render a form: mount on selection, submit from your Pay button.
// A method that asks nothing (Pix on this connection) creates the token as soon
// as it mounts, so it is mounted from the Pay button instead.
const MOUNT_ON_SELECTION = ['MERCADO_PAGO_SUPERTOKEN', 'CARD'];

async function selectMethod(type) {
  selectedType = type;
  formIsValid = false;
  if (MOUNT_ON_SELECTION.includes(type)) {
    // Mounting another type replaces the previous form and its validation state
    await yuno.mountCheckoutLite({ paymentMethodType: type });
    await yuno.startPayment();
  } else {
    // Remove the previous method's form; Pix mounts when the shopper presses Pay
    await yuno.unmountSdk();
  }
  refreshPayButton();
}

function refreshPayButton() {
  // Mercado Pago confirms inside its own component
  payButton.hidden = selectedType === 'MERCADO_PAGO_SUPERTOKEN';
  // Disable only while a mounted form is incomplete
  payButton.disabled = MOUNT_ON_SELECTION.includes(selectedType) && !formIsValid;
}

document.querySelectorAll('input[name="payment-method"]').forEach((radio) => {
  radio.addEventListener('change', () => selectMethod(radio.value));
});

payButton.addEventListener('click', async () => {
  if (MOUNT_ON_SELECTION.includes(selectedType)) {
    await yuno.submitOneTimeTokenForm();
    return;
  }
  await yuno.mountCheckoutLite({ paymentMethodType: selectedType });
  await yuno.startPayment();
});

// Web SDK v1.11.21+
const yuno = await Yuno.initialize('YOUR_PUBLIC_API_KEY');

let selectedType = null;

await yuno.startCheckout({
  checkoutSession: 'CHECKOUT_SESSION_ID',
  elementSelector: '#yuno-root',
  countryCode: 'BR',
  // renderMode defaults to { type: 'modal' }
  async createPayment(oneTimeToken, tokenWithInformation) {
    await createPaymentOnYourServer({ oneTimeToken, checkoutSession: 'CHECKOUT_SESSION_ID' });
    await yuno.continuePayment();
  },
  paymentResult(status) {
    console.log('Payment result:', status);
  },
  error(message, data) {
    console.error('Error:', message, data);
  },
});

document.querySelectorAll('input[name="payment-method"]').forEach((radio) => {
  radio.addEventListener('change', () => {
    selectedType = radio.value;
  });
});

document.querySelector('#pay-button').addEventListener('click', async () => {
  await yuno.mountCheckoutLite({ paymentMethodType: selectedType });
  await yuno.startPayment();
});

​

One-time token and payment creation

{
  "payment_method": {
    "type": "MERCADO_PAGO_SUPERTOKEN",
    "wallet": {
      "third_party_token": "<token issued by Mercado Pago for this payment>",
      "provider_method_id": "master",
      "provider_method_type": "credit_card"
    },
    "installment": { "value": 1, "id": null }
  }
}

• third_party_token is the token Mercado Pago issues for the method the shopper chose. Yuno uses it to charge the payment; you never see card data.
• provider_method_id and provider_method_type identify the method inside the shopper’s Mercado Pago account (a card brand such as master, or account_money for the account balance).
• installment is sent for cards, with the number of installments the shopper picked from Mercado Pago’s options. It is omitted for account_money.

​

Idempotency, retries, and diagnostics

• Idempotency and server timeouts: Always include an X-Idempotency-Key header when creating payments via POST /v1/payments. If a network timeout occurs during this request, your server should first retry the request using the exact same X-Idempotency-Key or reconcile the payment status via GET /v1/payments/{payment_id}.
• Recovering checkout state (continuePayment): Call yuno.continuePayment() on the client side only after the payment is created, when the payment response indicates an action is needed (such as sdk_action_required) or when a card returns DECLINED or ERROR and the shopper should select another method or retry. Do not use continuePayment() as a replacement for server-side timeout retries or status reconciliation.
• Support diagnostics: When escalating payment or integration issues to Yuno or Mercado Pago support, always capture and provide these identifiers:
  • checkout_session: The unique session identifier created via POST /v1/checkout/sessions.
  • payment_id: The transaction identifier returned by Yuno in the payment response.
  • trace_id / request_id: The HTTP response tracking header (X-Trace-Id) from API requests.

​

Countries

​

Testing and production release

​

Testing checklist

1. Test user creation: Create test buyer and seller accounts in the Mercado Pago Developers portal for the target country site.
2. Payment methods setup: Ensure the test buyer user has saved payment methods in their Mercado Pago account (credit card and account balance).
3. Session e-mail: In POST /v1/checkout/sessions, pass the test buyer’s registered email in customer_payer.email.
4. Authentication flow: Verify that saved cards load in the checkout section. Test security code prompts and simulated challenge steps.
5. Routing rules: Ensure routing rules direct MERCADO_PAGO_SUPERTOKEN transactions to the Mercado Pago test connection.

​

Production release checklist

1. Production OAuth authorization: In the Yuno Dashboard, click Connect with Mercado Pago under your production account to generate active seller tokens.
2. Production public keys: Ensure production public keys are assigned for each active country site.
3. Webhook verification: Verify that the production Notification URL is configured and receiving events in Mercado Pago Developers.
4. Checkout validation: Verify the experience for non-eligible shoppers and shoppers without saved payment methods, as described in How it works for the shopper.