DOCSEARCHbyAlgolia
Submit Docs

Mercado Pago NodeJS SDK

repository·master·Indexed 19 days ago

https://github.com/mercadopago/sdk-nodejs

The Mercado Pago NodeJS SDK (version 3.3.0) provides bindings to integrate Mercado Pago APIs for processing payments and managing orders. It includes tools for configuring the SDK via MercadoPagoConfig, managing online orders, and utilizing the AdvancedPayment client for marketplace split-payments, including operations to create, retrieve, search, update, cancel, and capture advanced payments. It also provides functionality for card tokenization via the cardToken client.

Tokens
40.4K
Snippets
172
Records
188
Agent score
66%

What's inside mercadopago-sdk-nodejs

  1. How to make an API request with the SDK

    master

    The SDK follows a pattern of initializing a configuration client, passing that client to a specific API object, and then calling a method on that object with a request body.

    1. Initialize Config: Create a MercadoPagoConfig instance with your accessToken.
    2. Initialize API Object: Instantiate the desired API class (e.g., Order) by passing the client instance.
    3. Define Body: Construct the request payload object (e.g., for an Order).
    4. Execute: Call the API method (e.g., .create()) passing an object containing the body and optional requestOptions.
    import { MercadoPagoConfig, Order } from "mercadopago";

// 1. Initialize client
const client = new MercadoPagoConfig({
	accessToken: "<ACCESS_TOKEN>",
});

// 2. Initialize API object
const order = new Order(client);

// 3. Create request body
const body = {
	type: "online",
	total_amount: "1000.00",
	// ... other fields
};

// 4. Make the request
order.create({ body }).then(console.log).catch(console.error);

  2. Security guidelines for public issues

    master

    ⚠️ NEVER share the following in public GitHub issues:

    • Access tokens or production credentials
    • Client IDs / Client Secrets
    • Customer or card data
    • Personally Identifiable Information (PII)

    Note: Issues containing real sensitive data will be closed and reported immediately.

  5. Determine where to seek support

    master

    Decide whether to use GitHub Issues or Official Mercado Pago Support based on your problem type:

    Use GitHub Issues for SDK Technical Support:

    • SDK bugs
    • Questions about SDK usage
    • SDK feature requests
    • Code contributions

    Use Official Mercado Pago Support for Account or Transactional issues:

    • Account problems or access issues
    • Specific transactions or payments
    • Commercial or billing topics
    • Homologation/certification
    • Webhook configuration within your account
    • Reports and statistics

  6. Follow language and commenting guidelines

    master

    All contributions must adhere to the following standards:

    Language

    • English only: All source code, comments, documentation, commit messages, and review comments must be in English.

    Comments

    Focus on the why rather than the how.

    When to comment:

    • Decisions that depart from common wisdom or convention.
    • Complex logic that required significant thought (e.g., more than 1 hour of reasoning for a small code fragment).
    • Implementation properties that must be preserved (e.g., performance-sensitive code, security primitives, or synchronization logic).

    When NOT to comment:

    • Program structures that follow standard conventions.
    • Pedantic explanations of behavior that are obvious from the code itself.
    • Behavior you cannot personally attest to.

  7. Use standard branching and Git commit patterns

    master

    Branch Naming

    Use the following patterns for short-term branches:

    • hotfix/something-needs-fix: Small routine patches.
    • feature/something-new: New features or changes to existing ones (watch for breaking changes).
    • doc/improves-documentation-for-this-feature: Documentation changes with no source code impact.

    Git Commit Messages

    Commit messages should follow the seven rules of a great Git commit message:

    1. Separate subject from body with a blank line.
    2. Limit the subject line to 72 characters.
    3. Capitalize the subject line.
    4. Do not end the subject line with a period.
    5. Use the imperative mood in the subject line.
    6. Wrap the body at 72 characters.
    7. Use the body to explain what and why vs how.

    Avoid vague messages like fix tests or now it's working. Always rebase your code to avoid reverse merge commits.

  10. Set up pre-commit for code style and formatting

    master

    To ensure code style and formatting consistency, the SDK uses pre-commit. You must have pre-commit installed on your machine and configured within the project folder to enable git hooks that run automatically before every commit.

    1. Verify pre-commit is installed:
      pre-commit --version
    2. Install the project's git hook scripts:
      pre-commit install

    Note: These rules are enforced automatically during Pull Requests. If checks fail, your contribution will be rejected until fixed.

    $ pre-commit --version
$ pre-commit install

  11. Manage orders with the Order client

    master

    The Order class is a facade for the MercadoPago Orders v1 endpoints. It allows you to manage the entire order lifecycle, including creation, retrieval, processing, capturing, canceling, and refunding. Additionally, it provides methods to manage individual transactions within an order (create, update, or delete).

    Each method in the Order class maps to a specific REST endpoint and returns a Promise. You can pass requestOptions to any method to override global configuration settings like timeouts or idempotency keys for that specific call.

    import { Order } from 'mercadopago';

const orderClient = new Order(mercadoPagoConfig);

// Example: Create an order
const order = await orderClient.create({
  body: { /* order data */ }
});

  12. Manage subscription plans with PreApprovalPlan

    master

    The PreApprovalPlan class is used to manage subscription plan templates. A PreApprovalPlan acts as a reusable template that defines billing terms (such as frequency, amount, free trial, and allowed payment methods) for recurring subscriptions. Individual PreApproval subscriptions can then reference these plans to inherit their configuration.

    This client provides CRUD (Create, Retrieve, Update, Delete) and search operations against the /preapproval_plan endpoint.