Skip to main content
Os endpoints de cashback permitem validar a disponibilidade, aplicar e remover cashback durante o processo de checkout.

​
Status de Autenticação dos Endpoints

EndpointStatus
GET /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}Autenticado
POST /pub/widget/rewards/checkout/cashbackAutenticado
POST /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}/redeemAutenticado
POST /pub/widget/rewards/checkout/cashback/redeemAutenticado
GET /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}/redeemedAutenticado
POST /pub/widget/rewards/checkout/cashback/redeemedAutenticado
POST /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}/refreshAutenticado
POST /pub/widget/rewards/checkout/cashback/refreshAutenticado
DELETE /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}/redeemAutenticado
POST /pub/widget/rewards/checkout/cashback/redeem/removeAutenticado

​
Validar Cashback

Verifica se o cliente pode utilizar cashback e qual o valor disponível para a compra atual. Deve ser chamada antes de aplicar o cashback.

​
Requisição (GET)

GET /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}

​
Requisição (POST)

POST /pub/widget/rewards/checkout/cashback Headers
​
X-Bq-Tenant
string
required
Identificador público da loja.
​
X-Bq-SecureToken
string
required
Token do usuário obtido no login seguro.
Path Parameters (GET)
​
ORDER_FORM_ID
string
required
Identificador do carrinho.
Body (POST)
​
CheckoutId
string
required
Identificador do carrinho (order_form_id).
​
Total
number
Valor total do carrinho (opcional, mas recomendado para cálculos mais precisos).

​
Exemplo (GET)

curl -X GET "https://api.bonifiq.com.br/pub/widget/rewards/checkout/cashback/abc123" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

​
Exemplo (POST)

curl -X POST "https://api.bonifiq.com.br/pub/widget/rewards/checkout/cashback" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "CheckoutId": "<order_form_id>",
    "Total": 150.00
  }'

​
Resposta

​
CashbackBalance
number
Saldo total de cashback do cliente.
​
UsableCashback
number
Valor de cashback que pode ser utilizado nesta compra (considerando regras e limites).
​
MaxUsableCashback
number
Valor máximo de cashback permitido para esta compra.
​
CashbackRules
string
Regras de utilização do cashback (texto para exibição ao cliente).
​
CanUse
boolean
Indica se o cliente pode usar cashback nesta compra.
​
CashbackWillReceiveText
string
Texto informando quanto cashback o cliente receberá nesta compra.
​
RequiredToAddMoreText
string
Texto informando quanto falta para usar o cashback (se aplicável).
​
IsCashbackAvailable
boolean
Indica se o cashback está disponível para uso.
​
RemainingToTotalCashback
number
Valor restante para usar todo o saldo de cashback.
​
RemainingToUse
number
Valor restante para atingir o mínimo necessário para usar cashback.
​
hasProductsIneligibleForCashback
boolean
Indica se há produtos no carrinho que não são elegíveis para cashback.
​
MinValueToUse
number
Valor mínimo do carrinho para usar cashback.
{
  "CashbackBalance": 50.00,
  "UsableCashback": 25.00,
  "MaxUsableCashback": 50.00,
  "CashbackRules": "Pague até 50% da compra com cashback.",
  "CanUse": true,
  "CashbackWillReceiveText": "Você receberá R$ 5,00 de cashback nesta compra",
  "RequiredToAddMoreText": null,
  "IsCashbackAvailable": true,
  "RemainingToTotalCashback": 0,
  "RemainingToUse": 0,
  "hasProductsIneligibleForCashback": false,
  "MinValueToUse": 20.00
}

​
Aplicar Cashback

Aplica o cashback ao carrinho do cliente.

​
Requisição (com ORDER_FORM_ID na rota)

POST /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}/redeem

​
Requisição (com CheckoutId no body)

POST /pub/widget/rewards/checkout/cashback/redeem Headers
​
X-Bq-Tenant
string
required
Identificador público da loja.
​
X-Bq-SecureToken
string
required
Token do usuário obtido no login seguro.
Path Parameters (primeira opção)
​
ORDER_FORM_ID
string
required
Identificador do carrinho.
Body (primeira opção)
​
CashbackValue
number
required
Valor do cashback a ser resgatado.
​
Token
string
Token de validação (se aplicável).
​
RedeemOrigin
integer
Origem do resgate. Use 3 para checkout mobile.
​
Total
number
Valor do carrinho (sem descontos ou frete).
Body (segunda opção - CheckoutId no body)
​
CheckoutId
string
required
Identificador do carrinho (order_form_id).
​
CashbackValue
number
required
Valor do cashback a ser resgatado.
​
Token
string
Token de validação (se aplicável).
​
RedeemOrigin
integer
Origem do resgate. Use 3 para checkout mobile.
​
Total
number
Valor do carrinho (sem descontos ou frete).

​
Exemplo (com ORDER_FORM_ID na rota)

curl -X POST "https://api.bonifiq.com.br/pub/widget/rewards/checkout/cashback/abc123/redeem" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "CashbackValue": 25.00,
    "RedeemOrigin": 3,
    "Total": 150.00
  }'

​
Exemplo (com CheckoutId no body)

