> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therius.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Aceite métodos de pagamento alternativos (APMs) com o Therius
> Adicione Pix, ACH, iDEAL, Klarna e mais de 40 métodos de pagamento pelo mesmo endpoint de purchase — basta mudar o campo paymentMethod.
Todo método de pagamento alternativo (APM) do catálogo do Therius passa pelo mesmo endpoint `POST /payment/purchase` que uma cobrança de cartão padrão. Você não precisa de uma integração diferente por método — você troca de método de pagamento definindo o campo `paymentMethod` e fornecendo uma carga específica do método em `apm`. Isso significa que você pode adicionar Pix no Brasil, ACH nos EUA e Klarna na Europa sem tocar na sua lógica central de checkout.
Cada APM exige que primeiro seja habilitada na sua conta uma conexão que o suporte. Verifique a página **Conexões** no seu painel para ver o que está ativo, e entre em contato com o Therius para adicionar um método de que você precise — nenhuma mudança de integração é necessária do seu lado depois que ele é habilitado.
## Formato base da requisição
Todas as requisições de APM compartilham a mesma estrutura de nível superior. As únicas coisas que mudam entre os métodos são `paymentMethod`, `amount.currency`, e os campos dentro de `apm`.
```json theme={"dark"}
{
"merchantCode": "MERCHANT_001",
"orderCode": "ORDER-001",
"amount": {
"currency": "",
"value": 5000,
"exponent": 2
},
"paymentMethod": "",
"apm": {
/* method-specific fields */
}
}
```
***
## Métodos de redirecionamento vs. de débito direto
Os APMs se dividem em duas categorias amplas conforme como o cliente autoriza o pagamento.
O cliente é redirecionado a uma página de terceiros (por exemplo, o banco dele ou o PayPal) para autorizar o pagamento. Inclua `apm.returnUrl` e `apm.cancelUrl` na sua requisição. A API responde com `status: "pending_action"` e `actionRequired.url`.
Os dados da conta bancária são coletados antecipadamente — sem redirecionamento. Passe campos de conta como `bankAccountNumber` e `bankRoutingNumber` (ACH) ou IBAN (SEPA) diretamente dentro do objeto `apm`.
### Tratar o redirecionamento
Quando um método devolve `status: "pending_action"`, você precisa enviar o seu cliente para `actionRequired.url` para concluir a autorização.
Passe o objeto `actionRequired` diretamente para `sdk.handleAction()`. O SDK gerencia o ciclo de vida do redirecionamento e resolve a promise com o `PaymentResult` final assim que o cliente retorna.
```javascript theme={"dark"}
const result = await sdk.purchase(payload)
if (result.status === 'pending_action') {
const finalResult = await sdk.handleAction(result.actionRequired)
// finalResult.status será 'approved' ou 'declined'
}
```
Redirecione o navegador do cliente para `actionRequired.url`. Após a autorização, o cliente é encaminhado para o seu `apm.returnUrl` com os parâmetros de consulta `orderId` e `status`. Verifique o status final chamando `GET /payment/inquiry/{orderId}`.
```bash theme={"dark"}
# Inclua as URLs de retorno e de cancelamento na sua requisição de purchase
curl -X POST https://api.therius.io/v1/payment/purchase \
-H "Authorization: Bearer prv_production_your_key_here" \
-H "Idempotency-Key: " \
-H "Content-Type: application/json" \
-d '{
"merchantCode": "MERCHANT_001",
"orderCode": "ORDER-001",
"amount": { "currency": "EUR", "value": 5000, "exponent": 2 },
"paymentMethod": "ideal",
"apm": {
"returnUrl": "https://yoursite.com/checkout/return",
"cancelUrl": "https://yoursite.com/checkout/cancel"
}
}'
```
***
## Métodos suportados
| Método | Código | Moeda | Observações |
| ----------------- | ------------ | --------------- | ---------------------------------------------- |
| Pix | `pix` | BRL | QR code instantâneo; somente Brasil |
| ACH | `ach` | USD | Transferência bancária; liquidação em 1–4 dias |
| iDEAL | `ideal` | EUR | Método online mais usado nos Países Baixos |
| SEPA Direct Debit | `sepa_debit` | EUR | Zona do euro, mais GB, CH e NO |
| Klarna | `klarna` | USD / EUR / GBP | Compre agora, pague depois |
| Boleto | `boleto` | BRL | Comprovante bancário; somente Brasil |
| OXXO | `oxxo` | MXN | Comprovante em dinheiro; somente México |
| PayPal | `paypal` | USD / EUR / GBP | |
| Alipay | `alipay` | CNY + 13 moedas | |
| GrabPay | `grabpay` | MYR / SGD / PHP | Sudeste Asiático |
Abra a aba **Conexões** no seu painel do Therius para navegar pelo catálogo completo de mais de 40 métodos. Cada entrada inclui os campos `apm` exigidos e uma requisição de exemplo pronta para executar que você pode copiar diretamente.
***
## Exemplos específicos por método
O Pix gera um QR code de pagamento instantâneo. A resposta inclui uma URL de imagem do QR code e uma string de código para copiar e colar em `actionRequired`. A liquidação é imediata.
```json theme={"dark"}
{
"merchantCode": "MERCHANT_001",
"orderCode": "ORDER-PIX-001",
"amount": { "currency": "BRL", "value": 5000, "exponent": 2 },
"paymentMethod": "pix",
"apm": {
"returnUrl": "https://yoursite.com/checkout/return"
}
}
```
O ACH coleta os dados da conta bancária do cliente diretamente — sem redirecionamento. Inclua `apm.tokenize: true` com um `shopper.id` para salvar a conta para uso futuro.
```json theme={"dark"}
{
"merchantCode": "MERCHANT_001",
"orderCode": "ORDER-ACH-001",
"amount": { "currency": "USD", "value": 10000, "exponent": 2 },
"paymentMethod": "ach",
"shopper": { "id": "customer-42" },
"apm": {
"bankAccountNumber": "000123456789",
"bankRoutingNumber": "021000021",
"accountType": "checking",
"accountHolderName": "Ada Lovelace",
"tokenize": true
}
}
```
O iDEAL redireciona o cliente para o banco holandês dele para autorizar. Opcionalmente passe `apm.issuerId` para pré-selecionar um banco e pular a tela de seleção de banco.
```json theme={"dark"}
{
"merchantCode": "MERCHANT_001",
"orderCode": "ORDER-IDEAL-001",
"amount": { "currency": "EUR", "value": 2500, "exponent": 2 },
"paymentMethod": "ideal",
"apm": {
"returnUrl": "https://yoursite.com/checkout/return",
"cancelUrl": "https://yoursite.com/checkout/cancel"
}
}
```
A Klarna suporta fluxos de pagar depois e de pagar em parcelas. Passe o locale do cliente para garantir que o produto Klarna correto seja oferecido.
```json theme={"dark"}
{
"merchantCode": "MERCHANT_001",
"orderCode": "ORDER-KLARNA-001",
"amount": { "currency": "USD", "value": 7500, "exponent": 2 },
"paymentMethod": "klarna",
"apm": {
"locale": "en-US",
"returnUrl": "https://yoursite.com/checkout/return",
"cancelUrl": "https://yoursite.com/checkout/cancel"
}
}
```
***
## Tokenização de ACH
Para pagamentos ACH você pode salvar a conta bancária para uso futuro passando `apm.tokenize: true` junto com um `shopper.id`. O Therius devolve um vault token na resposta que você pode passar a cobranças ACH posteriores sem pedir ao cliente para digitar novamente os dados da conta dele.
```json theme={"dark"}
{
"shopper": { "id": "customer-42" },
"apm": {
"bankAccountNumber": "000123456789",
"bankRoutingNumber": "021000021",
"accountHolderName": "Ada Lovelace",
"tokenize": true
}
}
```
A tokenização de ACH está sujeita às regras da NACHA. Garanta que você exiba ao cliente o mandato de autorização de conta bancária exigido antes de enviar a requisição.