AI resources

Test the integration

Before going live, we recommend testing the integration and transaction processing. This allows you to verify that the integration was configured correctly and that transactions are processed without errors.

If you wish, before testing your integration you can encrypt your data to perform your test transactions. To learn how to create this encryption, go to Security encryption. Remember that this encryption is only required when going live with your integration, that is, for your real transactions.

To test your integration with Payouts, create transactions by sending a request with your test Access TokenPrivate key linked to an application, used in the backend to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments and must never be exposed in the frontend. and the X-test-token: true header to the endpoint /v1/payoutsPOST, so that the request is made in a test environment.

To test the creation and processing of a payout via Pix, send one or more transactions to destination accounts in the test environment.

The Pix key used in the test must be registered for the destination account, and its format must match the type provided in transactions.pix.type.

curl
curl --location 'https://api.mercadopago.com/v1/payouts' \
--header 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'X-enforce-signature: false' \
--header 'X-test-token: true' \
--header 'Content-Type: application/json' \
--data '{
  "external_reference": "MP0197",
  "config": {
    "notification_url": "https://link-your-webhook-notification.com"
  },
  "description": "Payout for seller commissions",
  "transactions": [
    {
      "description": "Payment to seller Beltrano",
      "type": "pix",
      "pix": {
        "type": "CPF",
        "chave": "111.444.777-35"
      },
      "amount": {
        "currency": "BRL",
        "value": 10
      },
      "external_reference": "MP0197"
    }
  ]
}'

To learn in detail all the parameters sent and returned in this request, consult our API ReferenceAPI. If you receive an error when sending the request, check our error list for more information.

If the execution is successful, the request returns a status code 202, indicating that the payout was accepted for processing. The following example shows a payout containing two transactions:

json
{
  "id": "POP01KV681P6SJ38NQHWX3XK162SS",
  "external_reference": "payout_external_reference",
  "description": "description_root",
  "idempotency_key": "021957ca-7271-4f5e-8b8d-70ed87ce1a61",
  "created_date": "2026-06-15T14:17:36-03:00",
  "status": "created",
  "config": {
    "notification_url": "https://notification_url.com"
  },
  "transactions": [
    {
      "id": "TOP01KV681P6SJ38NQHWX3SF2WM22",
      "amount": {
        "currency": "BRL",
        "value": 11
      },
      "external_reference": "transaction_external_reference_01"
    },
    {
      "id": "TOP01KV681P6SJ38NQHWX3T9PHH3M",
      "amount": {
        "currency": "BRL",
        "value": 12
      },
      "external_reference": "transaction_external_reference_02"
    }
  ]
}

Transaction processing may take a few minutes. If a transaction has status=pending, send a request to the endpoint /v1/payouts/{payout_id}/transactions/{transaction_id}GET to check for updates.

Ready! Once this step is completed, the integration is complete and you can go to production.

PreviousConfigure notificationsSet up Mercado Pago notifications to keep transfers updated in your system.

NextGo to productionLearn the recommendations for going live with your integration with Payouts effectively and securely.