# ifthenpay

> ifthenpay é uma fintech portuguesa com mais de 20 anos de experiência a simplificar pagamentos digitais para empresas. Regulada pelo Banco de Portugal (registo n.º 8707), opera em todo o Espaço Económico Europeu (EEE). Cria soluções seguras e inovadoras que ligam o mundo físico ao digital, do e-commerce B2B e B2C à faturação tradicional. Sem mensalidades, mínimos de transações, períodos de fidelização ou contratos de exclusividade.

## Contactos

- **Telefone principal:** +351 256 245 560
- **Linha de apoio:** +351 808 222 777
- **Email de suporte:** suporte@ifthenpay.com
- **Email institucional:** ifthenpay@ifthenpay.com
- **Email anti-fraude:** fraude@ifthenpay.com
- **Helpdesk (tickets):** https://ifthenpay.com/pt-PT/support/
- **Morada:** Rua do FeiraPark, nº50, Edifício Feira Park, 4520-632 São João de Ver, Santa Maria da Feira, Portugal
- **Website:** https://ifthenpay.com
- **GitHub:** https://github.com/ifthenpay

---

## Sobre a ifthenpay

Fintech portuguesa fundada há mais de 20 anos. Regulada pelo Banco de Portugal (registo n.º 8707). Opera em todo o Espaço Económico Europeu. Integra com todos os bancos da área SEPA. Os pagamentos são disponibilizados 24 horas por dia, com notificações imediatas. O utilizador final não paga custos adicionais. Não é necessário introduzir dados bancários online.

Vantagens principais:
- Sem custos para o utilizador final
- Pagamentos 24h/dia com notificações imediatas
- Segurança: sem necessidade de introduzir dados bancários online
- Multicanal: Homebanking, MB Spot, Mobile, POS, MB WAY, agente Payshop ou loja CTT
- Independência bancária: muda de banco sem mudar de POS; integra com todos os bancos SEPA
- Controlo de vendas via app gratuita (Android e iOS)
- Suporte técnico gratuito para todos os clientes

Fluxo geral de funcionamento:
1. **Emissão** — Geração automática de referências via loja online, faturas ou app móvel
2. **Notificação** — Alertas em tempo real após cada pagamento (e-mail ou push)
3. **Transferência** — Montantes transferidos diariamente, deduzidas as comissões
4. **Faturação** — Fatura mensal detalhada dos serviços prestados

---

## Métodos de Pagamento

### Multibanco
Permite gerar referências de pagamento únicas (entidade + referência numérica) por transação. O cliente paga através de ATM, homebanking ou app móvel. Método amplamente utilizado em Portugal.
- **Preço:** 0.20€ + 1.5% por transação
- **Chave necessária:** MB KEY (fornecida pela ifthenpay)

### MB WAY
Solução de pagamento digital móvel integrada na rede Multibanco. O comerciante envia um pedido de pagamento para o número de telemóvel do cliente, que confirma na sua app MB WAY.
- **Preço:** 0.07€ + 0.7% por transação
- **Chave necessária:** MBWAY KEY (fornecida pela ifthenpay)

### Payshop
Pagamento em dinheiro em locais físicos autorizados (quiosques, lojas de conveniência, agentes Payshop). O cliente apresenta a referência gerada no checkout.
- **Preço:** 0.57€ por transação
- **Chave necessária:** PAYSHOP KEY (fornecida pela ifthenpay)

### Cartão de Crédito / Débito
Pagamentos com Visa, Mastercard e outros cartões, online e presencialmente.
- **Preço (EEE):** 0.20€ + 1.5% por transação
- **Chave necessária:** CCARD KEY (fornecida pela ifthenpay)
- Sandbox disponível com cartões de teste

### Google Pay
Carteira digital via NFC com autenticação biométrica para dispositivos Android e iOS.
- **Preço (EEE):** 0.20€ + 1.5% por transação
- **Chave necessária:** GATEWAY KEY + GOOGLE KEY
- Disponível via API Pay by Link & Pinpay

### Apple Pay
Serviço de pagamento seguro para dispositivos Apple (iPhone, iPad, Apple Watch, Mac), via NFC e autenticação biométrica.
- **Preço (EEE):** 0.20€ + 1.5% por transação
- **Chave necessária:** GATEWAY KEY + APPLE KEY
- Disponível via API Pay by Link & Pinpay

### Cofidis Pay
Pagamento em prestações com 0% de juros para o cliente. A ifthenpay não cobra comissão — o financiamento é um acordo de factoring entre a Cofidis e o comerciante. Ideal para aumentar conversão em compras de valor mais elevado.
- **Preço:** 0.00€ (sem comissão da ifthenpay)
- **Chave necessária:** COFIDIS KEY
- Limite mínimo: 60€ | Limite máximo: 1.000€ (por cliente, consultável via API)

### Débitos Diretos
Cobrança automática diretamente da conta bancária do cliente em datas agendadas. Ideal para pagamentos recorrentes (subscrições, utilities, prestações). Requer autorização do cliente (mandato).
- **Preço:** 0.45€ por transação
- **Chave necessária:** DD KEY (fornecida pela ifthenpay)
- Sandbox disponível em `https://services.ifthenpay.com/sandbox/directdebit`

### PIX
Pagamento instantâneo do Banco Central do Brasil. Transações em tempo real, 24/7, via dispositivo móvel. Disponível para comerciantes que operam no mercado brasileiro.
- **Preço (EEE):** 0.20€ + 3.5% por transação (custos cambiais real/euro incluídos)
- **Chave necessária:** PIX KEY (fornecida pela ifthenpay)
- Requer CPF do cliente para cada transação

### TPA — Terminal de Pagamento Automático
Terminais físicos para pagamentos presenciais com cartão, Contactless, MB WAY, Apple Pay e Google Pay.

**TPA Classic:** Contactless, teclado físico, robusto, autónomo, cartão de dados, impressora integrada, MB WAY.
**TPA Smart:** Contactless, ecrã tátil, Wi-Fi, faturação direta*, cartão de dados, impressora integrada, MB WAY.

- **Comissão:** 0.7% por pagamento efetivo (cartão de crédito consumidor EEE)
- **Aluguer:** 12€/mês (+ IVA)
- *Faturação direta não incluída; possibilidade de integração de software de faturação

---

## Soluções / Como Utilizar

