Show UR

Show UR in Getnet Split Payments lets you query a partner's URs (Receivable Units), grouped by date and card brand, and check whether a specific item can still be canceled before requesting the cancellation. Both queries help confirm a partner's receivables position and avoid rejected cancellation calls.
information icon
Note: In this API, SellerId identifies the marketplace (the platform) and SubSellerId identifies the partner (the store). This naming differs from the rest of this documentation, where "seller" usually refers to the partner.

Check the UR Summary by Date and Card Brand

Use this query to get a partner's UR amounts, totaled by date and card brand, within a period.

  1. Send a GET request to /v1/mgm/show-ur/summary.
  2. Include the required parameters in the query string, as shown in the table below.
  3. Check the response code in the Check the Response Codes table, further down.

Query Parameters

ParameterTypeRules
SellerIdstringRequired. Marketplace identifier. Must be a valid UUID.
SubSellerIdintegerRequired. Partner (store) identifier. Must be greater than 0.
StartDatestring (date)Required. Start date of the period, in YYYY-MM-DD format. Cannot be 0001-01-01.
EndDatestring (date)Required. End date of the period, in YYYY-MM-DD format. Cannot be 0001-01-01 or exceed 30 days after StartDate.

Response Fields

The response fields follow the terminology used in this guide (lien, anticipation).

FieldDescription
merchantIdMerchant establishment code (EC).
brandCardNumeric code for the card brand.
gravameAmountAmount subject to lien (a receivables block via a local clearing chamber). Doesn't apply outside Brazil.
anticipationAmountAmount related to an anticipation (for example, via Receba-Já).
freeTotalAmountAmount free of lien or anticipation.

Example Response

The example below shows the response for the request GET /v1/mgm/show-ur/summary?SellerId=71422ada-4cf1-4e95-99dd-a0026eb35111&SubSellerId=81&StartDate=2024-03-15&EndDate=2024-04-14.
JSON
{ "sellerId": "71422ada-4cf1-4e95-99dd-a0026eb35111", "subSellerId": 81, "startDate": "2024-03-15T00:00:00", "endDate": "2024-04-14T00:00:00", "merchantId": 281534, "summaryBrandCardDay": [ { "brandCard": 1, "date": "2024-03-27T00:00:00", "gravameAmount": 0, "anticipationAmount": -1.35, "freeTotalAmount": 0 }, { "brandCard": 1, "date": "2024-03-28T00:00:00", "gravameAmount": 0, "anticipationAmount": 0, "freeTotalAmount": -0.27 }, { "brandCard": 1, "date": "2024-04-01T00:00:00", "gravameAmount": 0, "anticipationAmount": 0, "freeTotalAmount": 45.96 }, { "brandCard": 1, "date": "2024-04-05T00:00:00", "gravameAmount": 0, "anticipationAmount": 0, "freeTotalAmount": 107.44 }, { "brandCard": 3, "date": "2024-04-05T00:00:00", "gravameAmount": 0, "anticipationAmount": 0, "freeTotalAmount": 342.43 }, { "brandCard": 1, "date": "2024-04-08T00:00:00", "gravameAmount": 0, "anticipationAmount": 0, "freeTotalAmount": 157.36 }, { "brandCard": 3, "date": "2024-04-08T00:00:00", "gravameAmount": 0, "anticipationAmount": 0, "freeTotalAmount": 849.98 }, { "brandCard": 3, "date": "2024-04-10T00:00:00", "gravameAmount": 0, "anticipationAmount": 0, "freeTotalAmount": 52.56 }, { "brandCard": 1, "date": "2024-04-10T00:00:00", "gravameAmount": 0, "anticipationAmount": 0, "freeTotalAmount": 26.28 } ], "summaryDay": [ { "date": "2024-03-27T00:00:00", "gravameAmount": 0, "anticipationAmount": -1.35, "freeTotalAmount": 0 }, { "date": "2024-03-28T00:00:00", "gravameAmount": 0, "anticipationAmount": 0, "freeTotalAmount": -0.27 }, { "date": "2024-04-01T00:00:00", "gravameAmount": 0, "anticipationAmount": 0, "freeTotalAmount": 45.96 }, { "date": "2024-04-05T00:00:00", "gravameAmount": 0, "anticipationAmount": 0, "freeTotalAmount": 449.87 }, { "date": "2024-04-08T00:00:00", "gravameAmount": 0, "anticipationAmount": 0, "freeTotalAmount": 1007.34 }, { "date": "2024-04-10T00:00:00", "gravameAmount": 0, "anticipationAmount": 0, "freeTotalAmount": 78.84 } ] }
summaryBrandCardDay returns one item per card brand and date. summaryDay returns the total consolidated by date, summed across all card brands. For example, on 2024-04-05, 107.44 (brand 1) plus 342.43 (brand 3) add up to the consolidated 449.87. StartDate and EndDate are sent as date-only (YYYY-MM-DD), but the response echoes these and the other date fields as full date-times.

Check Whether an Item Can Be Canceled

Use this query before requesting an item's cancellation to confirm it's still in a status that allows cancellation.

  1. Send a GET request to /v1/mgm/show-ur/cancel-permission.
  2. Include the required parameters in the query string, as shown in the table below.
  3. Check the cancelPermission field in the response: true means the item can be canceled.

Query Parameters

ParameterTypeRules
OrderIdstringRequired. Order identifier. Up to 255 characters.
OrderItemIdstringRequired. Order item identifier. Up to 25 characters.
SellerIdstringRequired. Marketplace identifier. Must be a valid UUID.
SubSellerIdintegerRequired. Partner (store) identifier. Must be greater than 0.
AmountintegerRequired. Amount of the item to be canceled, in cents. Example: 150 equals R$ 1.50.

Business Rules

The query returns an error (code 422, with an errorCode and errorMessage) when:
  • The item already has a registered cancellation date.
  • The transaction status isn't any of the codes listed in the Transaction Status Codes table below (an unrecognized code, not just "not approved").
  • The transaction status is in the table below, but isn't Aprovado (code 00).
  • External cancellation validation doesn't allow the amount provided for the item.
Since only status 00 allows cancellation, every other status in the table below is denied the same way. The table serves to validate whether the code is recognized, not to indicate a different action per status.

Transaction Status Codes

CodeStatus
00Aprovado
70Aguardando
77Pendente
78Pendente Pagamento
83Timeout
86Desfeita
90Inexistente
91Negado Administradora
92Estornada
93Repetida
94Estornada Conciliação
98Cancelada Sem Confirmação
99Negado Gestão MarketPlace

Example Response

The API returns justification in English, as shown below.
JSON
{ "justification": "Amount can be canceled.", "cancelPermission": true }

Check the Response Codes

CodeMeaning
200Success.
204No content found for the given parameters.
400Invalid request.
422Business validation error.
A 422 response returns a list of errors, each with an errorCode and an errorMessage, reproduced below exactly as returned by the API:
JSON
[ { "errorCode": "SUR-0013", "errorMessage": "It is not possible to cancel a transaction that has already been canceled." } ]
An error not handled by the system (for example, a connection failure) returns a body in RFC 9457 format, with the fields Title, Status, Detail, and Instance.
Treat the RFC 9457 format as an indication of an infrastructure failure, not a validation response: for business errors, use the errorCode/errorMessage list from the 422 code above.

Next Steps

  1. Rejected Payments: search for payments that were rejected.
  2. Settlement: see the overview of how and when each seller gets paid.

On this page

Show UR