sale-cancellation

Sale Cancellation API — White Label — REST facade for requesting and tracking sale cancellations (reversals) in the Getnet White Label ecosystem, backed by the legacy SOAP service RequestCancelService.

Overview

sale-cancellation is the cancellation API of the White Label platform. It allows a partner application to request the cancellation (total or partial) of an original sale and to track the outcome through a 17-digit protocol.

Internally the service translates each REST call into the legacy SOAP service RequestCancelService, converting business codes returned by the backend into standard HTTP semantics.

Base path: /sale-cancellation/v1/cancellations
Auth standard: OAuth2 Bearer (JWT) validated at the API Gateway / Ingress
Version: 1.0.0
Response format: JSON (snake_case)
Contact: Getnet MPS White Label — mps-whitelabel@getnet.com.br

Architecture

text

API Consumer (Partner Application)
        │
        │ 600;">POST /v1/cancellations (Bearer token + sale data)
        ▼
┌─────────────────────────────────────────┐
│ Getnet Sale Cancellation API (WLB)      │
│                                         │
│ Validate payload → map REST to SOAP     │
│ protocol (17 digits, HTTP 202)          │
└─────────────────────────────────────────┘
        │
        │ requestCancelTransation / queryCancelTransation (SOAP)
        ▼
RequestCancelService (Legacy Backend)
business code → HTTP status (De/Para)

Note: "Transation" is misspelled on purpose — it mirrors the legacy SOAP operation name defined in the WSDL and cannot be changed.

text

API Consumer (Partner Application)
        │
        │ 600;">POST /v1/cancellations (Bearer token + sale data)
        ▼
┌─────────────────────────────────────────┐
│ Getnet Sale Cancellation API (WLB)      │
│                                         │
│ Validate payload → map REST to SOAP     │
│ protocol (17 digits, HTTP 202)          │
└─────────────────────────────────────────┘
        │
        │ requestCancelTransation / queryCancelTransation (SOAP)
        ▼
RequestCancelService (Legacy Backend)
business code → HTTP status (De/Para)

Note: "Transation" is misspelled on purpose — it mirrors the legacy SOAP operation name defined in the WSDL and cannot be changed.

Key Design Decisions

Concern	Solution
Style	RESTful resource `cancellations`, versioned in the path (`/v1`)
Authentication	Not enforced by the service; Bearer JWT validated by the Gateway/Ingress
Asynchronous nature	`POST` returns 202 Accepted with a tracking `protocol`
Idempotency	`POST` is not idempotent (repeated calls may create different protocols); `GET` is safe and idempotent
Status semantics	Legacy SOAP business codes translated to HTTP status (De/Para mapping)
Error contract	Standard envelope with `code`, `message`, `details`, `trace_id`
Traceability	`X-Correlation-Id` echoed (or generated as UUID v4) and mirrored in `X-Request-Id`
Protection	IP-based rate limiting (token bucket): 50 requests / 60 s → HTTP 429
Currency	Only `986` (BRL) is supported; defaults to `986` when omitted

Environments

Environment	Base URL	Description
Local	`http://localhost:8080/sale-cancellation`	Local development
Development	`https://sales-data-ms-wlb-api-des.apps.ocp-dev.getnet.com.br/sale-cancellation`	Development environment (DES)
Staging	`https://sales-data-ms-wlb-api-hti.apps.ocp-hml.getnet.com.br/sale-cancellation`	Testing/homologation (HML)

API Reference (OpenAPI JSON): {base-url}/v3/api-docs
Swagger UI: {base-url}/swagger-ui/index.html

API Endpoints

Method	Path	Operation	Description
`POST`	`/v1/cancellations`	`cancel`	Requests a sale cancellation
`GET`	`/v1/cancellations?branch=&client_key=`	`queryByBranchAndClientKey`	Queries cancellations by branch and client key
`GET`	`/v1/cancellations/{protocol}`	`queryByProtocol`	Queries a cancellation by protocol

Request a Cancellation — `POST /v1/cancellations`

Requests the cancellation of an original sale. Returns the tracking protocol when accepted.

Attribute	Value
Method	`POST`
Operation	`cancel`
Category	Cancellation
Content-Type	`application/json`
Success	`202 Accepted`

Pre-conditions: the original transaction must exist and must not have been cancelled before.

Request parameters (body — JSON):

Field	Type	Required	Description
`branch`	String	Yes	Merchant branch code. Numeric, up to 15 digits.
`terminal`	String	Yes	POS terminal identifier. Alphanumeric, up to 8 characters.
`authorization`	String	Yes	Authorization code of the original transaction. Numeric, up to 6 digits.
`date`	String	Yes	Original transaction date (`yyyy-MM-dd`). Cannot be in the future.
`modality`	String	Yes	`V` = Cash (Vista), `P` = Installment (Parcelado).
`amount`	Number	Yes	Original transaction amount in BRL. Must be greater than zero.
`currency_code`	String	No	ISO 4217 code. Defaults to `986` (BRL); any other value is rejected.
`inst_num`	Integer	Yes	Number of installments. Use `1` for cash transactions.
`nsu`	String	Yes	NSU of the original transaction. Numeric, up to 9 digits.
`cancel_amount`	Number	Yes	Amount to cancel in BRL. Total or partial.
`client_key`	String	No	Unique client key. Alphanumeric, up to 32 characters.

