# Recompensas e Resgates

As recompensas permitem-lhe transformar parte de um pagamento em créditos que o cliente pode gastar num pagamento posterior. Os créditos ficam numa conta de recompensas associada ao seu marketplace e seguem o cliente que os ganhou apenas esse cliente os pode resgatar, e os créditos expiram após um período definido (12 meses por defeito).

O fluxo tem dois lados. **Gera** recompensas anexando um bloco `reward` a um ou mais splits dentro de uma captura. **Resgata-as** mais tarde enviando um bloco `reward_redemption` na captura seguinte. Entre essas duas operações, pode consultar o que cada cliente tem disponível através dos endpoints de Customer.

## Como funcionam as recompensas

A conta de recompensas é **por marketplace**. É provisionada no onboarding não existe API para a criar e é referenciada pelo seu UUID em cada geração e resgate de recompensa.

Cada entrada numa conta de recompensas está associada a um cliente. Quando um pagamento inclui um split com um bloco `reward`, o cliente identificado no topo do pedido é creditado pelo valor em `reward.value`. Esse crédito passa a fazer parte do saldo disponível do cliente até ser resgatado ou expirar.

O resgate funciona no sentido inverso: numa captura posterior para o mesmo cliente, envia um bloco `reward_redemption` e o valor correspondente é debitado do saldo e aplicado ao pagamento.

## Gerar recompensas numa captura

Anexe um bloco `reward` a qualquer split dentro do array `capture.splits[]`. O cliente identificado no topo do pedido é o que recebe o crédito.


```bash
curl -X POST 'https://api.test.easypay.pt/2.0/single' \
  -H 'AccountId: SEU_ACCOUNT_ID' \
  -H 'ApiKey: SUA_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "sale",
    "method": "cc",
    "value": 50.00,
    "currency": "EUR",
    "customer": {
      "id": "649e88cf-0b78-4c36-8f99-33f5ebb812a1",
      "name": "John Doe",
      "email": "john.doe@example.com"
    },
    "capture": {
      "descriptive": "Order #1029",
      "splits": [
        {
          "split_descriptive": "Marketplace seller",
          "account": {
            "id": "7e697e0c-c2bf-422a-9535-ab0b750bb832"
          },
          "value": 50.00,
          "reward": {
            "account": {
              "id": "458b2fc4-3092-4de3-abd4-fe1600c09420"
            },
            "value": 2.50,
            "expiration_date": "2027-04-02"
          }
        }
      ]
    }
  }'
```

O que cada campo de `reward` faz:

- `reward.account.id`: a conta de recompensas do marketplace que detém o crédito. Use o mesmo UUID em todas as recompensas que pretende agregar no mesmo saldo.
- `reward.value`: quanto desse split se transforma em crédito. Não altera o que o cliente paga no momento; é um valor que o marketplace contribui a partir do valor do split.
- `reward.expiration_date`: opcional. Por defeito são 12 meses a partir da data da transação. Depois desta data o crédito já não pode ser resgatado.


## Ler o saldo de um cliente

Dois endpoints expõem o que um cliente tem.

`GET /customer/{id}` devolve o cliente juntamente com um array `reward_balances` com uma entrada por cada conta de recompensas em que tem créditos. Use este quando quiser um total rápido antes de apresentar uma opção "Usar as suas recompensas" no checkout.


```json
{
    "id": "649e88cf-0b78-4c36-8f99-33f5ebb812a1",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "reward_balances": [
        {
            "account_id": "458b2fc4-3092-4de3-abd4-fe1600c09420",
            "available_balance": 12.5
        }
    ]
}
```

`GET /customer/{id}/rewards` lista todos os movimentos individuais no histórico cada `REWARD` ganho e cada `REDEMPTION` gasto do mais recente para o mais antigo. Suporta filtragem por conta, tipo, expiração e data de criação.


```bash
curl 'https://api.test.easypay.pt/2.0/customer/649e88cf-0b78-4c36-8f99-33f5ebb812a1/rewards?type[]=REWARD&account_id[]=458b2fc4-3092-4de3-abd4-fe1600c09420' \
  -H 'AccountId: SEU_ACCOUNT_ID' \
  -H 'ApiKey: SUA_API_KEY'
```


```json
{
    "metadata": { "next_cursor": null, "count": 2 },
    "data": [
        {
            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "account_id": "458b2fc4-3092-4de3-abd4-fe1600c09420",
            "type": "REWARD",
            "amount": 10.0,
            "expiration_date": "2027-01-15",
            "capture": { "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb" },
            "created_at": "2026-01-15T10:30:00Z"
        },
        {
            "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "account_id": "458b2fc4-3092-4de3-abd4-fe1600c09420",
            "type": "REWARD",
            "amount": 2.5,
            "expiration_date": "2027-04-02",
            "capture": { "id": "b6f53027-0478-4728-9269-8bcc0f8088ea" },
            "created_at": "2026-04-02T09:12:00Z"
        }
    ]
}
```

Use o histórico quando precisar de um registo de auditoria por movimento por exemplo, quando um cliente pergunta de onde veio um determinado crédito, ou quando quer avisar sobre créditos prestes a expirar.

## Resgatar recompensas numa captura

Para gastar créditos, adicione um bloco `reward_redemption` ao nível superior do pedido em `POST /single` (quando paga num único passo) ou em `POST /capture/{id}` (quando captura uma autorização anterior).

O resgate é **por conta de recompensas**: um bloco `reward_redemption` aponta para um UUID de conta. O valor resgatado não pode exceder o saldo disponível nessa conta, nem o valor do próprio pagamento.

**Resgate total** aplicar todo o saldo disponível:


```json
{
    "type": "sale",
    "method": "CC",
    "value": 50.0,
    "customer": {
        "id": "649e88cf-0b78-4c36-8f99-33f5ebb812a1"
    },
    "reward_redemption": {
        "account": {
            "id": "458b2fc4-3092-4de3-abd4-fe1600c09420"
        },
        "value": 50.0
    }
}
```

**Resgate parcial** aplicar apenas parte do saldo:


```json
{
    "type": "sale",
    "method": "CC",
    "value": 50.0,
    "customer": {
        "id": "649e88cf-0b78-4c36-8f99-33f5ebb812a1"
    },
    "reward_redemption": {
        "account": {
            "id": "458b2fc4-3092-4de3-abd4-fe1600c09420"
        },
        "value": 5.0
    }
}
```

Em ambos os casos o cliente é cobrado por `value − reward_redemption.value` através do método de pagamento escolhido. O valor resgatado é debitado do saldo imediatamente e aparece como uma entrada `REDEMPTION` no histórico.

## Ganhar e gastar no mesmo pedido

Um único pagamento pode fazer ambos. O bloco `reward_redemption` fica no topo do pedido e reduz o valor que o cliente paga; os blocos `capture.splits[].reward` creditam o cliente com base nos splits. Não interagem entre si pode resgatar €10 de um saldo anterior e ganhar €5 de novos créditos na mesma captura.

O exemplo `Sale with Splits and Reward Redemption` em [POST /single](/openapi#tag/Single-Payment) mostra a forma combinada de ponta a ponta.

## Próximos Passos

- [Endpoints de Customer](/openapi#tag/Customer): referência de saldo e histórico
- [Single Payment](/openapi#tag/Single-Payment): ganhar e resgatar num único passo
- [Captures](/openapi#tag/Captures): ganhar e resgatar numa captura separada
- [Autorizações e Capturas](/docs/guides/authorizations-captures): quando separar autorização e captura