Aceite métodos de pagamento alternativos (APMs) com a Therius

Cada método de pagamento alternativo (APM) do catálogo da Therius flui 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ê alterna os métodos de pagamento com um único objeto discriminado paymentMethod: { "type": "<code>", "<code>": { ...campos } }. Isso significa que você pode adicionar Pix no Brasil, ACH nos EUA e Klarna na Europa sem alterar a sua lógica central de checkout.

Cada APM exige que uma conexão que o suporte seja primeiro habilitada na sua conta. Confira a página Conexões no seu dashboard para ver o que está ativo, e entre em contato com a Therius para adicionar um método necessário — nenhuma alteração de integração é necessária do seu lado depois de habilitado.

Formato base da requisição

Todas as requisições de APM compartilham a mesma estrutura de nível superior. paymentMethod.type escolhe o método; a chave correspondente dentro de paymentMethod contém os campos desse método. amount.currency e os campos próprios do método são o que muda entre os métodos.

{
  "merchantCode": "MERCHANT_001",
  "orderCode": "ORDER-001",
  "amount": {
    "currency": "<ver tabela de métodos>",
    "value": 5000,
    "exponent": 2
  },
  "paymentMethod": {
    "type": "<code>",
    "<code>": { }
  }
}

paymentMethod é sempre obrigatório e explícito — type é a fonte única da verdade sobre qual método está sendo cobrado, portanto não há campo separado que possa divergir dele.

Vários APMs também exigem o documento de identificação nacional ou fiscal do cliente (por exemplo, o Pix exige um CPF/CNPJ brasileiro, o PSE exige o tipo e número de documento colombiano). Isso vai no objeto raiz da requisição shopper.document — { "type": "<code>", "number": "<value>" } — e não dentro de paymentMethod.<type>, já que a mesma identidade do cliente se aplica independentemente do método utilizado. type é um código canônico de tipo de documento da Therius (consulte GET /sdk/payment-methods ou a tabela de referência em document_types) — um catálogo amplo e fiel ao mercado, não uma garantia de que todos os tipos listados estejam verificados para uma conexão específica. O campo próprio payerTaxId/payerTaxIdType de um método, onde ainda for aceito, sobrescreve shopper.document para aquela chamada específica.A Therius valida o número contra o catálogo antes do envio do pagamento: o formato do tipo de documento e, quando houver, seus dígitos verificadores (por exemplo CPF, CNPJ — incluindo o CNPJ alfanumérico — RUT, CUIT, NIT, RFC, RUC, DNI/NIE, codice fiscale, NIF, BSN, PESEL, Aadhaar). O país é obtido de billingAddress.countryCode ou, alternativamente, da sessão de checkout. Uma falha retorna um 400 como shopper.document.number is not a valid CPF. Para Pix e Boleto, um número enviado sem type é interpretado como CPF (11 dígitos) ou CNPJ (14 caracteres).

Métodos de redirecionamento vs. de débito direto

Os APMs se dividem em duas categorias amplas conforme como o cliente autoriza o pagamento.

Métodos de redirecionamento

O cliente é redirecionado a uma página de terceiros (por exemplo, o banco dele ou o PayPal) para autorizar o pagamento. Inclua returnUrl e cancelUrl dentro do objeto do método. A API responde com status: "pending" e actionRequired.url.

Métodos de débito direto

Os dados da conta bancária são coletados antecipadamente — sem redirecionamento. Passe os campos da conta como bankAccountNumber e bankRoutingNumber (ACH) ou iban (SEPA) diretamente dentro do objeto do método.

Lidar com o redirecionamento

Quando um método retorna status: "pending", você deve direcionar o seu cliente para actionRequired.url a fim de concluir a autorização.

SDK JS
Redirecionamento no servidor

Passe o objeto actionRequired diretamente para sdk.handleAction(). O SDK gerencia o ciclo de vida do redirecionamento e resolve a promessa com o PaymentResult final assim que o cliente retorna.

const result = await sdk.purchase(payload)

if (result.status === 'pending') {
  const finalResult = await sdk.handleAction(result.actionRequired)
  // finalResult.status será 'captured' ou 'refused'
}

Redirecione o navegador do cliente para actionRequired.url. Após a autorização, o cliente é encaminhado para a sua returnUrl com os parâmetros de consulta orderId e status. Verifique o status final chamando GET /payment/inquiry/{orderId}.

# Inclua as URLs de retorno e 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: <uuid>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "orderCode": "ORDER-001",
    "amount": { "currency": "EUR", "value": 5000, "exponent": 2 },
    "paymentMethod": {
      "type": "ideal",
      "ideal": {
        "payerName": "Ada Lovelace",
        "payerEmail": "ada@example.com",
        "returnUrl": "https://yoursite.com/checkout/return",
        "cancelUrl": "https://yoursite.com/checkout/cancel"
      }
    }
  }'

Métodos suportados