Responses: 202 Accepted · 400 · 401 · 403 · 404 · 409 · 422 · 429 · 500 · 502 · 503 · 504

Response body (202):

json

{
  "code": "00",
  "message": "SOLICITACAO RECEBIDA COM SUCESSO",
  "protocol": "20260603000123456"
}

json

{
  "code": "00",
  "message": "SOLICITACAO RECEBIDA COM SUCESSO",
  "protocol": "20260603000123456"
}

Query by Branch and Client Key — `GET /v1/cancellations`

Parameter	In	Required	Description
`branch`	query	Yes	Merchant branch code. Numeric, up to 15 digits.
`client_key`	query	Yes	Client key. Alphanumeric, up to 32 characters.
`X-Correlation-Id`	header	No	Correlation identifier; echoed or generated by the server.

Query by Protocol — `GET /v1/cancellations/{protocol}`

Parameter	In	Required	Description
`protocol`	path	Yes	Cancellation protocol number. Numeric, exactly 17 digits.
`X-Correlation-Id`	header	No	Correlation identifier; echoed or generated by the server.

Response body (200):

json

{
  "code": "00",
  "message": "Operacao efetuada com sucesso",
  "processing_status": {
    "code": "000",
    "message": "REALIZADO"
  },
  "data": {
    "protocol": "20260603000123456",
    "client_key": "a1b2c3d4e5f6a7b8c9d0e1f2a",
    "branch": "55228091",
    "terminal": "ED315536",
    "authorization": "263250",
    "date": "2026-06-05",
    "modality": "V",
    "amount": 699.99,
    "currency_code": "986",
    "inst_num": 1,
    "nsu": "155098740",
    "cancel_amount": 699.99
  }
}

json

{
  "code": "00",
  "message": "Operacao efetuada com sucesso",
  "processing_status": {
    "code": "000",
    "message": "REALIZADO"
  },
  "data": {
    "protocol": "20260603000123456",
    "client_key": "a1b2c3d4e5f6a7b8c9d0e1f2a",
    "branch": "55228091",
    "terminal": "ED315536",
    "authorization": "263250",
    "date": "2026-06-05",
    "modality": "V",
    "amount": 699.99,
    "currency_code": "986",
    "inst_num": 1,
    "nsu": "155098740",
    "cancel_amount": 699.99
  }
}

processing_status.code = "000" means the cancellation was completed successfully. Any other code indicates a rejection or a pending state (e.g. 100 = in progress, 074 = cancellation authorization denied) and may require a new cancellation request.

Schemas

CancellationResponse (POST)

Field	Type	Required	Description
`code`	String	Yes	Backend return code. `000` = accepted.
`message`	String	Yes	Descriptive result message returned by the backend.
`protocol`	String	No	Tracking protocol (17 digits). Present only on acceptance.

CancellationQueryResponse (GET)

Field	Type	Required	Description
`code`	String	Yes	Query return code. `00` = query executed successfully.
`message`	String	Yes	Descriptive message of the query result.
`processing_status`	ProcessingStatus	No	Detailed cancellation processing status. Present on success.
`data`	CancellationData	No	Cancellation transaction data. Present when a record is found.

ProcessingStatus

Field	Type	Required	Description
`code`	String	Yes	Processing status code (`000` = completed, `100` = in progress…).
`message`	String	Yes	Textual status description (e.g. `REALIZADO`).

CancellationData

Field	Type	Description
`protocol`	String	Cancellation protocol number (17 digits).
`client_key`	String	Client key (up to 32 alphanumeric characters).
`branch`	String	Merchant branch code (up to 15 digits).
`terminal`	String	POS terminal identifier (up to 8 characters).
`authorization`	String	Authorization code of the original transaction.
`date`	String	Original transaction date (`yyyy-MM-dd`).
`modality`	String	`V` = Cash, `P` = Installment.
`amount`	Number	Original transaction amount in BRL.
`currency_code`	String	ISO 4217 currency code (`986`).
`inst_num`	Integer	Number of installments.
`nsu`	String	NSU of the original transaction.
`cancel_amount`	Number	Cancelled amount in BRL (may be partial).

ErrorResponse

Field	Type	Required	Description
`code`	String	Yes	HTTP error code as string (e.g. `400`, `404`, `422`).
`message`	String	Yes	Human-readable error message.
`details`	String[]	No	List of individual validation or business failures.
`trace_id`	String	No	Trace identifier (UUID v4), same value as `X-Correlation-Id`.

Authentication Flow

