{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-@l10n/pt/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Recompensas e Resgates","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"recompensas-e-resgates","__idx":0},"children":["Recompensas e Resgates"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["O fluxo tem dois lados. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Gera"]}," recompensas anexando um bloco ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward"]}," a um ou mais splits dentro de uma captura. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Resgata-as"]}," mais tarde enviando um bloco ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"como-funcionam-as-recompensas","__idx":1},"children":["Como funcionam as recompensas"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A conta de recompensas é ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cada entrada numa conta de recompensas está associada a um cliente. Quando um pagamento inclui um split com um bloco ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward"]},", o cliente identificado no topo do pedido é creditado pelo valor em ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward.value"]},". Esse crédito passa a fazer parte do saldo disponível do cliente até ser resgatado ou expirar."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["O resgate funciona no sentido inverso: numa captura posterior para o mesmo cliente, envia um bloco ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward_redemption"]}," e o valor correspondente é debitado do saldo e aplicado ao pagamento."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"gerar-recompensas-numa-captura","__idx":2},"children":["Gerar recompensas numa captura"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Anexe um bloco ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward"]}," a qualquer split dentro do array ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["capture.splits[]"]},". O cliente identificado no topo do pedido é o que recebe o crédito."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST 'https://api.test.easypay.pt/2.0/single' \\\n  -H 'AccountId: SEU_ACCOUNT_ID' \\\n  -H 'ApiKey: SUA_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"type\": \"sale\",\n    \"method\": \"cc\",\n    \"value\": 50.00,\n    \"currency\": \"EUR\",\n    \"customer\": {\n      \"id\": \"649e88cf-0b78-4c36-8f99-33f5ebb812a1\",\n      \"name\": \"John Doe\",\n      \"email\": \"john.doe@example.com\"\n    },\n    \"capture\": {\n      \"descriptive\": \"Order #1029\",\n      \"splits\": [\n        {\n          \"split_descriptive\": \"Marketplace seller\",\n          \"account\": {\n            \"id\": \"7e697e0c-c2bf-422a-9535-ab0b750bb832\"\n          },\n          \"value\": 50.00,\n          \"reward\": {\n            \"account\": {\n              \"id\": \"458b2fc4-3092-4de3-abd4-fe1600c09420\"\n            },\n            \"value\": 2.50,\n            \"expiration_date\": \"2027-04-02\"\n          }\n        }\n      ]\n    }\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["O que cada campo de ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward"]}," faz:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"ler-o-saldo-de-um-cliente","__idx":3},"children":["Ler o saldo de um cliente"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Dois endpoints expõem o que um cliente tem."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /customer/{id}"]}," devolve o cliente juntamente com um array ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"id\": \"649e88cf-0b78-4c36-8f99-33f5ebb812a1\",\n    \"name\": \"John Doe\",\n    \"email\": \"john.doe@example.com\",\n    \"reward_balances\": [\n        {\n            \"account_id\": \"458b2fc4-3092-4de3-abd4-fe1600c09420\",\n            \"available_balance\": 12.5\n        }\n    ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /customer/{id}/rewards"]}," lista todos os movimentos individuais no histórico cada ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REWARD"]}," ganho e cada ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REDEMPTION"]}," gasto do mais recente para o mais antigo. Suporta filtragem por conta, tipo, expiração e data de criação."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl 'https://api.test.easypay.pt/2.0/customer/649e88cf-0b78-4c36-8f99-33f5ebb812a1/rewards?type[]=REWARD&account_id[]=458b2fc4-3092-4de3-abd4-fe1600c09420' \\\n  -H 'AccountId: SEU_ACCOUNT_ID' \\\n  -H 'ApiKey: SUA_API_KEY'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"metadata\": { \"next_cursor\": null, \"count\": 2 },\n    \"data\": [\n        {\n            \"id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n            \"account_id\": \"458b2fc4-3092-4de3-abd4-fe1600c09420\",\n            \"type\": \"REWARD\",\n            \"amount\": 10.0,\n            \"expiration_date\": \"2027-01-15\",\n            \"capture\": { \"id\": \"c6056234-a3f9-42de-b944-3ed793fcb6bb\" },\n            \"created_at\": \"2026-01-15T10:30:00Z\"\n        },\n        {\n            \"id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n            \"account_id\": \"458b2fc4-3092-4de3-abd4-fe1600c09420\",\n            \"type\": \"REWARD\",\n            \"amount\": 2.5,\n            \"expiration_date\": \"2027-04-02\",\n            \"capture\": { \"id\": \"b6f53027-0478-4728-9269-8bcc0f8088ea\" },\n            \"created_at\": \"2026-04-02T09:12:00Z\"\n        }\n    ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resgatar-recompensas-numa-captura","__idx":4},"children":["Resgatar recompensas numa captura"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Para gastar créditos, adicione um bloco ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward_redemption"]}," ao nível superior do pedido em ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /single"]}," (quando paga num único passo) ou em ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /capture/{id}"]}," (quando captura uma autorização anterior)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["O resgate é ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["por conta de recompensas"]},": um bloco ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Resgate total"]}," aplicar todo o saldo disponível:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"type\": \"sale\",\n    \"method\": \"CC\",\n    \"value\": 50.0,\n    \"customer\": {\n        \"id\": \"649e88cf-0b78-4c36-8f99-33f5ebb812a1\"\n    },\n    \"reward_redemption\": {\n        \"account\": {\n            \"id\": \"458b2fc4-3092-4de3-abd4-fe1600c09420\"\n        },\n        \"value\": 50.0\n    }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Resgate parcial"]}," aplicar apenas parte do saldo:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"type\": \"sale\",\n    \"method\": \"CC\",\n    \"value\": 50.0,\n    \"customer\": {\n        \"id\": \"649e88cf-0b78-4c36-8f99-33f5ebb812a1\"\n    },\n    \"reward_redemption\": {\n        \"account\": {\n            \"id\": \"458b2fc4-3092-4de3-abd4-fe1600c09420\"\n        },\n        \"value\": 5.0\n    }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Em ambos os casos o cliente é cobrado por ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value − reward_redemption.value"]}," através do método de pagamento escolhido. O valor resgatado é debitado do saldo imediatamente e aparece como uma entrada ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REDEMPTION"]}," no histórico."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"ganhar-e-gastar-no-mesmo-pedido","__idx":5},"children":["Ganhar e gastar no mesmo pedido"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Um único pagamento pode fazer ambos. O bloco ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward_redemption"]}," fica no topo do pedido e reduz o valor que o cliente paga; os blocos ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["O exemplo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Sale with Splits and Reward Redemption"]}," em ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi#tag/Single-Payment"},"children":["POST /single"]}," mostra a forma combinada de ponta a ponta."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"próximos-passos","__idx":6},"children":["Próximos Passos"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi#tag/Customer"},"children":["Endpoints de Customer"]},": referência de saldo e histórico"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi#tag/Single-Payment"},"children":["Single Payment"]},": ganhar e resgatar num único passo"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi#tag/Captures"},"children":["Captures"]},": ganhar e resgatar numa captura separada"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/guides/authorizations-captures"},"children":["Autorizações e Capturas"]},": quando separar autorização e captura"]}]}]},"headings":[{"value":"Recompensas e Resgates","id":"recompensas-e-resgates","depth":1},{"value":"Como funcionam as recompensas","id":"como-funcionam-as-recompensas","depth":2},{"value":"Gerar recompensas numa captura","id":"gerar-recompensas-numa-captura","depth":2},{"value":"Ler o saldo de um cliente","id":"ler-o-saldo-de-um-cliente","depth":2},{"value":"Resgatar recompensas numa captura","id":"resgatar-recompensas-numa-captura","depth":2},{"value":"Ganhar e gastar no mesmo pedido","id":"ganhar-e-gastar-no-mesmo-pedido","depth":2},{"value":"Próximos Passos","id":"próximos-passos","depth":2}],"frontmatter":{"seo":{"title":"Recompensas e Resgates"}},"lastModified":"2026-05-28T13:31:47.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/pt/docs/guides/rewards-and-redemptions","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}