Connect Pagar.me
Get paid in reais with card installments and PIX through your Pagar.me account, with subscriptions, order bumps and one-click upsells.
Pagar.me processes credit cards, debit cards and PIX (Brazil's instant payment) in reais, for accounts opened in Brazil. Connected to Vipter, it handles one-time sales, card installments, subscriptions, order bumps and one-click upsells.
Before you start
- An active Pagar.me account. To try things first, Pagar.me's test environment works.
- Access to the Pagar.me Dashboard to see the keys and create webhooks.
- The Admin or Owner role in the Vipter project.
- Room in your plan for one more active connection. The providers screen shows how many you already use.
Step 1: copy the secret key in Pagar.me
- Sign in to the Pagar.me Dashboard and check which environment you are in. Test keys are for trying things out, production keys are for selling.
- Open the Dashboard's access keys page and copy the chave secreta (secret key) for the environment you chose. The test secret key starts with
sk_test_.
Keep the key safe
The secret key gives access to the sales in your Pagar.me account. Paste it only into Vipter. If it leaks, create a new one in Pagar.me and replace it in Vipter with the Replace keys button.
Step 2: create the connection in Vipter
- In the Vipter dashboard, open PaymentsProvidersPagar.me.
- Click New connection. If the store has no Pagar.me account yet, the form is already open.
- Fill in the numbered fields:
| # | Field | What to paste |
|---|---|---|
| 1 | Account name | A name to recognize the account, such as "Pagar.me Store". It shows up in the payment flows. |
| 2 | Account country | Brazil, already selected. Pagar.me only serves accounts opened in Brazil. |
| 3 | API key (secret key) | The secret key you copied in step 1. |
| 4 | Test connection | When on, it uses Pagar.me test keys and test cards (sk_test_). Turn it off to charge for real with the production key. |
- Click Save and get the webhook URL. Vipter checks the key with Pagar.me before saving. If it is wrong, nothing is saved and the error shows on the form.
Test mode starts on
The Test connection switch starts on so a first connection never charges anyone by mistake. To sell, create the connection with it off and the production key.
If the store has no flow yet for credit card, debit card or PIX, Vipter creates those flows pointing to the new account. The store can charge right after step 4.
Step 3: register the webhook in Pagar.me
Through the webhook, Pagar.me tells Vipter what happens after the purchase: PIX paid, refunds, chargebacks and canceled or expired charges. Pagar.me proves the notice comes from it with a username and password (HTTP Basic authentication) that you choose yourself. Without that pair, the payments platform rejects Pagar.me's notices.
- After saving, the connection card shows the Webhook URL. Copy it.
- Still on the card, make up a username and a password and fill in both fields:
| # | Field | What to paste |
|---|---|---|
| 1 | Webhook username (Basic Auth) | Any username, such as vipter-webhook. You will repeat the same value in Pagar.me. It shows as optional, but without it the notices are rejected. |
| 2 | Webhook password (Basic Auth) | A long password, only for this webhook. Do not use your Pagar.me account password. |
- Click Save secret.
- In the Pagar.me Dashboard, open ConfiguraçõesWebhooks (Settings › Webhooks) and click Criar webhook (Create webhook).
- Paste the URL you copied in item 1.
- Select the order and charge events. Vipter uses these:
- order:
order.paid,order.payment_failedandorder.canceled; - charge:
charge.paid,charge.pending,charge.payment_failed,charge.refunded,charge.partial_canceled,charge.canceled,charge.chargedback,charge.expired,charge.underpaidandcharge.overpaid.
- order:
- Turn on webhook authentication and enter the same username and password as in item 2.
- Confirm with your Pagar.me account password and save.
One webhook per environment
A webhook created in Pagar.me's test environment only reports test sales. When you create the production connection, register another webhook in the production environment with that new connection's URL.
Step 4: test the connection
- On the connection card, click Test. Vipter calls Pagar.me with the saved key.
- Make a test purchase on an offer's checkout. With test mode on, use card
4000 0000 0000 0010with any future expiration date. In Pagar.me's test environment, this card is always approved.
It worked if
You see the message Connection OK., the card shows Verification secret configured. and the test purchase appears in SalesTransactions as paid.
Common problems
-
Your plan allows N active connector(s). Upgrade to add more.
Your plan reached its limit of active connections. Deactivate a connection you no longer use or change plans in Vipter plan.
-
Pagar.me rejected the key
The key is incomplete, belongs to another account, or is a test key with test mode off (or the other way around). Copy the secret key again, not the public one (
pk_), and check the Test connection switch. -
Without the verification secret the platform rejects this provider's events. Register the URL above at the provider, copy the secret and save it here.
The webhook username and password were not saved in Vipter. Go through items 2 and 3 of step 3 again.
-
The PIX was paid, but the order is still pending
Pagar.me's notice did not arrive or was rejected. Check that the webhook exists in the same environment as the connection (test or production), that the URL is the one on this connection's card, and that the username and password in Pagar.me match the ones saved in Vipter. If you change the values, save them again on both sides.
What to do next
- Set how many installments the store offers and with what interest in installments.
- Review the payment flows to decide which account charges each payment and which one is the fallback.