Método	Código	Moeda	Notas
Pix	`pix`	BRL	Código QR instantâneo; apenas Brasil
ACH	`ach`	USD	Transferência bancária; liquidação em 1–4 dias
iDEAL	`ideal`	EUR	O método online mais utilizado na Holanda
SEPA Direct Debit	`sepa_debit`	EUR	Zona do Euro, além de GB, CH e NO
Klarna	`klarna`	USD / EUR / GBP	Compre agora, pague depois
Boleto	`boleto`	BRL	Boleto bancário; apenas Brasil
OXXO	`oxxo`	MXN	Comprovante em dinheiro; apenas 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 dashboard da Therius para navegar pelo catálogo completo de mais de 40 métodos. Cada item inclui os campos obrigatórios e um exemplo de requisição pronto para executar que você pode copiar diretamente.

Exemplos específicos por método

Pix
ACH
iDEAL
Klarna

O Pix gera um código QR de pagamento instantâneo. A resposta inclui uma URL de imagem do código QR e uma chave copia e cola sob actionRequired. A liquidação é imediata. payerName, payerEmail e shopper.document (CPF) são obrigatórios.

{
  "merchantCode": "MERCHANT_001",
  "orderCode": "ORDER-PIX-001",
  "amount": { "currency": "BRL", "value": 5000, "exponent": 2 },
  "paymentMethod": {
    "type": "pix",
    "pix": {
      "payerName": "Ada Lovelace",
      "payerEmail": "ada@example.com"
    }
  },
  "shopper": {
    "document": { "type": "CPF", "number": "12345678909" }
  }
}

O ACH coleta os dados da conta bancária do cliente diretamente — sem redirecionamento. payerName, bankRoutingNumber, bankAccountNumber e bankAccountType (checking ou savings) são obrigatórios. Inclua tokenize: true com um shopper.id para salvar a conta para uso futuro.

{
  "merchantCode": "MERCHANT_001",
  "orderCode": "ORDER-ACH-001",
  "amount": { "currency": "USD", "value": 10000, "exponent": 2 },
  "shopper": { "id": "customer-42" },
  "paymentMethod": {
    "type": "ach",
    "ach": {
      "payerName": "Ada Lovelace",
      "bankRoutingNumber": "021000021",
      "bankAccountNumber": "000123456789",
      "bankAccountType": "checking",
      "tokenize": true
    }
  }
}

O iDEAL redireciona o cliente para o banco holandês dele para autorizar. payerName e payerEmail são obrigatórios. Opcionalmente passe issuerId para pré-selecionar um banco e pular a tela de seleção de banco — consulte POST /payment/bank-options.

{
  "merchantCode": "MERCHANT_001",
  "orderCode": "ORDER-IDEAL-001",
  "amount": { "currency": "EUR", "value": 2500, "exponent": 2 },
  "paymentMethod": {
    "type": "ideal",
    "ideal": {
      "payerName": "Ada Lovelace",
      "payerEmail": "ada@example.com",
      "returnUrl": "https://yoursite.com/checkout/return",
      "cancelUrl": "https://yoursite.com/checkout/cancel"
    }
  }
}

A Klarna suporta fluxos de pagar depois e de pagar em parcelas. payerName, payerEmail e payerCountry (código de país ISO de 2 letras) são obrigatórios — não há campo locale na API; payerCountry é o que determina o produto Klarna oferecido. Passe um array de lineItems no nível da requisição (irmão de paymentMethod, não aninhado nele) para melhorar as taxas de aprovação — a Klarna o utiliza para a análise de crédito.

{
  "merchantCode": "MERCHANT_001",
  "orderCode": "ORDER-KLARNA-001",
  "amount": { "currency": "USD", "value": 7500, "exponent": 2 },
  "lineItems": [
    { "description": "Wireless Headphones", "quantity": 1, "amount": 7500 }
  ],
  "paymentMethod": {
    "type": "klarna",
    "klarna": {
      "payerName": "Ada Lovelace",
      "payerEmail": "ada@example.com",
      "payerCountry": "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 definindo tokenize: true dentro do objeto do método, junto com um shopper.id. A 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.

{
  "shopper": { "id": "customer-42" },
  "paymentMethod": {
    "type": "ach",
    "ach": {
      "payerName": "Ada Lovelace",
      "bankRoutingNumber": "021000021",
      "bankAccountNumber": "000123456789",
      "bankAccountType": "checking",
      "tokenize": true
    }
  }
}

Para reutilizar uma conta salva anteriormente no vault em vez dos campos bancários brutos, passe um token simples:

{
  "paymentMethod": {
    "type": "ach",
    "ach": { "token": "vt_4xK9mNpQ2rLsT7uV" }
  }
}

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.

Primeiros passos

Conceitos básicos

Guias

Webhooks

Assistente de IA

Plugins de e-commerce

Aceite métodos de pagamento alternativos (APMs) com a Therius

Formato base da requisição

Métodos de redirecionamento vs. de débito direto

Métodos de redirecionamento

Métodos de débito direto

Lidar com o redirecionamento

Métodos suportados

Exemplos específicos por método

Tokenização de ACH

​Formato base da requisição

​Métodos de redirecionamento vs. de débito direto

Métodos de redirecionamento

Métodos de débito direto

​Lidar com o redirecionamento

​Métodos suportados

​Exemplos específicos por método

​Tokenização de ACH

Formato base da requisição

Métodos de redirecionamento vs. de débito direto

Lidar com o redirecionamento

Métodos suportados

Exemplos específicos por método

Tokenização de ACH