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.
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.
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.
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.
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.
{
"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.
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'{
"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.
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:
{
"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:
{
"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.
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 mostra a forma combinada de ponta a ponta.
- Endpoints de Customer: referência de saldo e histórico
- Single Payment: ganhar e resgatar num único passo
- Captures: ganhar e resgatar numa captura separada
- Autorizações e Capturas: quando separar autorização e captura