### E-commerce
Integração com as principais plataformas de e-commerce (WooCommerce, PrestaShop, Shopify, Magento, etc.) ou plataformas desenvolvidas à medida via API REST.
- [Ver Plugins & Integrações](https://ifthenpay.com/plugins-and-integrations/)

### Documentos / Faturação
Integração em documentos tradicionais como faturas ou orçamentos. A maioria dos softwares de faturação já disponibiliza integração nativa ou pode ser facilmente integrada.

### Backoffice & App Móvel
Através do backoffice web ou da app móvel (Android e iOS) é possível gerar referências Multibanco, fazer pedidos MB WAY e enviá-los a clientes. Permite receber pagamentos digitais mesmo sem loja online.
- [Android (Google Play)](https://play.google.com/store/apps/details?id=com.ifthenpay.app)
- [iOS (App Store)](https://apps.apple.com/us/app/ifthenpay-2025/id6746652970)

### Pay by Link
Envio de um link de pagamento diretamente ao cliente via e-mail, SMS, redes sociais ou qualquer canal de comunicação. O comerciante define o montante e os métodos de pagamento disponíveis. Disponível no backoffice, app móvel e via API.
- Casos de uso: cobranças de faturas, vendas em redes sociais, pagamentos internacionais
- [Página Pay by Link](https://ifthenpay.com/solutions/pay-by-link/)

### ifthenpay.me
QR Code ou link para receber pagamentos presenciais ou remotos sem necessidade de TPA. O comerciante define montante fixo ou deixa em aberto. Cada registo tem um ID único associado. O cliente pode preencher dados de faturação antes de pagar.
- Casos de uso: balcão de loja sem TPA, venda de produtos/serviços online simples
- [Página ifthenpay.me](https://ifthenpay.com/solutions/ifthenpay-me/)

### Formulários
Criação de formulários de pagamento sem necessidade de site ou checkout próprio. Após submissão, o cliente é redirecionado para a gateway de pagamentos da ifthenpay.
- Casos de uso: inscrições em eventos, donativos, quotas associativas, reservas, serviços pontuais
- [Página Formulários](https://ifthenpay.com/solutions/forms/)

### Gateway
Link integrável em qualquer website, software, rede social, e-mail ou formulário. Redireciona para o portal de pagamentos da ifthenpay onde o cliente escolhe o método preferido.

### PINPAY
Serviço que simplifica pagamentos através de um código PIN único de 10 dígitos. O PIN valida a transação e guia o utilizador para selecionar o método de pagamento preferido. Pode ser apresentado como QR Code.
- Mais informações: https://pinpay.pt
- Casos de uso: vendas por telefone, serviços presenciais

### Weo Invoice
Solução de faturação eletrónica e gestão fiscal, desenvolvida por terceiros com integração ifthenpay.

---

## Plugins & Integrações

Plugins e integrações disponíveis para as principais plataformas. Alguns desenvolvidos pela ifthenpay, outros por terceiros.
- [Página de Plugins & Integrações](https://ifthenpay.com/plugins-and-integrations/)
- [Repositório GitHub](https://github.com/ifthenpay)

**Desenvolvidos pela ifthenpay:**
- [BigCommerce](https://github.com/ifthenpay) — Plataforma de e-commerce focada em escalabilidade multicanal
- [Bitrix24](https://github.com/ifthenpay) — CRM com ferramentas de vendas, automação e colaboração
- [Ecwid](https://github.com/ifthenpay) — Adiciona loja online a qualquer site
- [Google Forms](https://github.com/ifthenpay) — Formulários online com integração de pagamentos
- [Gravity Forms](https://github.com/ifthenpay) — Plugin WordPress para formulários avançados
- [Joomla + VirtueMart](https://github.com/ifthenpay) — CMS e loja online
- [Magento V2](https://github.com/ifthenpay) — E-commerce robusto para média e grande escala
- [MemberPress](https://github.com/ifthenpay) — Plugin WordPress para membros, subscrições e conteúdos pagos
- [Moodle](https://github.com/ifthenpay) — Plataforma e-learning
- [Odoo](https://github.com/ifthenpay) — ERP modular para gestão empresarial, faturação e vendas
- [OpenCart](https://github.com/ifthenpay) — Plataforma open-source para lojas online
- [PrestaShop](https://github.com/ifthenpay) — Plataforma open-source para lojas online
- [Sage](https://github.com/ifthenpay) — Software de contabilidade e faturação
- [Shopify](https://github.com/ifthenpay) — Plataforma tudo-em-um para lojas online
- [Squarespace](https://github.com/ifthenpay) — Plataforma de criação de websites com e-commerce
- [WHMCS](https://github.com/ifthenpay) — Faturação e gestão de clientes para hosting
- [Wix](https://github.com/ifthenpay) — Criação de websites com e-commerce integrado

**Desenvolvidos por terceiros:**
- Drupal — CMS para websites e aplicações web
- JumpSeller — Plataforma para lojas online
- Loja9 — Agência de comércio digital
- nopCommerce — E-commerce open-source baseado em .NET
- Weo Invoice — Faturação eletrónica e gestão fiscal
- WooCommerce — Plugin WordPress para lojas online

---

## Adesão & Conta

- **Formulário de adesão:** https://ifthenpay.com/join/
- Preencher o formulário online ou descarregar e enviar o contrato assinado para suporte@ifthenpay.com
- Sem custos de adesão, sem mensalidades
- Após adesão, são fornecidas as chaves de integração (MB KEY, MBWAY KEY, etc.)
- [Carreiras](https://ifthenpay.com/careers/)
- [Notícias & Atualizações](https://ifthenpay.com/blog/)
- [Relatórios & Contas](https://ifthenpay.com/accounts-and-reports/)

---

## Informação Legal e Institucional

- [Política de Privacidade e Proteção de Dados](https://ifthenpay.com/privacy-policy/) — Informação sobre recolha, tratamento e proteção de dados pessoais, em conformidade com o RGPD. Responsável pelo tratamento: ifthenpay, Lda. Contacto: ifthenpay@ifthenpay.com
- [Política BCFT](https://ifthenpay.com/assets/files/POL_BCFT_2026_01.pdf) — Política de Branqueamento de Capitais e Financiamento do Terrorismo
- [Código de Conduta](https://ifthenpay.com/downloads/CODIGO_DE_CONDUTA%202023_01.pdf)
- [Registo no Banco de Portugal](https://www.bportugal.pt/entidadeautorizada/ifthenpay-lda) — Registo n.º 8707
- Contrato de Adesão: disponível para download em https://ifthenpay.com/join/

---

## Documentação Técnica API

A API REST da ifthenpay permite gerar referências de pagamento, receber notificações (webhooks/callbacks) e consultar dados de pagamentos. Sempre usar sandbox para testes — abuso da API de produção pode gerar bloqueio de conta.

- **Índice completo da documentação:** https://ifthenpay.com/docs/en/
- **Documentação atualizada em:** 12 de maio de 2026

---

### API Multibanco REST

Permite gerar referências de pagamento Multibanco.
- **Base URL:** `https://api.ifthenpay.com/multibanco/reference`
- **Chave necessária:** MB KEY
- **Documentação:** https://ifthenpay.com/docs/en/api/multibanco/
- **Sandbox disponível:** sim (`POST /sandbox`)

#### POST /init — Criar referência de pagamento (produção)
Cria uma nova referência Multibanco.

**Request Body (JSON):**
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| mbKey | string | ✅ | Chave MB atribuída pela ifthenpay |
| orderId | string (max 25) | ✅ | Número de encomenda/fatura |
| amount | string | ✅ | Montante com exatamente 2 casas decimais, separador "." |
| description | string (max 200) | — | Descrição do pagamento |
| expiryDays | number (enum) | — | Dias até expirar (0=meia-noite do mesmo dia, 1–31, 45, 60, 90, 120, 180, 365, 730). Omitir = sem expiração |
| url | string (max 100) | — | URL de retorno |
| clientCode | string (max 200) | — | Código do cliente |
| clientName | string (max 200) | — | Nome do cliente |
| clientEmail | string (max 200) | — | E-mail do cliente |
| clientPhone | string (max 200) | — | Telemóvel do cliente |
| clientUsername | string (max 200) | — | Username do cliente |

**Exemplo de request:**
```bash
curl https://api.ifthenpay.com/multibanco/reference/init \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "mbKey": "MB_KEY",
    "orderId": "1887",
    "amount": "10.99",
    "description": "order 1 payment",
    "url": "https://www.empresa.com",
    "clientCode": 123,
    "clientName": "John Doe",
    "clientEmail": "empresa@empresa.com",
    "clientUsername": "johndoe",
    "clientPhone": 351976543210,
    "expiryDays": "0"
  }'
```

**Resposta 200:**
```json
{
  "Amount": 10.99,
  "Entity": 11990,
  "ExpiryDate": "30-10-2021",
  "Message": "Success",
  "OrderId": 1887,
  "Reference": "000000291",
  "RequestId": "5Qd8gtWLAEUJ6n0lkS5g",
  "Status": "0"
}
```

#### POST /sandbox — Criar referência de pagamento (sandbox)
Idêntico ao `/init` mas em modo sandbox. Usa os mesmos parâmetros e retorna a mesma estrutura de resposta.

---

### API MB WAY REST

Permite iniciar pedidos de pagamento MB WAY para o telemóvel do cliente.
- **Base URL:** `https://api.ifthenpay.com/spg/payment`
- **Chave necessária:** MBWAY KEY
- **Documentação:** https://ifthenpay.com/docs/en/api/mbway/

#### POST /mbway — Criar pedido de pagamento
Envia pedido de pagamento para a app MB WAY do cliente.

**Request Body (JSON):**
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| mbWayKey | string | ✅ | Chave MBWAY atribuída pela ifthenpay |
| orderId | string (max 15) | ✅ | Identificador de pagamento |
| amount | string | ✅ | Montante, separador decimal "." |
| mobileNumber | string | ✅ | Número de telemóvel com indicativo: `351#912345678` |
| description | string (max 100) | — | Descrição do pagamento |
| email | string (max 100) | — | E-mail do cliente |

**Exemplo de request:**
```bash
curl https://api.ifthenpay.com/spg/payment/mbway \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "mbWayKey": "MBWAY_KEY",
    "orderId": "1887",
    "amount": "10.99",
    "mobileNumber": "351#912345678",
    "email": "empresa@empresa.com",
    "description": "order 1 payment"
  }'
```

**Resposta 200:**
```json
{
  "Amount": 10.99,
  "Message": "Pending",
  "orderId": 1887,
  "RequestId": "i2szvoUfPYBMWdSxqO3n",
  "Status": "000"
}
```

#### GET /mbway/status — Verificar estado do pagamento
Verifica o estado de um pedido MB WAY previamente criado.

**Query Parameters:**
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| mbWayKey | string | ✅ | Chave MBWAY atribuída pela ifthenpay |
| requestId | string | ✅ | RequestId obtido na resposta do pedido de pagamento |

**Exemplo de request:**
```bash
curl 'https://api.ifthenpay.com/spg/payment/mbway/status?mbWayKey=MBWAY_KEY&requestId=i2szvoUfPYBMWdSxqO3n'
```

**Resposta 200:**
```json
{
  "CreatedAt": "03-01-2024 15:15:06",
  "Message": "Success",
  "RequestId": "i2szvoUfPYBMWdSxqO3n",
  "Status": "000",
  "UpdateAt": "03-01-2024 15:15:16"
}
```

---

### API Payshop REST

Permite gerar referências de pagamento Payshop.
- **Base URL:** `https://api.ifthenpay.com/payshop`
- **Chave necessária:** PAYSHOP KEY
- **Documentação:** https://ifthenpay.com/docs/en/api/payshop/
- **Sandbox disponível:** sim (`POST /sandbox`, `GET /getsandbox`)

#### POST /reference — Criar referência (produção, via POST)

**Request Body (JSON):**
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| payshopkey | string | ✅ | Chave Payshop atribuída pela ifthenpay |
| id | string (max 25) | ✅ | Identificador de pagamento |
| valor | string | ✅ | Montante, separador decimal "." |
| validade | string | — | Data de expiração no formato YYYYMMDD; pode ficar em branco |

**Exemplo de request:**
```bash
curl https://api.ifthenpay.com/payshop/reference \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "payshopkey": "PAYSHOP_KEY",
    "id": "12345",
    "valor": "5.00",
    "validade": 20301231
  }'
```

**Resposta 200:**
```json
{
  "Code": "0",
  "Message": "Success",
  "Reference": "1021600051424",
  "RequestId": "3VcgFZrviWnSlTCJPLdz"
}
```

#### GET /get — Criar referência (produção, via GET)
Mesmos parâmetros que o POST mas enviados como path parameters na URL.

#### POST /sandbox — Criar referência (sandbox)
Idêntico ao `POST /reference` mas em modo sandbox.

#### GET /getsandbox — Criar referência (sandbox, via GET)
Idêntico ao `GET /get` mas em modo sandbox.

---

### API Credit Card REST

Permite iniciar pagamentos com cartão de crédito/débito. Redireciona o cliente para uma página segura de introdução de dados do cartão.
- **Base URL:** `https://api.ifthenpay.com/creditcard`
- **Chave necessária:** CCARD KEY
- **Documentação:** https://ifthenpay.com/docs/en/api/ccard/
- **Sandbox:** usar endpoint `/sandbox/init/{CCARD_KEY}` com cartões de teste:
  - Sucesso: `4012 0010 3714 1112`, CVC: 212, Validade: 12/27
  - Erro: `4761 7390 0101 0135`, CVC: 608, Validade: 12/29

Após pagamento, são acrescentados parâmetros à URL de retorno: `id`, `amount`, `requestId`. Em caso de sucesso, é adicionado também `sk` (signature key, SHA-256 de `id+amount+requestId` com a CCARD KEY como segredo).

#### POST /init/{CCARD_KEY} — Iniciar pagamento com cartão

**Path Parameters:**
| Campo | Descrição |
|---|---|
| CCARD_KEY | Chave de cartão atribuída pela ifthenpay |

**Request Body (JSON):**
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| orderId | string (max 15) | ✅ | Identificador de pagamento |
| amount | string | ✅ | Montante, separador decimal "." |
| successUrl | string | ✅ | URL de redireccionamento após pagamento com sucesso |
| errorUrl | string | ✅ | URL de redireccionamento em caso de erro (sem pagamento) |
| cancelUrl | string | ✅ | URL de redireccionamento se o cliente cancelar |
| language | string | — | Idioma da página de cartão (default: `en`) |

**Exemplo de request:**
```bash
curl 'https://api.ifthenpay.com/creditcard/init/{CCARD_KEY}' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "orderId": "order_45678",
    "amount": "11.55",
    "successUrl": "https://youraddress.com/success.php",
    "errorUrl": "https://youraddress.com/error.php",
    "cancelUrl": "https://youraddress.com/cancel.php",
    "language": "en"
  }'
```

**Resposta 200:**
```json
{
  "Message": "Success",
  "PaymentUrl": "https://webkit.lemonway.fr/mb/ifthenpay/prod/?moneyintoken=...",
  "RequestId": "36jvlEhUYeknQ8PHKprR",
  "Status": "0"
}
```

---

### API Pay by Link & PINPAY REST

Permite gerar links de pagamento e códigos PIN para direcionar o cliente ao portal de pagamentos da ifthenpay.
- **Base URL:** `https://api.ifthenpay.com/gateway`
- **Chave necessária:** GATEWAY KEY
- **Documentação:** https://ifthenpay.com/docs/en/api/pbl/

#### POST /pinpay/{GATEWAY_KEY} — Criar link de pagamento e código PINPAY

**Path Parameters:**
| Campo | Descrição |
|---|---|
| GATEWAY_KEY | Chave de gateway atribuída pela ifthenpay |

**Request Body (JSON):**
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| id | string (max 15) | ✅ | Identificador de pagamento. Se usar Multibanco offline, apenas 4 dígitos numéricos |
| amount | string | ✅ | Montante, separador decimal "." |
| accounts | string (enum) | — | Métodos de pagamento disponíveis, formato: `MBWAY\|MBWAY-KEY;MB\|MB-KEY;CCARD\|CCARD-KEY;...`. Opções: `ENTITY\|SUBENTITY` (Multibanco offline), `MB\|MB-KEY`, `MBWAY\|MBWAY-KEY`, `PAYSHOP\|PAYSHOP-KEY`, `CCARD\|CCARD-KEY`, `COFIDIS\|COFIDIS-KEY`, `GOOGLE\|GOOGLE-KEY`, `APPLE\|APPLE-KEY` |
| description | string (max 200) | — | Descrição |
| expiredate | string | — | Data de expiração YYYYMMDD. Se > 31 dias, aplica-se o critério de 45, 60, 90, 120, 180, 365 ou 730 dias |
| success_url | string | — | URL após pagamento com sucesso |
| error_url | string | — | URL em caso de erro |
| cancel_url | string | — | URL se o cliente cancelar |
| btnCloseUrl | string | — | URL do botão fechar/voltar |
| btnCloseLabel | string | — | Texto do botão fechar/voltar |
| otp | string (enum) | — | `true` = link de uso único; `false` = reutilizável |
| lang | string (enum) | — | Idioma: `pt`, `en`, `es`, `fr` (default: `pt`) |
| selected_method | string (enum) | — | Método pré-selecionado: `1`=Multibanco, `2`=MB WAY, `3`=Payshop, `4`=Cartão, `7`=Cofidis Pay, `8`=PIX |

**Exemplo de request:**
```bash
curl 'https://api.ifthenpay.com/gateway/pinpay/{GATEWAY_KEY}' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "1234",
    "amount": "21.50",
    "description": "Order 1234",
    "accounts": "MBWAY|XXX-000000;11686|000;MB|BEM-700700",
    "expiredate": 20301231,
    "success_url": "https://youraddress.com/success.php",
    "error_url": "https://youraddress.com/error.php",
    "cancel_url": "https://youraddress.com/cancel.php",
    "btnCloseUrl": "https://youraddress.com",
    "btnCloseLabel": "Close",
    "otp": "true",
    "lang": "pt",
    "selected_method": "1"
  }'
```

**Resposta 200:**
```json
{
  "PinCode": 1234567890,
  "RedirectUrl": "https://gateway.ifthenpay.com/url/r54aiUE1dX",
  "PinpayUrl": "https://pinpay.pt/1234567890"
}
```

#### POST /pinpay/{GATEWAY_KEY}/{REQUEST_STATUS} — Ativar ou desativar link

Ativa ou desativa um link de pagamento existente. `{REQUEST_STATUS}` deve ser `enable` ou `disable`.

**Request Body (JSON):**
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| url | string | ✅ | O `RedirectUrl` retornado na criação do link |

**Exemplo de request:**
```bash
curl 'https://api.ifthenpay.com/gateway/pinpay/{GATEWAY_KEY}/disable' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://gateway.ifthenpay.com/url/08c6nh97sn"}'
```

**Resposta 200:**
```json
{
  "Message": "enabled",
  "Status": "0"
}
```

---

### API Cofidis Pay REST

Permite iniciar pedidos de financiamento Cofidis Pay em prestações.
- **Base URL:** `https://api.ifthenpay.com/cofidis`
- **Chave necessária:** COFIDIS KEY
- **Documentação:** https://ifthenpay.com/docs/en/api/cofidispay/
- **Sandbox:** usar COFIDIS TEST KEY. Cada pedido deve ter valores únicos em OrderID, CustomerVat, CustomerEmail e CustomerPhone.

#### POST /init/{COFIDIS_KEY} — Iniciar pagamento Cofidis

**Request Body (JSON):**
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| orderId | string (max 15) | ✅ | Identificador de pagamento |
| amount | string | ✅ | Montante, separador decimal "." |
| returnUrl | string | ✅ | URL de retorno (sucesso/falha). Parâmetro `&Success=True` adicionado em caso de pré-aprovação |
| customerVat | string | — | NIF do cliente |
| customerName | string | — | Nome do cliente |
| customerEmail | string | — | E-mail do cliente |
| customerPhone | string | — | Telemóvel do cliente (com indicativo) |
| billingAddress | string | — | Morada de faturação |
| billingZipCode | string | — | Código postal de faturação |
| billingCity | string | — | Cidade de faturação |
| deliveryAddress | string | — | Morada de entrega |
| deliveryZipCode | string | — | Código postal de entrega |
| deliveryCity | string | — | Cidade de entrega |
| description | string | — | Descrição |

**Exemplo de request:**
```bash
curl 'https://api.ifthenpay.com/cofidis/init/  {COFIDIS_KEY}' \
    --request POST \
    --header 'Content-Type: application/json' \
    --data '{
        "orderId": "order_45678",
        "amount": "11.55",
        "returnUrl": "https://youraddress.com/status.php",
        "description": "Order 45678",
        "customerName": "John Doe",
        "customerVat": "123456789",
        "customerEmail": "johndoe@example.com",
        "customerPhone": "+351256245560",
        "billingAddress": "123 Main Street",
        "billingZipCode": "12345",
        "billingCity": "New York",
        "deliveryAddress": "456 Elm Street",
        "deliveryZipCode": "67890",
        "deliveryCity": "Los Angeles"
    }'
```

**Resposta 200:**
```json
{
  "message": "Success",
  "paymentUrl": "https://gateway.ifthenpay.com/?moneyintoken=...",
  "requestId": "36jvlEhUYeknQ8PHKprR",
  "status": "0"
}
```

#### POST /status — Verificar estado do pagamento Cofidis

**Request Body (JSON):**
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| cofidisKey | string | ✅ | Chave Cofidis |
| requestId | string | ✅ | Token do pedido |

**Exemplo de request:**
```bash
curl https://api.ifthenpay.com/cofidis/status \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "cofidisKey": "COFIDIS_KEY",
    "requestId": "36jvlEhUYeknQ8PHKprR"
  }'
```

**Resposta 200:**
```json
[{
  "amount": "11.55",
  "description": "Order 45678",
  "orderId": "order_45678",
  "status": "INITIATED",
  "statusCode": "INITIATED",
  "statusDateTime": "28-11-2023 15:50:328",
  "statusMessage": "O pedido aguarda o envio da fatura."
}]
```

#### GET /limits/{COFIDIS_KEY} — Consultar limites do cliente
Retorna os limites mínimo e máximo de financiamento disponíveis para o cliente.

**Exemplo de request:**
```bash
curl 'https://api.ifthenpay.com/cofidis/limits/{COFIDIS_KEY}'
```

**Resposta 200:**
```json
{
  "limits": {
    "maxAmount": 1000,
    "minAmount": 60
  },
  "message": "success"
}
```

---

### API Direct Debit REST

Permite gerir autorizações e cobranças por débito direto.
- **Base URL (produção):** `https://services.ifthenpay.com/directdebit`
- **Base URL (sandbox):** `https://services.ifthenpay.com/sandbox/directdebit`
- **Chave necessária:** DD KEY + BACKOFFICE KEY
- **Documentação:** https://ifthenpay.com/docs/en/api/directdebit/
- **Autenticação:** JWT Bearer Token (gerado via `POST /api/v1/auth/token`)

#### POST /api/v1/auth/token — Gerar token JWT

**Request Body (JSON):**
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| backofficeKey | string (max 19) | ✅ | Chave de backoffice fornecida pela ifthenpay |

**Exemplo de request:**
```bash
curl https://services.ifthenpay.com/directdebit/api/v1/auth/token \
    --request POST \
    --header 'Content-Type: application/json' \
    --data '{
        "backofficeKey": "BACKOFFICE_KEY"
    }'
```

**Resposta 201:**
```json
{
  "data": {
    "token_type": "Bearer",
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiry_date": "2024-11-05 13:49:58"
  }
}
```

Todos os endpoints seguintes requerem o header `Authorization: Bearer <access_token>`.

**Grupo DIRECT DEBIT AUTHORIZATION:**
- `POST /api/v1/authorization/create` — Criar autorização (mandato)
- `GET /api/v1/authorization/list` — Listar autorizações
- `PUT /api/v1/authorization/update/{mandateId}` — Atualizar autorização

**Grupo DIRECT DEBIT COLLECTION:**
- `POST /api/v1/collection/create/{mandateId}` — Criar cobrança para um mandato
- `GET /api/v1/collection/list` — Listar cobranças
- `PUT /api/v1/collection/update/{transactionId}` — Atualizar cobrança
- `DELETE /api/v1/collection/cancel/{transactionId}` — Cancelar cobrança

**Grupo DOCUMENTATION:**
- `GET /api/v1/authorization/pdf/{mandateId}` — Obter PDF do mandato
- `POST /api/v1/authorization/upload/{mandateId}` — Fazer upload de documentação do mandato

#### POST /api/v1/authorization/create — Criar autorização

**Headers:** `Authorization: Bearer <token>`

**Request Body (JSON):**
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| ddKey | string | ✅ | Chave DD atribuída pela ifthenpay |
| contractId | string | ✅ | Identificador do contrato |
| debtor | object | ✅ | Dados do devedor (ver estrutura abaixo) |
| periodicity | string (enum) | ✅ | Periodicidade: `PUNCTUAL`, `WEEKLY`, `FORTNIGHTLY`, `MONTHLY`, `QUARTERLY`, `HALF-YEARLY`, `ANNUAL` |
| scheme | string | ✅ | Esquema SEPA: `CORE` ou `B2B` |
| contractDescription | string | — | Descrição opcional do contrato |
| obs | string | — | Observações |
| nextCollectionDate | date | — | Data da próxima cobrança |
| nextCollectionAmount | float | — | Montante da próxima cobrança |
| maximumAmount | float | — | Montante máximo por transação |
| expirationDate | date | — | Data de expiração da autorização |

**Estrutura do objeto `debtor`:** `name`, `email`, `phone` (ex: `351#123456789`), `vat`, `idCardNumber`, `idCardExpirationDate`, `iban`, `swift`, `address` (com `address`, `postalCode`, `city`, `country`)

**Exemplo de request:**
```bash
curl https://services.ifthenpay.com/directdebit/api/v1/authorization/create \
  --request POST \
  --header 'Authorization: Bearer eyQoOXAiOiJKQ1QiLCJhbGciOiJIUzI1NiJ9...' \
  --header 'Content-Type: application/json' \
  --data '{
    "ddKey": "DD_KEY",
    "contractId": "contract123",
    "contractDescription": "Contract for recurring payments",
    "obs": "No additional notes",
    "scheme": "CORE",
    "periodicity": "FORTNIGHTLY",
    "nextCollectionAmount": 50,
    "maximumAmount": 500,
    "nextCollectionDate": "2024-12-25",
    "expirationDate": "2025-08-12",
    "debtor": {
      "name": "John Doe",
      "email": "johndoe@example.com",
      "phone": "351#123456789",
      "vat": "DE123456",
      "idCardNumber": "ID123456789",
      "idCardExpirationDate": "2025-08-12",
      "iban": "DE89370400440532013000",
      "swift": "DEUTDEDB",
      "address": {
        "address": "123 Main Street",
        "postalCode": "12345",
        "city": "Berlin",
        "country": "Germany"
      }
    }
  }'
```

**Resposta 201:**
```json
{
  "status": 201,
  "data": {
    "mandateId": "030802052798",
    "maximumAmount": 55.3,
    "status": "ACTIVE",
    "expirationDate": "2025-08-12",
    "nextCollectionDate": "2024-12-25"
  }
}
```

#### GET /api/v1/authorization/list — Listar autorizações

**Headers:** `Authorization: Bearer <token>`

**Query Parameters:** `ddKey` (✅), `mandateId`, `collectionDate`, `status` (`PENDING`, `AWAITING_VERIFICATION`, `ACTIVE`, `SUSPENDED`, `CANCELED`), `initialDate`, `finalDate`, `limit` (default: 20), `page`

**Exemplo de request:**
```bash
curl 'https://services.ifthenpay.com/directdebit/api/v1/authorization/list?ddKey=DD_KEY&status=PENDING&limit=1&page=1' \
  --header 'Authorization: Bearer eyQoOXAiOiJKQ1QiLCJhbGciOiJIUzI1NiJ9...'
```

**Resposta 200:**
```json
{
  "status": 200,
  "data": {
    "authorizations": [{
      "mandateId": "04823294121",
      "ddKey": "DD_KEY",
      "contractId": "214124",
      "scheme": "CORE",
      "periodicity": "PUNCTUAL",
      "maximumAmount": 30,
      "nextCollectionAmount": 10,
      "nextCollectionDate": "2024-11-28",
      "status": "PENDING",
      "debtor": {
        "name": "ifthenpay, lda",
        "email": "suporte@ifthenpay.com",
        "iban": "******************7211",
        "address": { "city": "Santa Maria da Feira", "country": "Portugal" }
      },
      "createdAt": "2024-10-24 12:06:50.910"
    }],
    "pagination": { "current_page": 1, "total_pages": 1, "total_records": 1 }
  }
}
```

#### PUT /api/v1/authorization/update/{mandateId} — Atualizar autorização

**Headers:** `Authorization: Bearer <token>`. Todos os campos do body são opcionais (incluindo `debtor`, `periodicity`, `scheme`, `status`, etc.).

**Exemplo de request:**
```bash
curl 'https://services.ifthenpay.com/directdebit/api/v1/authorization/update/{mandateId}' \
  --request PUT \
  --header 'Authorization: Bearer eyQoOXAiOiJKQ1QiLCJhbGciOiJIUzI1NiJ9...' \
  --header 'Content-Type: application/json' \
  --data '{
    "periodicity": "MONTHLY",
    "maximumAmount": 500,
    "nextCollectionDate": "2024-12-25",
    "status": "ACTIVE"
  }'
```

**Resposta 200:**
```json
{ "status": 200, "data": { "mandateId": "030802052798", "status": "ACTIVE" } }
```

> ⚠️ Quando o status muda para `SUSPENDED` ou `CANCELED`, todas as cobranças pendentes associadas são imediatamente canceladas.

#### POST /api/v1/collection/create/{mandateId} — Criar cobrança manual

**Headers:** `Authorization: Bearer <token>`

**Request Body (JSON):**
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| amount | float | ✅ | Montante a cobrar |
| collectionDate | date | ✅ | Data da cobrança |
| description | string | — | Descrição da cobrança |
| externalID | string | — | Identificador externo |

**Exemplo de request:**
```bash
curl 'https://services.ifthenpay.com/directdebit/api/v1/collection/create/{mandateId}' \
  --request POST \
  --header 'Authorization: Bearer eyQoOXAiOiJKQ1QiLCJhbGciOiJIUzI1NiJ9...' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 125.75,
    "collectionDate": "2024-11-25",
    "description": "Invoice 12345 payment",
    "externalID": "1234500000"
  }'
```

**Resposta 201:**
```json
{
  "status": 201,
  "data": {
    "transactionId": "hYxvh25zxCmlctwqYZtE",
    "collectionStatus": "PENDING",
    "collectionDate": "2023-10-02"
  }
}
```

#### GET /api/v1/collection/list — Listar cobranças

**Headers:** `Authorization: Bearer <token>`

**Query Parameters:** `ddKey` (✅), `mandateId`, `transactionId`, `collectionDate` (YYYY-MM-DD), `status` (`PENDING`, `CANCELED`, `PROCESSING`, `COMPLETED`, `ERROR`), `limit`, `page`

**Exemplo de request:**
```bash
curl 'https://services.ifthenpay.com/directdebit/api/v1/collection/list?ddKey=DD_KEY&status=PENDING&limit=1&page=1' \
  --header 'Authorization: Bearer eyQoOXAiOiJKQ1QiLCJhbGciOiJIUzI1NiJ9...'
```

**Resposta 200:**
```json
{
  "status": 200,
  "data": {
    "collections": [{
      "mandateId": "010179121548",
      "transactionId": "Ml6z7B1uTgBo0zJcQ3Fs",
      "amount": 1.13,
      "collectionDate": "2024-10-30",
      "collectionStatus": "PENDING",
      "referenceId": "3040039C6E",
      "description": "Invoice 12345 payment",
      "externalID": "1234500000",
      "createdAt": "2024-10-24 16:19:56.413"
    }],
    "pagination": { "current_page": 1, "total_pages": 1, "total_records": 1 }
  }
}
```

#### PUT /api/v1/collection/update/{transactionId} — Atualizar cobrança

**Headers:** `Authorization: Bearer <token>`

**Request Body (JSON):** `collectionDate` (✅), `amount`, `description`, `externalID`

**Exemplo de request:**
```bash
curl 'https://services.ifthenpay.com/directdebit/api/v1/collection/update/{transactionId}' \
  --request PUT \
  --header 'Authorization: Bearer eyQoOXAiOiJKQ1QiLCJhbGciOiJIUzI1NiJ9...' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 125.75,
    "collectionDate": "2024-11-25",
    "description": "Invoice 12345 payment",
    "externalID": "1234500000"
  }'
```

**Resposta 200:**
```json
{ "status": 200, "data": { "transactionId": "4GR4t7ldGyGlc650fGUW", "status": "PENDING" } }
```

#### DELETE /api/v1/collection/cancel/{transactionId} — Cancelar cobrança

**Headers:** `Authorization: Bearer <token>`. Sem body.

**Exemplo de request:**
```bash
curl 'https://services.ifthenpay.com/directdebit/api/v1/collection/cancel/{transactionId}' \
  --request DELETE \
  --header 'Authorization: Bearer eyQoOXAiOiJKQ1QiLCJhbGciOiJIUzI1NiJ9...'
```

**Resposta 200:**
```json
{ "status": 200, "data": { "transactionId": "8JykLVLVDNmlLzr8c1ae", "mandateId": "030802052798", "status": "CANCELED" } }
```

#### GET /api/v1/authorization/pdf/{mandateId} — Obter PDF do mandato

**Query Parameters:** `_t` (✅) — JWT token de autenticação. Retorna o PDF em `application/pdf`.

**Exemplo de request:**
```bash
curl 'https://services.ifthenpay.com/directdebit/api/v1/authorization/pdf/{mandateId}?_t=JWT_TOKEN'
```

**Resposta 200** — PDF retornado em `application/pdf`

**Resposta 404** — Mandato não encontrado:
```json
{ "status": 404, "message": "Direct Debit Authorization not found." }
```

#### POST /api/v1/authorization/upload/{mandateId} — Upload de documento assinado

**Headers:** `Authorization: Bearer <token>`

**Request Body (JSON):** `content` (string, base64 do ficheiro), `fileSize` (tamanho em bytes), `fileType` (extensão, ex: `.pdf`)

**Exemplo de request:**
```bash
curl 'https://services.ifthenpay.com/directdebit/api/v1/authorization/upload/{mandateId}' \
  --request POST \
  --header 'Authorization: Bearer eyQoOXAiOiJKQ1QiLCJhbGciOiJIUzI1NiJ9...' \
  --header 'Content-Type: application/json' \
  --data '{
    "fileSize": "2097152",
    "fileType": ".pdf",
    "content": "JVQERi0xLjcNMSAwIGO9iag08PC9UeXB....."
  }'
```

**Resposta 200** — Documento carregado com sucesso:
```json
{ "status": 200, "data": { "mandateId": "12014538099", "mandateFile": "12014538099_20250313.pdf", "status": "ACTIVE" } }
```

**Resposta 403** — Sem permissão para fazer upload do documento:
```json
{ "status": 403, "message": "Forbidden - User lacks permission to upload the document." }
```

---

### API PIX REST

Permite gerar pagamentos PIX para o mercado brasileiro.
- **Base URL:** `https://api.ifthenpay.com/pix`
- **Chave necessária:** PIX KEY
- **Documentação:** https://ifthenpay.com/docs/en/api/pix/
- **Sandbox:** usar PIX TEST KEY. Requer CPF válido em cada pedido.

Dados de teste para sandbox:
- Nome: Ana Santos Araujo | CPF: 853.513.468-93
- Endereço: Rua E, 10409, Maracanaú, CE, 61919-230

#### POST /init/{PIX_KEY} — Iniciar pagamento PIX

**Request Body (JSON):**
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| orderId | string (max 25) | ✅ | Identificador de pagamento |
| amount | string | ✅ | Montante, separador decimal "." |
| redirectUrl | string (max 200) | ✅ | URL de retorno após pagamento (verificar estado via Status API) |
| customerName | string (max 150) | ✅ | Nome completo do cliente |
| customerCpf | string (max 20) | ✅ | CPF do cliente (identificação fiscal brasileira) |
| customerEmail | string (max 250) | ✅ | E-mail do cliente |
| customerPhone | string (max 20) | ✅ | Telemóvel com indicativo internacional |
| description | string | — | Descrição |
| customerAddress | string (max 250) | — | Rua |
| customerStreetNumber | string (max 20) | — | Número |
| customerZipCode | string (max 20) | — | Código postal |
| customerCity | string (max 50) | — | Cidade |
| customerState | string (max 50) | — | Estado |

```bash
curl 'https://api.ifthenpay.com/pix/init/{PIX_KEY}' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "orderId": "order_45678",
  "amount": "11.55",
  "redirectUrl": "https://youraddress.com/status.php",
  "description": "Order 45678",
  "customerName": "John Doe",
  "customerCpf": "74026594025",
  "customerEmail": "johndoe@example.com",
  "customerPhone": "+351256245560",
  "customerAddress": "Main Street",
  "customerStreetNumber": "123",
  "customerZipCode": "12345",
  "customerCity": "New York",
  "customerState": "New York"
}'
```

**Resposta 200:**
```json
{
  "message": "Success",
  "paymentUrl": "https://gateway.ifthenpay.com/?moneyintoken=...",
  "qrCodeValue": "00020126680014br.gov.bcb.pix...",
  "requestId": "36jvlEhUYeknQ8PHKprR",
  "status": "0"
}
```

#### GET /payment/status/ — Verificar estado do pagamento PIX

**Query Parameters:**
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| requestId | string | ✅ | Token obtido na resposta do pedido de pagamento |

**Exemplo de request:**
```bash
curl 'https://api.ifthenpay.com/pix/payment/status/?requestId=i2szvoUfPYBMWdSxqO3n'
```

**Resposta 200:**
```json
{
  "Message": "Success",
  "Status": "0"
}
```

---

### API List of Payments REST

Permite consultar a lista de pagamentos recebidos. Alternativa ou complemento ao callback/webhook.
- **Base URL:** `https://api.ifthenpay.com/v2/payments`
- **Chave necessária:** BACKOFFICE KEY (boKey)
- **Documentação:** https://ifthenpay.com/docs/en/api/list-of-payments-rest/

#### POST /read — Obter lista de pagamentos

Se não forem fornecidos parâmetros opcionais, retorna apenas os 1.000 pagamentos mais recentes.

**Request Body (JSON):**
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| boKey | string | ✅ | Chave de backoffice fornecida pela ifthenpay |
| entity | string | — | Filtrar por entidade: `5 dígitos`, `MB`, `MBWAY`, `PAYSHOP`, `CCARD`, `COFIDIS`, `GOOGLE`, `APPLE`, `PIX`, `TPA` |
| subEntity | string | — | Filtrar por sub-entidade ou chave do método |
| reference | string | — | Referência de pagamento (Multibanco/Payshop) ou orderId (outros métodos) |
| orderId | string | — | Identificador da encomenda |
| amount | string | — | Montante |
| requestId | string | — | Token único do pedido |
| dateStart | string | — | Data de início no formato `dd-MM-yyyy HH:mm:ss` |
| dateEnd | string | — | Data de fim no formato `dd-MM-yyyy HH:mm` |

**Exemplo de request:**
```bash
curl https://api.ifthenpay.com/v2/payments/read \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "boKey": "BACKOFFICE_KEY",
    "entity": null,
    "subEntity": null,
    "reference": null,
    "orderId": null,
    "amount": null,
    "requestId": null,
    "dateStart": "21-10-2024 00:00:00",
    "dateEnd": "21-10-2024 23:59:59"
  }'
```

**Resposta 200:**
```bash
{
  "message": "OK",
  "status": 200,
  "payments": [
    {
      "amount": 22750,
      "entity": "MB",
      "fee": 0.86,
      "netAmount": 22749.14,
      "orderId": "000017273",
      "paymentDate": "21-10-2024 15:41:00",
      "procDate": "20241021",
      "reference": "007875810",
      "requestId": "wIh3HzFByfmj75Adl98x",
      "subEntity": "XXX-000000",
      "terminal": "5-0000000000-CAIXA GERAL DE "
    }
  ]
}
```

---

### API Refunds REST

Permite efetuar devoluções de pagamentos. Suporta devoluções parciais.
- **Base URL:** `https://api.ifthenpay.com/v2/payments`
- **Chave necessária:** BACKOFFICE KEY
- **Documentação:** https://ifthenpay.com/docs/en/api/refund/
- **Métodos suportados:** MB WAY, Cartão de Crédito, Google Pay, Apple Pay, PIX

#### POST /refund — Reembolsar pagamento

**Request Body (JSON):**
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| backofficekey | string | — | Chave de backoffice fornecida pela ifthenpay |
| requestId | string | — | Token do pedido de pagamento original |
| amount | string | ✅ | Montante a reembolsar, separador decimal "." |

**Exemplo de request:**
```bash
curl https://api.ifthenpay.com/v2/payments/refund \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "backofficekey": "BACKOFFICE_KEY",
    "requestId": "36jvlEhUYeknQ8PHKprR",
    "amount": "11.55"
  }'
```

**Resposta 200:**
```json
{
  "Code": 0,
  "Message": "Payment could not be refunded"
}
```

---

## Guias Técnicos

### Callback & Notificações (Webhooks)
Mecanismo para receber notificações automáticas quando um pagamento é confirmado.
- **Documentação:** https://ifthenpay.com/docs/en/guides/callback/
- Configurado pela ifthenpay a pedido do comerciante (por método de pagamento)
- **Política de retry:** máximo 13 tentativas — primeiras 8 a intervalos de 5 minutos, restantes a intervalos de 1 hora
- Sucesso determinado por HTTP 200; qualquer outro código = falha e reenvio
- Parâmetro de segurança `[ANTI_PHISHING_KEY]` em todos os callbacks

**Formato geral da URL de callback:**
```
https://www.yoursite.com/callback.php?key=[ANTI_PHISHING_KEY]&orderId=[ORDER_ID]&amount=[AMOUNT]&requestId=[REQUEST_ID]&payment_datetime=[PAYMENT_DATETIME]
```

**Parâmetros adicionais por método:**
- **Multibanco:** `entity=[ENTITY]&reference=[REFERENCE]`
- **Payshop:** `reference=[REFERENCE]` (parâmetro `anti_phishing_key` em vez de `key`)
- **Credit Card / Google Pay / Apple Pay:** `payment_method=[PAYMENT_METHOD]` (ex: `CCARD`, `GOOGLE`, `APPLE`)
- **Direct Debit:** `mandate_id=[ORDER_ID]&transaction_id=[REQUEST_ID]` — também disponível URL de notificação separada com campos `mandateId`, `transactionId`, `amount`, `currency`, `collectionDate`, `reference`, `status`, `code`
- **PIX:** `anti_phishing_key=` em vez de `key=`
- **Pay by Link / Pinpay:** `id=[ID]&payment_method=[PAYMENT_METHOD]`

**Restrições:** URL máx. 300 caracteres; Anti-Phishing Key máx. 50 caracteres.

---

### Simple Checkout
Método de checkout sem necessidade de API. Basta construir um URL com os parâmetros necessários e partilhá-lo ou incorporá-lo num botão/link no site.
- **Documentação:** https://ifthenpay.com/docs/en/guides/simple-checkout/
- **Chave necessária:** GATEWAY KEY

**Formato do URL:**
```
https://gateway.ifthenpay.com/?token=[GATEWAY_KEY]&id=[ORDER_ID]&amount=[AMOUNT]&description=[DESCRIPTION]&expire=[YYYYMMDD]&lang=[LANG]
```

**Parâmetros:**
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
| token | ✅ | GATEWAY KEY |
| id | ✅ | Identificador único da encomenda |
| amount | ✅ | Montante no formato XX.XX |
| description | — | Descrição (HTML-friendly) |
| lang | — | Idioma: `PT`, `EN`, `ES` |
| expire | — | Data de expiração YYYYMMDD |
| accounts | — | Métodos disponíveis (mesmo formato da API PBL) |
| success_url | — | URL após pagamento com sucesso |
| cancel_url | — | URL se cancelado |
| error_url | — | URL em caso de erro |
| return_url | — | URL de retorno ao site |
| btn_close_url | — | URL do botão fechar |
| btn_close_label | — | Texto do botão fechar |
| selected_method | — | Método pré-selecionado: `1`=MB, `2`=MBWAY, `3`=Payshop, `4`=CCard, `7`=Cofidis, `8`=PIX |
| iframe | — | `true` para uso em iframe |

**Exemplo:**
```
https://gateway.ifthenpay.com/?token=GATEWAY_KEY&id=10501&amount=10.50&description=Order+No.+2010501&expire=20291029&lang=PT
```

---

### Multibanco Offline Algorithm
Integração offline para geração de referências Multibanco sem chamada à API.
- **Documentação:** https://ifthenpay.com/docs/en/guides/multibanco/
- **Necessário:** Código de entidade (5 dígitos numéricos) + Código de sub-entidade (3 dígitos numéricos), atribuídos pela ifthenpay

---

## SDKs & Bibliotecas

### PHP SDK
Integração de todos os métodos de pagamento em aplicações PHP.
- **Documentação:** https://ifthenpay.com/docs/en/
- **GitHub:** https://github.com/ifthenpay/ifthenpay-sdk-php
- **Packagist:** https://packagist.org/packages/ifthenpay/payment-gateway-sdk
- **Instalação:** `composer require ifthenpay/payment-gateway-sdk`

### JavaScript SDK
Integração de todos os métodos de pagamento em aplicações JavaScript/Node.js.
- **Documentação:** https://ifthenpay.com/docs/en/
- **GitHub:** https://github.com/ifthenpay/js-sdk
- **NPM:** https://www.npmjs.com/package/@ifthenpay/js-sdk
- **Exemplo de implementação:** https://ifthenpay.com/docs/en/examples/sdk-js/
- **Instalação:** `npm install @ifthenpay/js-sdk`

---

## Ferramentas

### Webhook Tester
Ferramenta para testar e validar a configuração de callbacks antes de ir para produção. Permite simular pedidos para cada método de pagamento com valores personalizados.
- **URL:** https://ifthenpay.com/docs/tools/webhook-tester/

---

## Suporte & FAQ

- **FAQ:** https://ifthenpay.com/pt-PT/support/solutions/
- **Helpdesk (tickets):** https://ifthenpay.com/pt-PT/support/
- **Email:** suporte@ifthenpay.com
- **Telefone:** +351 256 245 560 | +351 808 222 777
- Suporte técnico gratuito para todos os clientes

---

## Helpdesk — Perguntas Frequentes

### Quem pode aderir?
Podem aderir ao serviço da ifthenpay:
- Empresas
- Empresários em nome individual (ENI)
- Associações
- Fundações
- Condomínios ou outras equiparadas a pessoas coletivas

Não são aceites particulares sem atividade aberta na AT.

---

### Tenho um débito com o nome da IFTHENPAY na minha conta bancária!
A ifthenpay é uma Instituição de Pagamento autorizada e supervisionada pelo Banco de Portugal (registo n.º 8707).

Se aparece o nosso nome em algum movimento na sua conta bancária é porque efetuou um pagamento por referência Multibanco, MB WAY ou num terminal de pagamentos (TPA) de um cliente nosso. Cabe a este a prestação de informações sobre a transação específica, uma vez que a ifthenpay apenas processa o pagamento.

Para identificar o beneficiário efetivo de um pagamento, por favor contacte-nos.

**Importante:**
- Se a designação for **"PAGAMENTO DE SERVIÇOS"** ou **"PAG. SERV."**: aceda aos detalhes do movimento e registe a entidade (5 dígitos) e a referência (9 dígitos), e comunique-nos estes 2 elementos juntamente com a data e montante do pagamento.
- Se a designação for **"COMPRA XXXX IFTHENPAY S M LAMAS"**: pode corresponder a um pagamento MB WAY ou TPA. Indique o contacto telefónico associado ao MB WAY, a data, hora e montante. Na app MB WAY pode consultar em "Atividades" o nome e NIF do beneficiário.
- Se a designação for **"DEBITO DIRETO"** ou **"DD"**: faculte o IBAN, juntamente com a data e montante do débito.

---

### Quando recebo os fundos? — Prazo das transferências
- **Pagamentos Online:** Pagamentos efetuados num dia D (até às 20h00) são transferidos no dia útil seguinte (D+1) e ficam disponíveis na conta no dia útil posterior (D+2). Pagamentos após as 20h00 são processados com os do dia seguinte.
- **Pagamentos TPA:** Fechos de TPA efetuados num dia D (até às 20h00) são transferidos em D+1 e disponíveis em D+2. Fechos após as 20h00 são processados com os do dia seguinte.
- **Pagamentos Débito Direto:** Transferidos até 8 dias úteis após a data da cobrança.

**Notas:**
- As transferências são efetuadas sem qualquer custo.
- A conta bancária pode estar domiciliada em qualquer país da zona SEPA.
- São transferidos os valores líquidos (valor do pagamento deduzida a taxa c/IVA).

---

### Quando recebo a fatura das comissões?
A fatura/recibo das comissões é emitida no final de cada mês e enviada no 1.º dia útil de cada mês.

Juntamente com a fatura/recibo é enviado:
- Extrato detalhado com todos os pagamentos do mês
- Extrato resumo com os totais por dia e o valor de cada transferência diária (útil para reconciliação bancária)

A fatura/recibo e extratos mensais ficam também disponíveis no backoffice para consulta e download.