Sign in

v4

OpenAPI 3.0.02026-07-31811,0021.1 MB
Checkout

Redeems cashback for a checkout

This endpoint allows you to apply cashback discount to a checkout/cart.

Input Parameters

  • CustomerId (required): The customer identifier (email or document/CPF)
  • CheckoutId (required): The checkout/cart ID from the e-commerce platform
  • CashbackValue (optional): The specific amount of cashback to apply. If not provided, the maximum available cashback will be used.
  • Total (optional): The checkout total value. Used for validation.
  • OriginalKey (optional): A unique key to identify this redemption (for idempotency)

Response

On success, returns the reward information including:

  • RewardId: The unique ID for this reward
  • ExternalCode: Code to be used when sending orders to BonifiQ
  • OriginalKey: The key identifying this redemption
  • Point: Information about the points used
  • Coupon: The coupon information (if generated)

Important Notes

  • If the customer already has cashback applied in another checkout (without an order), it will be automatically refunded.
  • The cashback value cannot exceed the checkout total or the customer's available cashback balance.
post/v1/pvt/Checkout/redeem

Request body

CustomerIdstring

Customer identifier (email or document/CPF)

CheckoutIdstring

The checkout/cart ID from the e-commerce platform

CashbackValuenumber nullable

Optional: The specific amount of cashback to apply. If not provided, the maximum available cashback will be used.

Totalnumber nullable

Optional: The checkout total value. Used for validation.

Tokenstring nullable

Optional: Platform-specific token for the checkout

OriginalKeystring nullable

Optional: A unique key to identify this redemption (for idempotency)

Response

The reward information

ErrorMessagestring nullable

Error message returned when the request fails validation or processing. For warnings and successful responses, consumers should usually inspect Result, Code and Severity first.

ErrorCodeinteger nullable

Legacy numeric error code derived from internal API errors when available. This field is relevant only for error flows that use ApiResponseErrorDescription.

Codestring nullable

Endpoint-specific business code formatted as a two-digit string, such as 03 or 07. This field is available for success, warning and error outcomes.

CodeNamestring nullable

Symbolic enum name associated with Code, such as CheckoutNotFound.

Severity0 | 1 | 2

0 = Success 1 = Warning 2 = Error

HasWarningboolean

Convenience flag that is true when Severity is Warning. Warnings are valid 200 OK business outcomes and should not be handled as transport or validation errors.

HasErrorboolean

Indicates whether the request failed and should be handled as an error response. This flag is reserved for real API errors; warnings must keep this property as false.