5-minute quickstart

This path proves three things quickly: your backend can send sk_test_... safely, the QA host is reachable, and the webhook can close the payment loop.

1. Create the first authenticated charge on the backend

Choose your language, install the SDK, and set MUPAG_API_KEY to your sk_test_... key in the server environment. The example creates a PIX charge for R$12.90.

Installationnpm install mupag-sdk@0.2.0

import { MuPag } from 'mupag-sdk';

const mupag = new MuPag({
  apiKey: process.env.MUPAG_API_KEY,
  env: 'test',
});

const charge = await mupag.charges.create({
  amount_cents: 1290,
  payment_method: 'pix',
  customer: {
    name: 'Ana Silva',
    email: 'ana@example.com',
    tax_id: '12345678909',
  },
}, { idempotencyKey: 'order_123_charge_1' });

console.log(charge.charge_id);

2. Keep the secret key on your server

MethodPOST

Path/v1/charges

Credentialsserver only

Request body

{
  "amount_cents": 1290,
  "payment_method": "pix",
  "customer": {
    "name": "Ana Silva",
    "email": "ana@example.com",
    "tax_id": "12345678909"
  }
}

Configure backend authenticationOpen full quickstart

Secret keys stay on the backend

The portal does not execute financial mutations or ask for your key. Copy an example and make the authenticated call from your server.

3. Reuse the key for the same payment

Replace order_123_charge_1 with an immutable ID for your payment operation. Persist it before calling the SDK. Retries of the same operation must use the same key and payload; a new payment needs a new key.

The SDK handles authentication, serialization and internal retries. Save charge_id from the response to track the charge. See SDKs and tools and Idempotency.

4. Close the loop

• Point your receiver to the events described in Webhooks.
• Confirm in the QA dashboard that the charge and customer arrived with the same IDs stored in your system.
• Keep charge_id, request_id and your idempotency key in application logs.