curl -X POST "https://api.bonifiq.com.br/pub/widget/rewards/checkout/cashback/redeem" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "CheckoutId": "<order_form_id>",
    "CashbackValue": 25.00,
    "RedeemOrigin": 3,
    "Total": 150.00
  }'

​
Resposta

​
AppliedCashback
number
Valor de cashback efetivamente aplicado.
​
Success
boolean
Indica se a operação foi bem-sucedida.
​
CustomerMessage
string
Mensagem para exibir ao cliente.
​
CashbackRules
string
Regras de utilização do cashback.
​
InternalMessage
string
Mensagem interna (para debugging).
​
CouponCode
string
Código do cupom gerado (se aplicável).
​
Token
string
Token de validação para operações subsequentes.
{
  "AppliedCashback": 25.00,
  "Success": true,
  "CustomerMessage": "Cashback resgatado com sucesso.",
  "CashbackRules": "Pague até 50% da compra com cashback.",
  "InternalMessage": null,
  "CouponCode": null,
  "Token": "xyz789"
}

​
Valores de RedeemOrigin

ValorDescrição
0Widget
1Checkout Web
2Landing Page
3Checkout Mobile
4API

​
Consultar Cashback Aplicado

Verifica se há cashback aplicado ao carrinho atual.

​
Requisição (GET)

GET /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}/redeemed

​
Requisição (POST)

POST /pub/widget/rewards/checkout/cashback/redeemed Headers
​
X-Bq-Tenant
string
required
Identificador público da loja.
​
X-Bq-SecureToken
string
required
Token do usuário obtido no login seguro.
Path Parameters (GET)
​
ORDER_FORM_ID
string
required
Identificador do carrinho.
Body (POST)
​
CheckoutId
string
required
Identificador do carrinho (order_form_id).

​
Exemplo (GET)

curl -X GET "https://api.bonifiq.com.br/pub/widget/rewards/checkout/cashback/abc123/redeemed" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

​
Resposta

{
  "AppliedCashback": 25.00,
  "Success": true,
  "CustomerMessage": "Você está utilizando R$ 25,00 de cashback.",
  "CashbackRules": "Pague até 50% da compra com cashback.",
  "InternalMessage": null,
  "CouponCode": null,
  "Token": "xyz789"
}

​
Atualizar Cashback (Refresh)

Recalcula o cashback aplicado quando o carrinho é alterado (itens adicionados/removidos). Deve ser chamado sempre que houver mudança no carrinho.

​
Requisição (com ORDER_FORM_ID na rota)

POST /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}/refresh

​
Requisição (com CheckoutId no body)

POST /pub/widget/rewards/checkout/cashback/refresh Headers
​
X-Bq-Tenant
string
required
Identificador público da loja.
​
X-Bq-SecureToken
string
required
Token do usuário obtido no login seguro.
Path Parameters (primeira opção)
​
ORDER_FORM_ID
string
required
Identificador do carrinho.
Body (segunda opção)
​
CheckoutId
string
required
Identificador do carrinho (order_form_id).

​
Exemplo

curl -X POST "https://api.bonifiq.com.br/pub/widget/rewards/checkout/cashback/refresh" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "CheckoutId": "<order_form_id>"
  }'

​
Resposta

​
CashbackRemoved
boolean
Indica se o cashback foi removido (por exemplo, se o carrinho ficou abaixo do mínimo).
​
CustomerMessage
string
Mensagem para exibir ao cliente.
{
  "CashbackRemoved": false,
  "CustomerMessage": "Cashback atualizado com sucesso."
}
Se CashbackRemoved for true, significa que o cashback aplicado anteriormente foi removido automaticamente porque o carrinho não atende mais aos requisitos mínimos. Neste caso, exiba a mensagem ao cliente.

​
Remover Cashback

Remove o cashback aplicado ao carrinho e estorna o valor de volta à carteira do cliente.

​
Requisição (DELETE)

DELETE /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}/redeem

​
Requisição (POST)

POST /pub/widget/rewards/checkout/cashback/redeem/remove Headers
​
X-Bq-Tenant
string
required
Identificador público da loja.
​
X-Bq-SecureToken
string
required
Token do usuário obtido no login seguro.
Path Parameters (DELETE)
​
ORDER_FORM_ID
string
required
Identificador do carrinho.
Body (POST)
​
CheckoutId
string
required
Identificador do carrinho (order_form_id).
​
Total
number
Valor do carrinho (opcional).

​
Exemplo (DELETE)

curl -X DELETE "https://api.bonifiq.com.br/pub/widget/rewards/checkout/cashback/abc123/redeem" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

​
Exemplo (POST)

curl -X POST "https://api.bonifiq.com.br/pub/widget/rewards/checkout/cashback/redeem/remove" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "CheckoutId": "<order_form_id>",
    "Total": 150.00
  }'

​
Resposta

​
Success
boolean
Indica se a operação foi bem-sucedida.
​
CustomerMessage
string
Mensagem para exibir ao cliente.
{
  "Success": true,
  "CustomerMessage": "O cashback foi removido com sucesso"
}
Diferentemente da remoção de recompensas, a remoção de cashback estorna automaticamente o valor de volta para a carteira do cliente.