Authentication is not performed by this microservice: the API Gateway / Ingress validates the Bearer token and forwards only authenticated requests.

Obtain an access_token from the OAuth2 API (client_credentials flow).
Call the cancellation endpoints with Authorization: Bearer <access_token>.
When the token expires → request a new token and retry.

Traceability Headers

Header	Direction	Description
`X-Correlation-Id`	request/response	Client value is echoed when non-blank; otherwise the server generates a UUID v4.
`X-Request-Id`	response	Always carries the same value as `X-Correlation-Id` (compatibility).

Error Handling

Errors follow the standard envelope (code, message, details, trace_id). Legacy SOAP business codes are translated into HTTP status codes (De/Para mapping).

HTTP Status	Meaning
`400 Bad Request`	Invalid payload, query or path parameters; backend validation error
`401 Unauthorized`	Authentication with the backend failed
`403 Forbidden`	Access denied by the backend
`404 Not Found`	Original transaction / cancellation not found
`409 Conflict`	Inconsistent state (e.g. transaction already cancelled)
`422 Unprocessable Entity`	Business rule prevented the processing
`429 Too Many Requests`	Rate limit exceeded for the client IP
`500 Internal Server Error`	Unexpected internal error or unmapped backend code
`502 Bad Gateway`	Failure communicating with the SOAP backend
`503 Service Unavailable`	Backend temporarily unavailable
`504 Gateway Timeout`	Timeout waiting for the backend response

Error body example:

json

{
  "code": "400",
  "message": "Dados da requisição inválidos. currency_code: deve ser '986'",
  "details": ["currency_code: deve ser '986'"],
  "trace_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

json

{
  "code": "400",
  "message": "Dados da requisição inválidos. currency_code: deve ser '986'",
  "details": ["currency_code: deve ser '986'"],
  "trace_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Usage Example

Request a cancellation (cURL):

bash

curl -X POST "https://sales-data-ms-wlb-api-hti.apps.ocp-hml.getnet.com.br/sale-cancellation/v1/cancellations" \
  -H "Authorization: Bearer {ACCESS-TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-Id: f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -d '{
    "branch": "55228091",
    "terminal": "ED315536",
    "authorization": "263250",
    "date": "2026-06-05",
    "modality": "V",
    "amount": 625.00,
    "currency_code": "986",
    "inst_num": 1,
    "nsu": "155098740",
    "cancel_amount": 625.00,
    "client_key": "34567895673456782345678934567843"
  }'

bash

curl -X POST "https://sales-data-ms-wlb-api-hti.apps.ocp-hml.getnet.com.br/sale-cancellation/v1/cancellations" \
  -H "Authorization: Bearer {ACCESS-TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-Id: f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -d '{
    "branch": "55228091",
    "terminal": "ED315536",
    "authorization": "263250",
    "date": "2026-06-05",
    "modality": "V",
    "amount": 625.00,
    "currency_code": "986",
    "inst_num": 1,
    "nsu": "155098740",
    "cancel_amount": 625.00,
    "client_key": "34567895673456782345678934567843"
  }'

Track the cancellation by protocol:

bash

curl "https://sales-data-ms-wlb-api-hti.apps.ocp-hml.getnet.com.br/sale-cancellation/v1/cancellations/20260603000123456" \
  -H "Authorization: Bearer {ACCESS-TOKEN}"

bash

curl "https://sales-data-ms-wlb-api-hti.apps.ocp-hml.getnet.com.br/sale-cancellation/v1/cancellations/20260603000123456" \
  -H "Authorization: Bearer {ACCESS-TOKEN}"

Best Practices

Store the protocol — it is the only key to track the cancellation lifecycle; persist it right after the 202.
Do not retry blindly — POST is not idempotent; on timeout, query by branch/client_key before requesting again.
Check processing_status.code — HTTP 200 only means the query succeeded; the cancellation outcome is in processing_status.
Send X-Correlation-Id — propagate your own identifier to correlate logs during support requests.
Respect the rate limit — 50 requests per 60 s per IP; handle 429 with backoff.
Validate before sending — modality ∈ {V,P}, currency_code = 986, date not in the future, amounts greater than zero.

Getnet MPS White Label — Sale Cancellation API v1.0.0

En esta página

sale-cancellation

sale-cancellation

Overview

Architecture

Key Design Decisions

Environments

API Endpoints

Request a Cancellation — POST /v1/cancellations

Query by Branch and Client Key — GET /v1/cancellations

Query by Protocol — GET /v1/cancellations/{protocol}

Schemas

CancellationResponse (POST)

CancellationQueryResponse (GET)

ProcessingStatus

CancellationData

ErrorResponse

Authentication Flow

Traceability Headers

Error Handling

Usage Example

Best Practices

Request a Cancellation — `POST /v1/cancellations`

Query by Branch and Client Key — `GET /v1/cancellations`

Query by Protocol — `GET /v1/cancellations/{protocol}`