# Architecture Source: https://developer.paymee.com.br/api-reference/architecture Overview of the PayMee API integration model, endpoints, and HTTP methods used. Integration with PayMee is performed through **Web Services**. The model employed is quite simple, utilizing two main base URLs (endpoints): * **Production Endpoint:** For live, real-time operations. [https://api.paymee.com.br/](https://api.paymee.com.br/) * **Sandbox Endpoint:** For testing and development. [https://apisandbox.paymee.com.br/](https://apisandbox.paymee.com.br/) These endpoints receive `HTTP` messages using standard methods (`POST`, `GET`, `PUT`). Each message type must be sent to a specific **resource**, identified by its path (URI) appended to the base endpoint URL. ## HTTP Methods The primary `HTTP` methods used by the PayMee API are detailed below: | Method | Description | Example Usage | | :----- | :----------------------------------------------------------------------- | :------------------------------------ | | `POST` | Used to **create** new resources or send information to be processed. | Creating a new transaction. | | `PUT` | Used to **update** an already existing resource. | Refunding or canceling a transaction. | | `GET` | Used for **querying** (retrieving information about) existing resources. | Querying transaction details. | # Cancel a transaction Source: https://developer.paymee.com.br/api-reference/cancel-a-transaction put /v1.1/transactions/{saleUUID}/void Allows the merchant to cancel a **PENDING** sale. Any other situation will return an error. # Cancel authorization Source: https://developer.paymee.com.br/api-reference/cancel-authorization put /v1.1/pix-automatic/authorizations/{idRec}/cancel Cancels a recurring payment authorization. # Cancel scheduled payment Source: https://developer.paymee.com.br/api-reference/cancel-scheduled-payment put /v1.1/pix-automatic/scheduled-payments/{instructionId}/cancel Cancels a scheduled payment that has not yet been processed. # Create a loan Source: https://developer.paymee.com.br/api-reference/checkouts/create post /v1.1/loans/create Creates a loan based on a previously approved proposal # Redirect checkout Source: https://developer.paymee.com.br/api-reference/checkouts/redirect-checkout post /v1.1/checkout Creates a redirect checkout. Bank transfer and cash deposit payment methods are unavailable and return HTTP 400 with the message 'Transferência bancária e depósito identificado foram descontinuados e não estão mais disponíveis.'. Omitting paymentMethod keeps the hosted checkout available with supported methods. # Semi-transparent PIX, boleto, BolePix, credit card and Open Banking checkout Source: https://developer.paymee.com.br/api-reference/checkouts/semi-transparent-wire-transfer-pix-and-credit-card-and-openbanking-checkout post /v1.1/checkout/transparent Creates a semi-transparent checkout. BOLETO and BOLETO_PIX require merchant enablement, a configured boleto fee, a complete merchant address, and the shopper document and address. Shopper address is required only for these two methods. Split payments and recurrence are not supported for boleto. PIX charges can be split between your account and linked recipients with the optional `split` array; see [Split payments](/api-reference/split-payments). Bank transfers and cash deposits are unavailable. Requests using these methods return HTTP 400 with code `bank_transfer.discontinued`. ## Split payments PIX charges can be split between your account and linked recipients with the optional `split` array. Each leg sets a `recipientId` and either an `amount` or a `percentage`. PayMee fees and refunds stay with your account. The response adds a root `split` block. See [Split payments](/api-reference/split-payments) for rules, settlement and error codes. ## Boleto and BolePix Use `BOLETO` for a bank boleto or `BOLETO_PIX` for a boleto with a Pix QR code. BolePix offers two ways to pay the same sale; the customer must pay only once. These methods require merchant enablement, a configured boleto fee, and a complete merchant address. Check [available payment methods](/api-reference/get-available-payment-methods) before offering them. Split payments and recurrence are not supported for either method. ### Shopper address `shopper.address` is required **only for `BOLETO` and `BOLETO_PIX`**. PIX, credit card and Open Banking (`INITIATOR`) do not require it. | Field | Requirement for boleto and BolePix | | -------------- | ---------------------------------------------- | | `street` | Required, nonblank | | `number` | Required, nonblank | | `neighborhood` | Required, nonblank | | `city` | Required, nonblank | | `state` | Required, two-letter Brazilian state code | | `zipCode` | Required, eight digits; formatting is accepted | | `complement` | Optional | Provide a valid shopper CPF or CNPJ. Shopper bank details are not required for boleto or BolePix. Request examples use illustrative data: replace the document and due date before submitting. ### Due date and expiration `dueDate` uses `yyyy-MM-dd`, interpreted in `America/Sao_Paulo`. The default configuration uses today plus 3 days when omitted and accepts dates from today through today plus 20 days. PayMee can configure these limits. For these two methods, sale expiration is calculated from `dueDate` plus the configured grace period (default: 2 days), instead of the request's `maxAge`. The BolePix QR code expires at the end of `dueDate`. Use the bank's returned `paymentLimitDate`, when present, for the boleto payment limit. ### Payment instructions and confirmation Creation returns boleto fields directly in `response.instructions`: `documentNumber`, `typeableLine`, `barcode`, `dueDate`, `paymentLimitDate`, `amountDue`, `status` and `pdfUrl`. BolePix also returns `response.instructions.pix.qrCode` with the Pix payload and QR code. Use the returned PDF URL as provided. Successful registration is not payment confirmation. Use the existing [payment webhook](/api-reference/webhook#boleto-and-bolepix) or [transaction query](/api-reference/query-a-transaction) to confirm payment. Transaction queries expose boleto details in the root `boleto` field; its lifecycle status is separate from the sale's `situation`. ### Boleto errors Errors use the existing validation envelope: `status: -1`, `message: "validation failure"`, `errorCount` and `errors` containing `field`, `code` and `message`. | HTTP | Code | Meaning | | ---- | --------------------------------- | ------------------------------------------------------- | | 400 | `boleto.disabled` | Boleto is not enabled for this merchant/configuration | | 400 | `merchant.address.incomplete` | Merchant address must be completed | | 400 | `shopper.address.isNull` | Shopper address is missing | | 400 | `shopper.address..isNull` | Required address field is missing or blank | | 400 | `shopper.address.state.invalid` | State must have two characters | | 400 | `shopper.address.zipCode.invalid` | Postal code must contain eight digits | | 400 | `boleto.register_failed` | The bank could not register the boleto | | 409 | `boleto.duplicate_in_flight` | Issuance is already in progress for this reference code | | 503 | `boleto.unavailable` | Boleto issuance is temporarily unavailable | | 503 | `boleto_pix.pix_unavailable` | The BolePix QR code could not be generated | # Simulation Source: https://developer.paymee.com.br/api-reference/checkouts/simulation post /v1.1/loans/simulation Create a loan simulation based on customer information and requested amount # Create Pix Automatic Recurrence Source: https://developer.paymee.com.br/api-reference/create-pix-automatic-checkout post /v1.1/checkout/pix-automatic Creates a Pix Automatic recurrence journey. Use the `immediatePayment` flag inside the `recurrence` object to control the flow: `false` for Journey 2 (authorization only), or `true` for Journey 3 (authorization with an immediate payment). # Create a recurrence plan Source: https://developer.paymee.com.br/api-reference/create-plan post /v1.1/pix-automatic/plans Creates a new recurrence plan for Pix Automatic. # Get authorization by recurrence ID Source: https://developer.paymee.com.br/api-reference/get-authorization-by-id get /v1.1/pix-automatic/authorizations/{idRec} Retrieves a specific recurring payment authorization by its recurrence ID (idRec). # Get available payment methods Source: https://developer.paymee.com.br/api-reference/get-available-payment-methods get /v1.1/available_payment_methods Returns payment methods available to the authenticated merchant. BOLETO and BOLETO_PIX appear only when boleto is enabled for that merchant and its boleto fee is configured. Bank transfer and cash deposit methods are unavailable and omitted. # Get payer information Source: https://developer.paymee.com.br/api-reference/get-payer-information get /v1.1/transactions/{sale_uuid}/payment_info Returns PIX payer details for a **PAID** sale identified by `sale_uuid`. # Get pix data from a sale Source: https://developer.paymee.com.br/api-reference/get-pix-data-from-a-sale get /v1.1/transactions/pix/{transactionUUID} To query a transaction, do a GET as shown below. # Get plan by ID Source: https://developer.paymee.com.br/api-reference/get-plan-by-id get /v1.1/pix-automatic/plans/{planId} Retrieves a specific plan by its ID. # Get scheduled payment by instruction ID Source: https://developer.paymee.com.br/api-reference/get-scheduled-payment-by-id get /v1.1/pix-automatic/scheduled-payments/{instructionId} Retrieves a specific scheduled payment by its instruction ID. # Overview Source: https://developer.paymee.com.br/api-reference/introduction Introduction to integrating with the PayMee API, covering purpose, requirements, and environments. ## Purpose The purpose of this documentation is to guide the developer on how to integrate with PayMee. It describes the features and methods to be used, lists the information to be sent and received, and provides examples. ## Required Knowledge The integration mechanism with PayMee is straightforward. Intermediate knowledge in the following areas is required to successfully deploy the PayMee solution: * Web programming languages * `HTTP`/`HTTPS` requests * `JSON` file manipulation ## API Operations In this manual, you will find references to all operations available via the PayMee `API REST`. These operations require authentication using specific keys (`x-api-key` and `x-api-token`) sent in the request headers. ### Environments Requests should be directed to the appropriate environment endpoint: * **Production Environment:** For live transactions. [https://api.paymee.com.br/](https://api.paymee.com.br/) * **Sandbox Environment:** For testing and development. [https://apisandbox.paymee.com.br/](https://apisandbox.paymee.com.br/) ### Making Requests To perform an operation: 1. Combine the base URL of the chosen environment (Production or Sandbox) with the resource (`URI`) of the desired operation. 2. Send the request using the `HTTP` verb specified for that operation (e.g., `GET`, `POST`). 3. Include your `x-api-key` and `x-api-token` in the request headers for authentication. # List authorizations Source: https://developer.paymee.com.br/api-reference/list-authorizations get /v1.1/pix-automatic/authorizations Lists recurring payment authorizations based on provided filters. # List recurrence plans Source: https://developer.paymee.com.br/api-reference/list-plans get /v1.1/pix-automatic/plans Lists Pix Automatic plans based on provided filters. # List scheduled payments Source: https://developer.paymee.com.br/api-reference/list-scheduled-payments get /v1.1/pix-automatic/scheduled-payments Lists scheduled payments (payment instructions) based on filters. # Authorize payout Source: https://developer.paymee.com.br/api-reference/payouts/authorize-payout post /v1.1/payout/authorize/{tid}/{authorizationCode} Authorize Payout # Batch payout request Source: https://developer.paymee.com.br/api-reference/payouts/batch-payout-request post /v1.1/payout/create/batch Payouts at PayMee are cash-out transactions; Before we start, there are some important tips: 1. you must have sufficient funds; 2. you shoud provide a valid and complete beneficiary details 3. Register your server CIDR for production enviroment # Cancel a payout Source: https://developer.paymee.com.br/api-reference/payouts/cancel-a-payout delete /v1.1/payout Before we start, there are some important notes: 1. the transactions should have **PENDING** status and not marked as **IN PROCESSING** # Individual payout request Source: https://developer.paymee.com.br/api-reference/payouts/individual-payout-request post /v1.1/payout/create Payouts at PayMee are cash-out transactions; Before we start, there are some important tips: 1. you must have sufficient funds; 2. you shoud provide a valid and complete beneficiary details 3. Register your server CIDR for production enviroment # Variable Amount (Dynamic Pricing) Source: https://developer.paymee.com.br/api-reference/pix-automatic-variable-amount Recurring charges that follow the current plan amount — update the plan, next charges follow Pix Automático subscriptions come in two pricing modes, defined at checkout by `recurrence.amount.valueType`: | Mode | What the payer authorizes | Can the charge amount change? | | ----------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `FIXED` (default) | An exact amount (e.g. R\$ 15,00/month) | No. Banco Central locks the mandate to the authorized amount — a mismatching charge is rejected by the payer's bank (`AM09`). | | `VARIABLE` | A **minimum** amount (`debitorMinimumAmount`) | Yes. Each cycle is charged with the plan's current `recurrenceAmount`. | ## Creating a variable-amount subscription Send `valueType: "VARIABLE"` and the authorized minimum in the checkout: ```json theme={null} POST /v1.1/checkout/pix-automatic { "currency": "BRL", "referenceCode": "order-123", "shopper": { ... }, "recurrence": { "planId": "6a45a170c8ad05000722084d", "immediatePayment": false, "retry": true, "amount": { "valueType": "VARIABLE", "debitorMinimumAmount": 10.00 }, "calendar": { "initialDate": "2026-08-01T00:00:00.000-03:00", "periodicity": "MONTHLY" } } } ``` The payer sees and authorizes "variable amount, minimum R\$ 10,00" in their bank app. In the merchant panel, tick **"Valor variável (segue o plano)"** in the New Recurrence modal to create the subscription in this mode. The recurrence amount field becomes the authorized minimum. ## How each charge is priced For every cycle of a `VARIABLE` subscription the engine resolves the amount in this order: 1. A one-off amount set for the next cycle via [`PUT /authorizations/{idRec}/cycle-amount`](/api-reference/cancel-authorization), if any (cleared after use); 2. The plan's **current** `recurrenceAmount`; 3. The authorized minimum (`debitorMinimumAmount`), as fallback. The resolved amount is never below the authorized minimum. If it exceeds the maximum the payer configured at their bank, the charge is rejected with `AM02` and reported through the `RECURRENCE_CHARGE_FAILED` webhook. ## Updating the plan amount Update the plan; the **next** charges of every variable subscription linked to it follow the new value automatically: ```json theme={null} PUT /v1.1/pix-automatic/plans/{planId} { "recurrenceAmount": 22.50 } ``` In the merchant panel, use the pencil icon on the Plans tab. `FIXED` subscriptions are never affected by plan edits — the payer authorized an exact amount. To change the price of a fixed subscription, cancel it and create a new one (new payer authorization via QR code). ## Already-scheduled charges A charge already registered at the payer's bank (status `SCHEDULED`) keeps its amount. Plan edits apply from the next cycle the engine schedules (charges are registered 2–10 days before their due date, per Banco Central rules). # Query a transaction Source: https://developer.paymee.com.br/api-reference/query-a-transaction get /v1.1/transactions/{transactionUUID} Returns detailed information about a sale, payout or refund transaction. Split sales include a `split` block: the parent sale lists its recipient legs, and a recipient-side transaction describes the leg it received. # Query webhook requests Source: https://developer.paymee.com.br/api-reference/query-a-webhook-requests get /v1.1/transactions/{transactionUUID}/webhook Returns every webhook attempt associated with the specified transaction. Optional query parameters let you filter by endpoint, event type, status, or HTTP response code. # Query current balance Source: https://developer.paymee.com.br/api-reference/query-current-balance get /v1.1/balance Returns the merchant’s current balance, the timestamp when the balance was calculated (GMT‑3), and a status/message pair indicating success or failure. # Query transactions using filters Source: https://developer.paymee.com.br/api-reference/query-transactions-using-filters get /v1.1/transactions Use the query parameters to filter the list of transactions returned. # Request a sale refund Source: https://developer.paymee.com.br/api-reference/request-a-sale-refund put /v1.1/transactions/{saleUUID}/refund Creates a refund request for a **PAID** sale. The body must include the amount to refund and may include a reason and a callback URL. # Request a webhook redeliver Source: https://developer.paymee.com.br/api-reference/request-a-webhook-redeliver get /v1.1/transactions/{transactionUUID}/webhook/redeliver Triggers a new delivery attempt for the webhooks of a **SALE** transaction whose payment status is **PAID**. # Sandbox and Tools Source: https://developer.paymee.com.br/api-reference/sandbox-tools Information about the PayMee Sandbox environment for testing integrations and obtaining credentials. ## About Sandbox To facilitate testing during integration, PayMee offers a **Sandbox environment**. This environment allows you to test your integration thoroughly without affecting live data. It comprises two main areas: 1. **Test Account Registration:** Where you can sign up for test credentials. 2. **Transactional Endpoint:** The specific URL for sending API requests in the test environment. All Sandbox API requests should be sent to the following endpoint: [https://apisandbox.paymee.com.br](https://apisandbox.paymee.com.br) ## Advantages of Using the Sandbox * **No Affiliation Required:** You don't need to be a formally approved merchant to start testing in the Sandbox. * **Easy Credential Generation:** Simply access the Sandbox Registration page, create an account, and you will receive the `x-api-key` and `x-api-token` needed for authenticating your test API calls. ## Create Your Sandbox Account Ready to start testing? Create your Sandbox account via the link below to get your test API keys: Click here to access the Sandbox registration page and create your test account. ## Simulating Pix Automatic The Sandbox includes a simulator that drives the full Pix Automatic recurrence lifecycle (authorize, charge, settle, fail and cancel) without a real payer. Drive mandates, collections, run-due charges, scenarios and reason codes end to end. # Solution Features Source: https://developer.paymee.com.br/api-reference/solution-features Key attributes and benefits of the PayMee API platform technology. The PayMee API solution was developed using `REST` technology. As a market standard, `REST` is independent of the technology used by the integrating party, allowing integration through the vast majority of programming languages, such as: * `ASP` * `ASP.NET` * `Java` * `PHP` * `Ruby` * `Python`, etc. Key features that stand out in the PayMee platform include: * **No Proprietary Apps:** It is not necessary under any circumstances to install proprietary applications in the virtual shop environment. * **Simplicity:** The communication protocol used is purely `HTTPS`. * **Ease of Testing:** The PayMee platform offers a publicly accessible **Sandbox environment**. This allows developers to create test accounts, making the integration start easier and faster. * **Credentials Handling:** The customer’s credentials (`x-api-key` and `x-api-token`) are securely transmitted in the header of the `HTTP` request. * **Safety:** Information exchange always occurs directly between the store's `Server` and PayMee's `Server`, meaning it does not pass through the buyer’s browser. * **Multiplatform:** Integration is performed through the `REST Web Service`, ensuring compatibility across various platforms. # Split Payments Source: https://developer.paymee.com.br/api-reference/split-payments Split a PIX charge between your account and linked recipients, with fees and refunds handled by your account. Split payments let you divide a single PIX charge between your account (the **parent**) and one or more **recipients**. The payer sees and pays one charge. After payment, PayMee credits each recipient with its share and credits the remainder to the parent. ## Concepts * **Parent:** the account whose credentials create the charge. The parent pays all PayMee fees and is the only account that can refund the sale. * **Recipient:** an account linked to the parent by PayMee operations. Recipients cannot be created or linked through the API. Contact PayMee to enable split for your account and to link recipients. * **Leg:** the share of one recipient in a charge. Each leg creates a recipient-side transaction, owned by the recipient account and identified by `transactionId`. Use the [recipients endpoints](/api-reference/split/list-split-recipients) to find the `recipientId` of each linked recipient. ## Creating a split charge Send the optional `split` array in [`POST /v1.1/checkout/transparent`](/api-reference/checkouts/semi-transparent-wire-transfer-pix-and-credit-card-and-openbanking-checkout). Each item is one leg: | Field | Type | Required | Description | | :------------------ | :------------ | :------------------------------ | :---------------------------------------------------------------------------------------------------------- | | `recipientId` | string (UUID) | Yes | Recipient identifier from the recipients endpoints. | | `amount` | number | One of `amount` or `percentage` | Fixed amount. At least `0.01`, up to two decimal places. | | `percentage` | number | One of `amount` or `percentage` | Percentage of the charge `amount`. Greater than `0` and up to `100`, up to four decimal places. | | `externalReference` | string | No | Your reference for the leg, up to 100 characters. Control characters are removed and whitespace is trimmed. | **Example: split by fixed amounts** ```json theme={null} POST /v1.1/checkout/transparent { "currency": "BRL", "amount": 100.00, "referenceCode": "ORDER-1001", "maxAge": 120, "paymentMethod": "PIX", "callbackURL": "https://foo.bar/paymeeListener", "shopper": { "id": "24391203", "email": "foo@bar.com", "name": "JOHN DOE", "document": { "type": "CPF", "number": "00000000000" }, "phone": { "type": "MOBILE", "number": "11999990000" } }, "split": [ { "recipientId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "amount": 35.50, "externalReference": "ORDER-1001-A" }, { "recipientId": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "amount": 12.50, "externalReference": "ORDER-1001-B" } ] } ``` **Example: split by percentage** ```json theme={null} "split": [ { "recipientId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "percentage": 33.3333 }, { "recipientId": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "percentage": 12.5 } ] ``` For an `amount` of `100.00`, these legs resolve to `33.33` and `12.50`, and the parent keeps `54.17`. You can mix legs by amount and legs by percentage in the same charge. ## Rules * **PIX only.** `paymentMethod` must be `PIX`. Split is not supported with `BOLETO`, `BOLETO_PIX`, `CREDIT_CARD` or `INITIATOR`, and cannot be combined with `recurrence`, scheduled payments, `taxData` or the legacy `sellersTransactions` field. * **Enablement.** Split must be enabled for your account. * **Recipients.** Up to **20** recipients per charge by default. PayMee can configure this limit. Each recipient can appear only once, cannot be your own account and must be active and linked to your account. * **`amount` or `percentage`.** Each leg must have exactly one of them. * **Rounding.** Percentage legs are calculated on the charge `amount` and **rounded down** to cents. The rounding remainder stays with the parent. Each resolved leg must be at least `0.01`. * **Total.** The sum of all legs must be less than or equal to the charge `amount`. * **Fees.** PayMee fees are calculated on the full charge `amount` and charged **to the parent only**. The parent remainder (`amount` minus all legs) must cover these fees, otherwise the request is rejected with `split.parentAmountInsufficientForFees`. Recipients receive their full leg amount, without fees. * **Refunds.** Refunds are requested only on the parent sale, through the [refund endpoint](/api-reference/request-a-sale-refund), and are debited from the parent balance. Recipient balances are not debited, so the parent balance plus its overdraft limit must cover the full refund amount, including the recipients' shares. The sum of all non-cancelled refunds of the sale cannot exceed the sale total (`grossAmount`). A refund requested on a recipient-side transaction is rejected with `split.childRefundNotAllowed`. ## Response The checkout response includes a `split` block at the root of the body, next to `response`: ```json theme={null} { "status": 0, "message": "success", "response": { "amount": 100.00, "uuid": "00000000-0000-4000-8000-000000000000", "referenceCode": "ORDER-1001", "instructions": { "chosen": "PIX", "qrCode": { "plain": "00020101021226...6304ABCD" } } }, "split": { "feePayer": "PARENT", "refundLiability": "PARENT", "grossAmount": 100.00, "parentAmount": 52.00, "recipients": [ { "recipientId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "transactionId": "11111111-1111-4111-8111-111111111111", "amount": 35.50, "percentage": null, "externalReference": "ORDER-1001-A", "settlementStatus": "PENDING" }, { "recipientId": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "transactionId": "22222222-2222-4222-8222-222222222222", "amount": 12.50, "percentage": null, "externalReference": "ORDER-1001-B", "settlementStatus": "PENDING" } ] } } ``` | Field | Description | | :------------------------------- | :----------------------------------------------------------------- | | `feePayer` | Always `PARENT`. | | `refundLiability` | Always `PARENT`. | | `grossAmount` | Sale total. | | `parentAmount` | `grossAmount` minus the sum of all legs, before PayMee fees. | | `recipients[].recipientId` | Recipient identifier. | | `recipients[].transactionId` | Recipient-side transaction created for the leg. | | `recipients[].amount` | Resolved leg amount. | | `recipients[].percentage` | Percentage sent in the request, or `null` for legs sent by amount. | | `recipients[].externalReference` | Your leg reference, or `null`. | | `recipients[].settlementStatus` | See [Settlement status](#settlement-status). | Without `split` in the request, the response does not change. ## Querying split sales [`GET /v1.1/transactions/{transactionUUID}`](/api-reference/query-a-transaction) and [`GET /v1.1/transactions`](/api-reference/query-transactions-using-filters) return the same `split` block for parent sales. Query the parent sale to follow the settlement of each leg. A recipient-side transaction belongs to the recipient account and is returned only with the recipient's credentials. It has the leg amount as its total, the parent transaction UUID as its `referenceCode`, and a recipient variant of the `split` block: ```json theme={null} "split": { "role": "RECIPIENT", "origin": "SPLIT", "refundLiability": "PARENT", "amountReceived": 35.50, "settlementStatus": "SETTLED" } ``` ## Settlement status Recipients are credited asynchronously, after the parent sale is paid. No recipient is credited while the parent sale is unpaid. | `settlementStatus` | Meaning | | :----------------- | :-------------------------------------------------------------------------------------------------- | | `PENDING` | The leg has not been credited to the recipient yet. | | `PROCESSING` | Crediting the recipient is in progress. | | `SETTLED` | The leg amount was credited to the recipient balance. | | `FAILED` | Crediting failed. PayMee retries it automatically. If a leg stays `FAILED`, contact PayMee support. | ## Webhooks * **Parent.** When the sale is paid, the payment confirmation for the parent sale is sent to the charge `callbackURL`, or to the webhook URL configured for your account. It includes the parent `split` block, with the same content as the checkout response. Its `settlementStatus` values are a snapshot taken when the notification was first built, usually `PENDING`; automatic delivery retries resend that same snapshot. Query the transaction for the current status. * **Recipients.** Each recipient account receives a payment confirmation (`newStatus: PAID`) for its own recipient-side transaction, at the webhook URL configured for the recipient account. The request has no per-recipient callback URL, so a recipient without a configured webhook URL receives no notification. It includes the recipient `split` block, usually with `settlementStatus` `PROCESSING`, and its `referenceCode` is the parent transaction UUID. * No notification is sent when a leg's `settlementStatus` changes later. Poll the parent sale, or the recipient-side transaction with the recipient's credentials, using the [transaction query](/api-reference/query-a-transaction) to follow settlement. * Payment confirmations for sales without `split` do not change. See [Webhook Notifications](/api-reference/webhook#split-payments) for the payloads. ## Errors Split errors use the standard error envelope, with the split code in `errors[].message`. For `split.*` checkout errors, `errors[].field` is `split` (or `split[n].` for field format errors); the split and tax data conflict is reported as `taxData.unsupportedSaleType` in `errors[].code` on field `taxData`. The recipient refund rejection (`split.childRefundNotAllowed`) uses `saleToken`, and the recipients endpoints use `split` for `split.notEnabled` and `recipientId` for `split.recipientNotFound`. ```json theme={null} { "status": -1, "message": "validation failure", "errorCount": 1, "errors": [ { "field": "split", "message": "split.recipientNotFound" } ], "main_error_message": "split.recipientNotFound" } ``` | HTTP | Code | Meaning | | :--- | :-------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `split.notEnabled` | Split is not enabled for your account. | | 400 | `split.unsupportedPaymentMethod` | `paymentMethod` is not `PIX`. | | 400 | `split.unsupportedRecurrence` | Split cannot be combined with `recurrence`. | | 400 | `split.unsupportedSchedule` | Split cannot be combined with scheduled payments. | | 400 | `split.contractConflict` | Split cannot be combined with `sellersTransactions`. | | 400 | `split.valueRequired` | `split` is empty, or a leg has neither `amount` nor `percentage`. | | 400 | `split.valueConflict` | A leg has both `amount` and `percentage`. | | 400 | `split.tooManyRecipients` | More legs than the per-charge limit (20 by default). | | 400 | `split.amountTooLow` | `amount` is below `0.01` or has more than two decimal places, or a percentage leg resolves below `0.01`. | | 400 | `split.percentageOutOfRange` | `percentage` is not greater than 0 and up to 100, or has more than four decimal places. | | 400 | `split.duplicateRecipient` | The same `recipientId` appears more than once. | | 400 | `split.recipientEqualsParent` | `recipientId` is your own account. | | 400 | `split.recipientNotFound` | The recipient does not exist or is not linked to your account. Both cases return this code on purpose. | | 400 | `split.recipientInactive` | The recipient is linked but not active. | | 400 | `split.externalReferenceTooLong` | `externalReference` is longer than 100 characters. | | 400 | `split.sumExceedsAmount` | The sum of all legs is greater than the charge `amount`. | | 400 | `split.parentAmountInsufficientForFees` | The parent remainder does not cover the PayMee fees. | | 400 | `taxData.unsupportedSaleType` | `taxData` was sent with `split`. This error uses `errors[].code`. | | 400 | `split.childRefundNotAllowed` | Refund requested on a recipient-side transaction ([refund endpoint](/api-reference/request-a-sale-refund)). | | 403 | `split.notEnabled` | Recipients endpoints: split is not enabled for your account. | | 404 | `split.recipientNotFound` | [Get a split recipient](/api-reference/split/get-split-recipient): the recipient does not exist, is not linked to your account or is not active. | # Get a split recipient Source: https://developer.paymee.com.br/api-reference/split/get-split-recipient get /v1.1/split/recipients/{recipientId} Returns one active recipient linked to your account. Unknown, unlinked and inactive recipients all return the same 404 response. Requires split to be enabled for your account. # List split recipients Source: https://developer.paymee.com.br/api-reference/split/list-split-recipients get /v1.1/split/recipients Lists the active recipients linked to your account, most recently linked first. Recipients are provisioned by PayMee operations; there is no API to create or change them. Requires split to be enabled for your account. # Testing Pix Automatic in Sandbox Source: https://developer.paymee.com.br/api-reference/test-pix-automatic-in-sandbox Drive the full Pix Automatic recurrence lifecycle in the Sandbox using the simulator endpoints — authorize, charge, settle, fail and cancel without a real payer. ## Overview Pix Automatic depends on asynchronous webhooks sent by the acquirer (mandate approvals, scheduled charges, settlements, failures). In the Sandbox, PayMee exposes a **simulator** that produces those exact webhooks and feeds them to the same handlers used in production, so you can exercise the entire recurrence lifecycle end to end without a real payer. All simulator endpoints live under: ``` https://apisandbox.paymee.com.br/v1.1/pix-automatic/sandbox/sim ``` These endpoints exist **only** in the Sandbox. They authenticate with the same `x-api-key` and `x-api-token` as the rest of the API and act only on recurrences that belong to your test merchant. ## Authentication Every simulator call requires both headers: ```http theme={null} x-api-key: x-api-token: Content-Type: application/json ``` ## Typical end-to-end flow `POST /v1.1/pix-automatic/plans` — defines the frequency and amount of the recurrence. `POST /v1.1/checkout/pix-automatic` — returns an `idRec` for the new authorization, which starts in `CREATED`. `POST /sandbox/sim/mandate/{idRec}/approved` — drives the approval and moves the recurrence to `APPROVED`. A `RECURRENCE_AUTHORIZED` webhook is emitted. `POST /sandbox/sim/recurrence/{idRec}/run-due` — generates the next scheduled collection (a sale) for recurrences whose next charge falls within the due window. `POST /sandbox/sim/collection/{txId}/concluded` to settle, or `POST /sandbox/sim/collection/{txId}/reject/{code}` to fail with a reason code. Each individual `mandate` action drives the full prerequisite sequence automatically. Calling `.../mandate/{idRec}/approved` on a recurrence still in `CREATED` first drives `APPROVING` and then `APPROVED`, so the action works from any starting state. ## Mandate (authorization) endpoints | Endpoint | Effect | | :--------------------------------------------- | :---------------------------------------------------- | | `POST /sandbox/sim/mandate/{idRec}/approving` | Marks the authorization as in progress (`APPROVING`). | | `POST /sandbox/sim/mandate/{idRec}/approved` | Approves the mandate (`APPROVED`). | | `POST /sandbox/sim/mandate/{idRec}/rejected` | Rejects the authorization (`REJECTED`). | | `POST /sandbox/sim/mandate/{idRec}/expired` | Expires the authorization request (`EXPIRED`). | | `POST /sandbox/sim/mandate/{idRec}/cancelling` | Starts cancellation (`CANCELLING`). | | `POST /sandbox/sim/mandate/{idRec}/cancelled` | Completes cancellation (`CANCELLED`). | ## Collection (charge) endpoints | Endpoint | Effect | | :-------------------------------------------------- | :-------------------------------------------------------------- | | `POST /sandbox/sim/recurrence/{idRec}/run-due` | Generates the next due collection (sale) for the recurrence. | | `POST /sandbox/sim/collection/{txId}/active` | Marks the collection as active/scheduled. | | `POST /sandbox/sim/collection/{txId}/concluded` | Settles the collection and credits the merchant balance. | | `POST /sandbox/sim/collection/{txId}/failed` | Fails the collection (insufficient funds). | | `POST /sandbox/sim/collection/{txId}/canceled` | Cancels the collection. | | `POST /sandbox/sim/collection/{txId}/reject/{code}` | Rejects the collection with a specific reason code (see below). | | `POST /sandbox/sim/collection/{txId}/retry` | Triggers the retry sweep for failed collections (3R/7D policy). | ## One-shot scenarios For convenience, composite scenarios drive a whole sequence in a single call: ``` POST /v1.1/pix-automatic/sandbox/sim/recurrence/{idRec}/scenario/{name} ``` | `name` | Sequence driven | | :------------------- | :---------------------------------------------------------------------- | | `approve-and-settle` | Approve the mandate, generate the first charge, settle it and conclude. | | `no-funds-3x` | Approve, then fail the charge repeatedly to exercise the retry policy. | | `approve-reject` | Approve the request, then reject it. | | `cancel-by-payer` | Approve the mandate, then cancel it on the payer's side. | ## Failure reason codes Use these codes with `.../collection/{txId}/reject/{code}` (or `.../recurrence/{idRec}/fail/{code}`): | Code | Meaning | | :-------------- | :---------------------------------------- | | `FAIL` / `AM04` | Insufficient funds in the payer's account | | `AC06` | Payer's account is blocked | | `AC03` / `AC01` | Invalid payer account | | `MD01` | Authorization missing or revoked | | `SL02` | Pix Automatic limit exceeded | | `AG03` | Operation not allowed for the account | | `AB09` | Failure at the payer's PSP | | `SLCR` | Cancellation requested | The due window for `run-due` is `[now + 2 days, now + 10 days]`. A freshly created recurrence whose next charge date is outside this window will not generate a collection until its next cycle approaches; the `approve-and-settle` scenario handles the first charge for you. ## Related See the Pix Automatic (Recurrence) notification payloads emitted during these flows. # Update Plan Source: https://developer.paymee.com.br/api-reference/update-plan put /v1.1/pix-automatic/plans/{planId} Updates an existing recurrence plan. All fields are optional; only the fields sent are changed. Changing recurrenceAmount immediately affects the NEXT charges of every active subscription created with variable amount (valueType VARIABLE). Fixed-amount subscriptions keep the amount authorized by the payer (Banco Central rule) and are not affected. # Webhook Notifications Source: https://developer.paymee.com.br/api-reference/webhook Receiving real-time event notifications from PayMee via webhooks, including authentication, examples, and response formats. Webhooks allow your application to receive real-time notifications about events related to your PayMee transactions, such as payment confirmations, reversals, or refunds. These are essential for keeping your system synchronized with the status of payments without needing to poll the API constantly. ## Notification Mechanism PayMee sends **Notification Posts** to a URL you configure in your PayMee merchant panel. These notifications are triggered based on specific events occurring within the PayMee system. * **Method:** `POST` * **Protocol:** `HTTP` / `HTTPS` (HTTPS is strongly recommended for security) * **Configurable Events:** You can select which events trigger a notification in your panel. Common event types that can be configured include: | Event Context | Notifiable Statuses / Events | | :---------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------- | | Sale | `PAID`, `REVERSAL` | | Transfer | `PAID` | | Payout | `PAID`, `FAILED` | | Refund | `PAID` | | Reversal | `PENDING`, `PAID`, `CANCELLED` | | *Note: This table provides a general overview. Consult your PayMee panel for the exact configuration options available for your account.* | | ## Authentication Webhook notifications sent by PayMee use **HTTP Basic Authentication** for security, ensuring that the requests genuinely originate from PayMee. * **Username:** Your PayMee `x-api-key` * **Password:** Your PayMee `x-api-token` Your webhook listener endpoint **must** validate these credentials from the `Authorization` header of incoming requests before processing the payload. **Example Basic Auth Header Construction:** 1. **Combine Credentials:** Concatenate your API key and token, separated by a colon (`:`). *Example:* `af38b751-30d7-4261-a9fb-ea30f6ece609:28331f43-e2b3-4078-9502-5f656fb66cdf` 2. **Encode with Base64:** Encode the resulting string using Base64. *Example Encoded Value:* `YWYzOGI3NTEtMzBkNy00MjYxLWE5ZmItZWEzMGY2ZWNlNjA5OjI4MzMxZjQzLWUyYjMtNDA3OC05NTAyLTVmNjU2ZmI2NmNkZg==` 3. **Construct Header:** The `Authorization` header sent by PayMee will look like this: ```http theme={null} Authorization: Basic YWYzOGI3NTEtMzBkNy00MjYxLWE5ZmItZWEzMGY2ZWNlNjA5OjI4MzMxZjQzLWUyYjMtNDA3OC05NTAyLTVmNjU2ZmI2NmNkZg== ``` ## Expected Response & Retries For **all** types of webhook notifications received from PayMee: * Your callback URL **must** respond promptly with an `HTTP 200 OK` status code to acknowledge successful receipt and acceptance of the notification. Any other status code (or a timeout) will be interpreted as a failure. * If PayMee does not receive a `200 OK` status, it will automatically retry sending the notification to ensure delivery. * Retries occur at approximately **60-second intervals**. * PayMee will attempt a maximum of **5 retries** after the initial failure. * **Idempotency:** It's crucial to design your webhook handler to be idempotent. This means processing the same notification multiple times should not result in duplicate actions or inconsistent states in your system, as network issues could lead to retries even if you processed the notification initially. Using the `saleToken` or `uuid` from the payload is a common way to check if an event has already been processed. *** ## Payment Confirmation Notification *(Also known as Transfer/Walk-in Notification)* This notification is sent when a payment associated with a transaction is successfully confirmed (status transitions to `PAID`). **Example Notification POST:** ```http theme={null} POST /your-callback-path HTTP/1.1 Host: your-registered-domain.com Authorization: Basic Content-Length: Content-Type: application/json { "saleToken": "d59b39ce-bffd-3f6d-80c4-c376a242afd1", "referenceCode": "0000000000014", "currency": "BRL", "amount": 100.00, "shopper": { "id": "12911", "firstName": "Teste", "lastName": "Silva", "email": "teste@teste.com.br", "agency": "1234", "account": "123456-0" }, "date": "2017-07-28 10:48:56", "newStatus": "PAID" } ``` **Requirements:** * A valid **Payment Status URL** must be configured in your PayMee merchant panel settings. **Response Payload Fields:** | Property | Type | Description | | :------------------ | :----- | :-------------------------------------------------------------------------- | | `saleToken` | string | The unique identifier (UUID) of the transaction. | | `referenceCode` | string | Your unique order identification code provided during transaction creation. | | `amount` | number | The amount of the order. | | `currency` | string | The currency code (e.g., `BRL`). | | `shopper.id` | string | The shopper's ID in your system (if provided). | | `shopper.firstName` | string | Shopper's first name. | | `shopper.lastName` | string | Shopper's last name. | | `shopper.email` | string | Shopper's email address. | | `shopper.agency` | string | Shopper's bank agency (if applicable). | | `shopper.account` | string | Shopper's bank account (if applicable). | | `date` | string | Timestamp of the payment confirmation (`yyyy-MM-dd HH:mm:ss`). | | `newStatus` | string | The new status of the payment, typically `PAID`. | *** ## Boleto and BolePix `BOLETO` and `BOLETO_PIX` use the existing payment confirmation notification with `newStatus: PAID`, after payment is confirmed and processed. Payload fields, Basic Authentication and acknowledgment requirements remain unchanged. No separate boleto registration event or additional boleto/Pix fields are added to this webhook. Boleto registration and QR code generation do not confirm payment. Settlement processing is asynchronous. For BolePix, the customer pays once, using either the boleto or Pix. After settlement, cancellation of the alternative payment instrument is requested asynchronously; it is not an immediate guarantee against a second payment. Use `saleToken` and `referenceCode` to match the sale and process notifications idempotently. Retrieve boleto details through the [transaction query](/api-reference/query-a-transaction), in the root `boleto` field. *** ## Split Payments For [split payments](/api-reference/split-payments), the payment confirmation uses the payload above plus an additive `split` block. Payloads of sales without split do not change. **Parent sale.** Sent to the charge `callbackURL`, or to the webhook URL configured for your account. The `split` block has the same content as the checkout response. Its `settlementStatus` values are a snapshot taken when the notification was first built, usually `PENDING`; automatic delivery retries resend that same snapshot. Query the transaction for the current status. `percentage` and `externalReference` are `null` when they were not sent for the leg. ```json theme={null} { "newStatus": "PAID", "saleToken": "00000000-0000-4000-8000-000000000000", "referenceCode": "ORDER-1001", "currency": "BRL", "amount": 100.00, "shopper": { "fullName": "JOHN DOE", "firstName": "JOHN", "lastName": "DOE", "email": "foo@bar.com", "cpf": "00000000000" }, "date": "2026-09-23 10:05:00", "split": { "feePayer": "PARENT", "refundLiability": "PARENT", "grossAmount": 100.00, "parentAmount": 52.00, "recipients": [ { "recipientId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "transactionId": "11111111-1111-4111-8111-111111111111", "amount": 35.50, "percentage": null, "externalReference": "ORDER-1001-A", "settlementStatus": "PENDING" }, { "recipientId": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "transactionId": "22222222-2222-4222-8222-222222222222", "amount": 12.50, "percentage": null, "externalReference": "ORDER-1001-B", "settlementStatus": "PENDING" } ] } } ``` **Recipient-side transaction.** Each recipient account receives a payment confirmation for its own recipient-side transaction, at the webhook URL configured for the recipient account. There is no per-recipient callback URL, so a recipient without a configured webhook URL receives no notification. `saleToken` is the recipient-side transaction, `amount` is the leg amount and `referenceCode` is the parent transaction UUID. `settlementStatus` is usually `PROCESSING` at this moment. ```json theme={null} { "newStatus": "PAID", "saleToken": "11111111-1111-4111-8111-111111111111", "referenceCode": "00000000-0000-4000-8000-000000000000", "currency": "BRL", "amount": 35.50, "shopper": { "fullName": "JOHN DOE", "firstName": "JOHN", "lastName": "DOE", "email": "foo@bar.com", "cpf": "00000000000" }, "date": "2026-09-23 10:05:00", "split": { "refundLiability": "PARENT", "role": "RECIPIENT", "origin": "SPLIT", "amountReceived": 35.50, "settlementStatus": "PROCESSING" } } ``` No notification is sent when a leg's `settlementStatus` changes later. Query the parent sale, or the recipient-side transaction with the recipient's credentials, using the [transaction query](/api-reference/query-a-transaction) to follow settlement. *** ## Loan Status Notification The loan status notification reports credit decision changes for BNPL transactions. It uses a PayMee-owned contract so integrations do not depend on a credit provider's payload. This webhook contract is currently in preview and is published for integration planning. Do not rely on it in production until PayMee confirms enablement for your account. The `status` field can contain: | `status` | When it is sent | | :---------- | :-------------------------------------------------------------------- | | `APPROVED` | The credit proposal was approved and the BNPL contract was completed. | | `DENIED` | The credit proposal was declined. | | `ABANDONED` | The customer did not complete the onboarding flow before expiration. | **Example Notification POST:** ```http theme={null} POST /your-callback-path HTTP/1.1 Host: your-registered-domain.com Authorization: Basic Content-Type: application/json { "eventType": "LOAN_STATUS_CHANGED", "saleToken": "d59b39ce-bffd-3f6d-80c4-c376a242afd1", "referenceCode": "order-00000014", "status": "APPROVED", "date": "2026-08-21 10:48:56" } ``` **Response Payload Fields:** | Property | Type | Description | | :-------------- | :----- | :------------------------------------------------------------------------ | | `eventType` | string | Event identifier. Always `LOAN_STATUS_CHANGED`. | | `saleToken` | string | PayMee UUID of the BNPL transaction. | | `referenceCode` | string | Merchant order identifier provided when the loan transaction was created. | | `status` | string | Current credit decision: `APPROVED`, `DENIED`, or `ABANDONED`. | | `date` | string | Event timestamp in `America/Sao_Paulo` (`yyyy-MM-dd HH:mm:ss`). | Loan approval is distinct from an installment payment. When the associated merchant transaction is financially confirmed, PayMee sends the standard [`PAYMENT_CONFIRMATION`](#payment-confirmation-notification) webhook. Overdue installment and chargeback events are not part of the loan status contract. **Requirements:** * A valid **Payment Status URL** must be configured in your PayMee merchant panel settings. * Your endpoint must follow the authentication, acknowledgement, retry, and idempotency requirements described above. *** ## Pix Automatic (Recurrence) Notification These notifications cover a Pix Automatic recurrence: the **mandate lifecycle** (authorization → conclusion) and **each paid charge**. The event is identified by the `eventType` field: | `eventType` | When it is sent | | :---------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `RECURRENCE_AUTHORIZED` | The payer approved the mandate; the recurrence is now `APPROVED` and can be charged. | | `RECURRENCE_REJECTED` | The payer rejected the authorization request (`REJECTED`). | | `RECURRENCE_EXPIRED` | The authorization request was not answered in time and expired (`EXPIRED`). | | `RECURRENCE_CANCELLED` | The mandate was cancelled, by either party (`CANCELLED`). | | `RECURRENCE_CONCLUDED` | The recurrence reached the end of its agreed period (`CONCLUDED`). | | `RECURRENCE_CHARGE_SCHEDULED` | A new charge (cycle) was registered at the payer's bank. Carries `chargeDueDate` and `chargeAmount`. | | `RECURRENCE_CHARGE_PAID` | A scheduled charge (cycle) of the recurrence was paid. Carries the paid `saleToken` and `chargeAmount`. | | `RECURRENCE_CHARGE_FAILED` | A charge failed or was rejected (e.g. insufficient funds). Carries `rejectionCode`, `rejectionReason` and `retryScheduled` (whether an automatic retry was scheduled). | Recurring charges are notified **exclusively** through the `RECURRENCE_*` events — they do **not** emit the generic [`PAYMENT_CONFIRMATION`](#payment-confirmation-notification) (only the optional immediate payment of a Journey-3 checkout does, since it carries your own order `referenceCode`). Each charge cycle produces `RECURRENCE_CHARGE_SCHEDULED` when registered, then `RECURRENCE_CHARGE_PAID` or `RECURRENCE_CHARGE_FAILED`. Every event carries `idRec`, your `externalId`, `planId` and, for charge events, the `saleToken` of that specific charge for reconciliation. You can also reconcile at any time via `GET /v1.1/pix-automatic/scheduled-payments`. All dates are in `America/Sao_Paulo` (GMT-3). **Example Notification POST:** ```http theme={null} POST /your-callback-path HTTP/1.1 Host: your-registered-domain.com Authorization: Basic Content-Type: application/json { "eventType": "RECURRENCE_AUTHORIZED", "idRec": "RR286838922026062203474822291", "externalId": "your-order-ref-001", "planId": "6a38da8623711b0007b267a6", "contractId": "6a38da8623711b0007b267a6", "contractDescription": "Monthly subscription", "status": "APPROVED", "periodicity": "MONTHLY", "valueType": "FIXED", "amount": 15.00, "payerDocument": "12345678909", "payerName": "John Doe", "initialDate": "2026-06-25 00:00:00", "finalDate": null, "nextRecurrenceDate": "2026-07-25 00:00:00", "eventDate": "2026-06-22 21:48:34" } ``` **Example `RECURRENCE_CHARGE_PAID` (a paid charge):** ```json theme={null} { "eventType": "RECURRENCE_CHARGE_PAID", "idRec": "RR286838922026062203474822291", "externalId": "your-order-ref-001", "planId": "6a38da8623711b0007b267a6", "status": "APPROVED", "amount": 15.00, "payerDocument": "12345678909", "payerName": "John Doe", "nextRecurrenceDate": "2026-07-25 00:00:00", "saleToken": "2ce02094-ab3b-4649-aac8-1a8f122b0ca1", "chargeAmount": 15.00, "chargeDueDate": "2026-06-25 00:00:00", "chargeStatus": "PAID", "eventDate": "2026-06-23 16:54:22" } ``` **Example `RECURRENCE_CHARGE_FAILED` (a failed charge):** ```json theme={null} { "eventType": "RECURRENCE_CHARGE_FAILED", "idRec": "RR286838922026062203474822291", "externalId": "your-order-ref-001", "planId": "6a38da8623711b0007b267a6", "status": "APPROVED", "amount": 15.00, "payerDocument": "12345678909", "payerName": "John Doe", "saleToken": "bae33c40-df9f-4fd4-ba9a-cbf7cca1a622", "chargeAmount": 15.00, "chargeDueDate": "2026-07-25 00:00:00", "chargeStatus": "REJECTED", "rejectionCode": "AM04", "rejectionReason": "Saldo insuficiente na conta do pagador", "retryScheduled": true, "eventDate": "2026-07-25 08:00:12" } ``` **Response Payload Fields:** | Property | Type | Description | | :-------------------- | :------ | :---------------------------------------------------------------------------------------------------------------- | | `eventType` | string | The recurrence event (see the table above). | | `idRec` | string | The acquirer identifier of the recurrence/mandate. | | `externalId` | string | Your unique reference provided when the recurrence was created. | | `planId` | string | Identifier of the plan the recurrence belongs to. | | `contractId` | string | Identifier of the contract (mirrors `planId`). | | `contractDescription` | string | Human-readable description of the plan/contract. | | `status` | string | The new status of the recurrence (e.g. `APPROVED`, `REJECTED`, `EXPIRED`, `CANCELLED`, `CONCLUDED`). | | `periodicity` | string | Charge frequency (`WEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMIANNUAL`, `ANNUALLY`). | | `valueType` | string | `FIXED` for a fixed amount or `VARIABLE` for a per-cycle amount. | | `amount` | number | The recurrence amount. | | `payerDocument` | string | The payer's CPF/CNPJ. | | `payerName` | string | The payer's name. | | `initialDate` | string | Start date of the recurrence (`yyyy-MM-dd HH:mm:ss`). | | `finalDate` | string | End date of the recurrence, or `null` if open-ended. | | `nextRecurrenceDate` | string | Date of the next scheduled charge (`yyyy-MM-dd HH:mm:ss`). | | `saleToken` | string | **Charge events only.** Token of that specific charge (use it for reconciliation). | | `chargeAmount` | number | **Charge events only.** Amount of that specific charge. | | `chargeDueDate` | string | **Charge events only.** Due date of that charge (`yyyy-MM-dd HH:mm:ss`). | | `chargeStatus` | string | **Charge events only.** Status of the charge (`SCHEDULED`, `PAID`, `FAILED`, `REJECTED`, `CANCELLED`). | | `rejectionCode` | string | **`RECURRENCE_CHARGE_FAILED` only.** Bacen reason code (e.g. `AM04` insufficient funds, `AC06` blocked account). | | `rejectionReason` | string | **`RECURRENCE_CHARGE_FAILED` only.** Human-readable description of the failure. | | `retryScheduled` | boolean | **`RECURRENCE_CHARGE_FAILED` only.** `true` when an automatic retry was scheduled (mandates with `ACCEPT_3R_7D`). | | `eventDate` | string | Timestamp the notification was generated (`yyyy-MM-dd HH:mm:ss`). | **Requirements:** * A valid **Payment Status URL** must be configured in your PayMee merchant panel settings. *** ## Reversal Notification This notification is sent regarding the status of a transaction reversal (returning funds to the original payer, often due to issues like non-identification or cancellation). **Example Notification POST:** ```http theme={null} POST /your-callback-path?reversing=true&type=reversing HTTP/1.1 Host: your-registered-domain.com Authorization: Basic Content-Length: Content-Type: application/json { "id": 611212, "uuid": "d19b39ce-bffd-3f6d-80c4-c376a242afd3", "currency": "BRL", "originalAmount": 100.00, "reversedAmount": 100.00, "status": "PENDING", "bankDetails": { "bank": "341 - BANCO ITAÚ-UNIBANCO S.A.", "branch": "0000", "account": "00000-0" }, "sale": { "id": 611210, "uuid": "75e0b5e2-bc3f-4e75-9c52-24096f2e004d" }, "creation": "2018-04-15 08:33:22", "receipt": null, "reason": "amount greater than total of sale" } ``` *** **Requirements:** * A **Reversal Status URL** must be registered in your PayMee merchant panel. * The reversal notification feature must be **enabled** in your panel settings for this URL. **Trigger Moments & Status:** This notification can inform you about key stages of a reversal: 1. **Reversal Initiated/Pending:** Sent when PayMee initiates a reversal (e.g., cannot approve or identify the original sale, triggering a return). The `status` attribute will typically be `PENDING`. 2. **Reversal Completed/Updated:** Sent when the amount is successfully returned to the customer (`PAID`) or if the reversal process is `CANCELLED`. Always check the `status` field for the specific outcome. **Response Payload Fields:** | Property | Type | Description | | :-------------------- | :----- | :--------------------------------------------------------------------------------------- | | `id` | number | The unique ID of the reversal transaction. | | `uuid` | string | The unique UUID of the reversal transaction. | | `currency` | string | The currency of the order (e.g., `BRL`). | | `originalAmount` | number | The amount of the original sale transaction. | | `reversedAmount` | number | The amount that was actually reversed. | | `bankDetails.bank` | string | Name/code of the bank receiving the reversed funds. | | `bankDetails.branch` | string | Bank branch receiving the reversed funds. | | `bankDetails.account` | string | Bank account receiving the reversed funds. | | `sale.id` | number | The ID of the original sale transaction being reversed. | | `sale.uuid` | string | The UUID of the original sale transaction being reversed. | | `creation` | string | Timestamp of the reversal creation (`yyyy-MM-dd HH:mm:ss`). | | `receipt` | string | Reversal receipt details or link (may be null or "under development" per original text). | | `status` | string | The current status of the reversal (`PENDING`, `PAID`, `CANCELLED`). | | `reason` | string | The reason provided for the reversal. | *** ## Refund Notification Sent when a partial or full refund initiated by you is successfully processed (`PAID`) for a previously paid transaction. **Example Notification POST:** ```http theme={null} POST /your-callback-path?refund=true&type=refund HTTP/1.1 Host: your-registered-domain.com Authorization: Basic Content-Length: Content-Type: application/json { "saleToken": "d19b39ce-bffd-3f6d-80c4-c376a242afd3", "referenceCode":"0000000000014", "currency": "BRL", "originalAmount": 150.00, "reversedAmount": 50.00, "bankDetails":{ "bank": "341 - BANCO ITAÚ-UNIBANCO S.A.", "branch":"0000", "account":"00000-0" }, "receipt": "null", "status": "PAID", "refund": { "id": 611211, "uuid": "fbebcd28-ae51-11e9-a2a3-2a2ae2dbcce4", "status": "PAID", "amount": 50.00, "creation": "2018-04-15 08:33:22", "creditDate": "2018-04-16 10:48:56" }, "reason": "amount greater than total of sale", "date":"2018-04-16 10:48:56" } ``` **Requirements:** * A **Refund Status URL** must be registered (the original text suggests this can often be the same URL used for Payment Notifications, but confirm this in your PayMee panel). * The refund notification feature must be **enabled** in your merchant panel settings for this URL. **Trigger Moment & Status:** * This notification is typically sent when the refund amount is successfully processed and credited back. The `status` field in the main object and within the `refund` object should indicate `PAID`. **Response Payload Fields:** | Property | Type | Description | | :-------------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------- | | `saleToken` | string | The unique identifier (UUID) of the original transaction being refunded. | | `referenceCode` | string | Your unique order identification code from the original transaction. | | `currency` | string | The currency code (e.g., `BRL`). | | `originalAmount` | number | The amount of the original transaction. | | `amountRefunded` | number | The amount that was refunded in this specific operation. *(Note: The example JSON payload used the field name `reversedAmount` for this value).* | | `bankDetails.bank` | string | Bank name for the refund credit (if applicable/available). | | `bankDetails.branch` | string | Bank branch for the refund credit (if applicable/available). | | `bankDetails.account` | string | Bank account for the refund credit (if applicable/available). | | `receipt` | string | Refund receipt details or link (may be null or "under development" per original text). | | `status` | string | The overall status related to this refund notification, typically `PAID`. | | `refund.id` | number | ID of the specific refund transaction itself. *(From Example)* | | `refund.uuid` | string | UUID of the specific refund transaction itself. *(From Example)* | | `refund.status` | string | Status of this specific refund transaction (e.g., `PAID`). *(From Example)* | | `refund.amount` | number | Amount processed in this specific refund transaction. *(From Example)* | | `refund.creation` | string | Creation timestamp of this refund transaction (`yyyy-MM-dd HH:mm:ss`). *(From Example)* | | `refund.creditDate` | string | Date the refund was effectively credited (`yyyy-MM-dd HH:mm:ss`). *(From Example)* | | `reason` | string | The reason provided for initiating the refund. | | `date` | string | Timestamp when this refund notification was generated (`yyyy-MM-dd HH:mm:ss`). | *(Note: Fields within the `refund` object were added based on the JSON example provided in the original text, as they offer more specific details about the refund operation itself.)* *** ## Payout Notification This notification informs about the status of a Payout operation (transferring funds out, often initiated by you to pay a user or supplier). It can indicate success or failure. **Example Success Notification POST:** ```http theme={null} POST /your-callback-path?payout=true&type=payout HTTP/1.1 Host: your-registered-domain.com Authorization: Basic Content-Length: Content-Type: application/json { "success": true, "message": "success", "id": 611212, "uuid": "d19b39ce-bffd-3f6d-80c4-c376a242afd3", "currency": "BRL", "amount": 100.00, "status": "PAID", "referenceCode": "XPADOA", "bankDetails": { "bank": "341 - BANCO ITAÚ-UNIBANCO S.A.", "branch": "0000", "account": "00000-0" }, "creation": "2018-04-15 08:33:22", "receipt": "https://receipts.paymee.com.br/transaction/23e49aa1f7f193395a7f30900f8aeb40a65a9d7dd85e8d05456847b800713546/d19b39ce-bffd-3f6d-80c4-c376a242afd3" } ``` Here is an error example of a notification sent by PayMee (the lines have been broken for ease of reading in the original source): ```http theme={null} POST /your-callback-path?payout=true HTTP/1.1 Host: your-registered-domain.com Authorization: Basic YWYzOGI3NTEtMzBkNy00MjYxLWE5ZmItZWEzMGY2ZWNlNjA5OjI4MzMxZjQzLWUyYjMtNDA3OC05NTAyLTVmNjU2ZmI2NmNkZg== Content-Type: application/json Content-Length: { "success": false, "message": "Os dados informados não são validos", "error_code": "PE0001", "id": 611212, "uuid": "d19b39ce-bffd-3f6d-80c4-c376a242afd3", "currency": "BRL", "amount": 100.00, "status": "PENDING", "referenceCode": "XPADOA", "bankDetails": { "bank": "341 - BANCO ITAÚ-UNIBANCO S.A.", "branch": "0000", "account": "00000-0" }, "creation": "2018-04-15 08:33:22", "receipt": "[https://receipts.paymee.com.br/transaction/23e49aa1f7f193395a7f30900f8aeb40a65a9d7dd85e8d05456847b800713546/d19b39ce-bffd-3f6d-80c4-c376a242afd3](https://receipts.paymee.com.br/transaction/23e49aa1f7f193395a7f30900f8aeb40a65a9d7dd85e8d05456847b800713546/d19b39ce-bffd-3f6d-80c4-c376a242afd3)" } ``` **Requirements:** * A **webhook URL** must be registered in your PayMee merchant panel (confirm if this is the same URL used for other notifications or a specific one for payouts). * The payout notification feature must be **enabled** in your panel settings for this URL. **Response Payload Fields:** *This table is constructed based on the fields shown in the success and error JSON examples provided earlier.* | Property | Type | Description | | :-------------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------- | | `success` | boolean | Indicates if the overall payout operation was successful (`true`) or encountered an error (`false`). | | `message` | string | A descriptive message related to the status (e.g., "success", or an error description like "Os dados informados não são validos"). | | `error_code` | string | An error code present if `success` is `false`. See Error Codes section below. | | `id` | number | The unique ID assigned by PayMee to this payout transaction. | | `uuid` | string | The unique UUID assigned by PayMee to this payout transaction. | | `currency` | string | The currency of the payout (e.g., `BRL`). | | `amount` | number | The amount of the payout transaction. | | `status` | string | The processing status of the payout (e.g., `PAID` on success, `PENDING` or other on error/processing). | | `referenceCode` | string | Your reference code associated with this payout, if you provided one. | | `bankDetails.bank` | string | Bank name/code for the payout destination account. | | `bankDetails.branch` | string | Bank branch for the payout destination account. | | `bankDetails.account` | string | Bank account number for the payout destination. | | `creation` | string | Timestamp when the payout transaction was created (`yyyy-MM-dd HH:mm:ss`). | | `receipt` | string | URL or reference details of the payout receipt, if available and generated. | ### Payout Error Codes When a Payout Notification has `success: false`, the `error_code` field provides a specific reason for the failure. Here are the codes mentioned in the original text: | Code | Description (Portuguese from original text) | Possible Meaning (Translation/Interpretation) | | :------- | :---------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- | | `PE0001` | Os dados bancarios fornecidos não validos | The bank details provided are not valid. | | `PE0002` | A titularidade da conta não pertence ao documento informado | The account ownership (holder name/document) does not match the provided identification document (e.g., CPF/CNPJ). | | `PE0003` | A conta nao aceita movimentacoes - (MOTIVOS) | The destination account does not accept transfers/transactions - (Specific REASONS might be provided by the bank). | | `PE0004` | OUTROS - (MOTIVOS) | Other unspecified reasons - (Specific REASONS might be provided). Check the `message` field in the notification payload for more context. |