Guia de Migração

Existem duas formas de migrar para o Toktus API. Escolha a que melhor se encaixa na sua situação:

Abordagem	Alterações de código	Ideal para
Compatibility Mode	Nenhuma — só muda URL e autenticação	Quem quer migrar rápido e adaptar o código depois
Migração manual	Adaptar payload e parsing de resposta	Novas integrações ou quem quer usar todos os recursos do Toktus API

[!NOTE]
O Compatibility Mode e a migração manual não são mutuamente exclusivos. Você pode ativar o Compatibility Mode para migrar agora, e gradualmente adaptar os endpoints para o formato nativo usando o header X-Payload-Format: native por chamada.

Opção 1 — Migração zero-código (Compatibility Mode)

Se você já tem uma integração funcionando com um gateway e quer migrar sem mexer no código:

1. Configure o gateway e o modo de compatibilidade na conta:

curl -X PATCH https://api.toktus.com/api/v1/clients/settings \
  -H "x-api-key: tk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "primaryGateway": "asaas",
    "gatewayFallbacks": ["stripe"],
    "compatibilityMode": "pagarme"
  }'

2. Mude a URL base e a autenticação no seu sistema:

Antes (Pagar.me direto)

    URL:  https://api.pagar.me/core/v5/orders
    Auth: Authorization: Basic <base64(sk_test_xxx:)>
    ```

## Depois (Toktus API)

URL:  https://api.toktus.com/api/v1/charges
Auth: x-api-key: tk_SUA_CHAVE
```

3. Pronto. O payload que você envia e a resposta que você lê continuam no mesmo formato do gateway anterior.

Para detalhes sobre como o Compatibility Mode funciona, incluindo headers de rastreabilidade e migração gradual, veja o Guia de Configuração de Gateway da Conta.

Opção 2 — Migração manual (formato nativo)

Esta opção exige ajustes no código, mas dá acesso completo a todos os recursos do Toktus API: fallback automático, coprodutores, responseFormat, e payload mais simples.

Checklist

Trocar URL base para https://api.toktus.com/api/v1
Substituir header de autenticação por x-api-key: tk_SUA_CHAVE
Cadastrar credenciais do gateway em POST /credentials
Configurar primaryGateway em PATCH /clients/settings (opcional, mas recomendado)
Atualizar payload de envio (remover campos específicos do gateway antigo)
Atualizar leitura dos campos de resposta (ver tabelas abaixo)
Atualizar comparação de status (ex: "paid" → "approved")
(Se usar split) Cadastrar coprodutores e atualizar payload

Mapeamento de campos — Pagar.me

Payload de entrada

Campo Pagar.me	Campo Toktus API	Observação
`payments[0].payment_method`	`paymentMethod`	`credit_card`, `boleto`, `pix`
`payments[0].credit_card.card.number`	`creditCard.number`
`payments[0].credit_card.card.holder_name`	`creditCard.holderName`
`payments[0].credit_card.card.exp_month`	`creditCard.expMonth`
`payments[0].credit_card.card.exp_year`	`creditCard.expYear`
`payments[0].credit_card.card.cvv`	`creditCard.cvv`
`payments[0].credit_card.installments`	`creditCard.installments`
`payments[0].credit_card.token`	`creditCard.token`
`payments[0].pix.expires_in`	`pix.expiresInSeconds`
`payments[0].boleto.due_at`	`boleto.dueDate`	Somente a data: `AAAA-MM-DD`
`payments[0].boleto.instructions`	`boleto.instructions`
`items[0].amount` (soma de todos)	`amount`	Em centavos nos dois casos
`items[0].description`	`description`
`customer.name`	`customer.name`
`customer.email`	`customer.email`
`customer.document`	`customer.document`
`customer.phones.mobile_phone`	`customer.phone`	Concatenar `area_code` + `number`
`customer_id`	`customerId`

Resposta — PIX

Campo Pagar.me	Campo Toktus API
`data.id`	`data.externalId`
`data.status`	`data.status`
`data.charges[0].last_transaction.qr_code`	`data.pixQrCode`
`data.charges[0].last_transaction.qr_code_url`	`data.pixCopyPaste`
`data.amount`	`data.amount`
`data.currency`	`data.currency`

Resposta — Boleto

Campo Pagar.me	Campo Toktus API
`data.charges[0].last_transaction.url`	`data.boletoUrl`
`data.charges[0].last_transaction.line`	`data.boletoBarcode`

Resposta — Cartão de crédito

Campo Pagar.me	Campo Toktus API
`data.charges[0].id`	`data.externalId`
`data.charges[0].amount`	`data.amount`
`data.charges[0].paid_amount`	`data.paidAmount`
`data.status`	`data.status`

Status

Status Pagar.me	Status Toktus API
`paid`	`approved`
`pending` / `waiting_payment` / `pending_payment`	`pending`
`processing`	`processing`
`refused`	`declined`
`canceled`	`cancelled`
`refunded` / `chargedback`	`refunded`
`failed` / `with_error`	`failed`

Mapeamento de campos — Asaas

Payload de entrada

Campo Asaas	Campo Toktus API	Observação
`customer`	`customerId`	ID do customer no Asaas
`billingType`	`paymentMethod`	Ver tabela de conversão abaixo
`value` (reais, float)	`amount` (centavos, inteiro)	Multiplicar por 100
`dueDate`	`boleto.dueDate`	Para boletos
`description`	`description`
`installmentCount`	`creditCard.installments`
`creditCard.holderName`	`creditCard.holderName`
`creditCard.number`	`creditCard.number`
`creditCard.expiryMonth`	`creditCard.expMonth`
`creditCard.expiryYear`	`creditCard.expYear`
`creditCard.ccv`	`creditCard.cvv`

Conversão de billingType:

`billingType` Asaas	`paymentMethod` Toktus API
`CREDIT_CARD`	`credit_card`
`DEBIT_CARD`	`debit_card`
`BOLETO`	`boleto`
`PIX`	`pix`

Resposta

Campo Asaas	Campo Toktus API	Observação
`id`	`externalId`
`value` (reais)	`amount` (centavos)	Multiplicar por 100
`status`	`status`	Ver conversão abaixo
`pixQrCodeImage`	`pixQrCode`
`pixCopiaECola`	`pixCopyPaste`
`bankSlipUrl`	`boletoUrl`
`nossoNumero`	`boletoBarcode`

Status

Status Asaas	Status Toktus API
`PENDING`	`pending`
`CONFIRMED` / `RECEIVED`	`approved`
`REFUSED`	`declined`
`CANCELLED`	`cancelled`
`REFUNDED`	`refunded`

Mapeamento de campos — Stripe

Payload de entrada

Campo Stripe	Campo Toktus API	Observação
`payment_method`	`creditCard.paymentMethodId`
`source`	`creditCard.token`
`amount`	`amount`	Mesma unidade: centavos
`currency`	`currency`
`description`	`description`
`capture_method: "manual"`	`capture: false`	Pré-autorização
`customer`	`customerId`
`payment_method_types[0]`	`paymentMethod`	`card` → `credit_card`

Resposta

Campo Stripe	Campo Toktus API
`id`	`externalId`
`status` (`succeeded`)	`status` (`approved`)
`amount`	`amount` (mesma unidade: centavos)
`amount_received`	`paidAmount`
`amount_refunded`	`refundedAmount`
`next_action.boleto_display_details.hosted_voucher_url`	`boletoUrl`
`next_action.pix_display_qr_code.image_url_png`	`pixQrCode`
`next_action.pix_display_qr_code.data`	`pixCopyPaste`

Status

Status Stripe	Status Toktus API
`succeeded`	`approved`
`processing`	`processing`
`requires_payment_method` / `requires_action`	`pending`
`canceled`	`cancelled`

Mapeamento de campos — Mercado Pago

Payload de entrada

Campo Mercado Pago	Campo Toktus API	Observação
`transaction_amount` (reais, float)	`amount` (centavos, inteiro)	Multiplicar por 100
`token`	`creditCard.token`	Obrigatório para cartão
`payment_method_id`	`creditCard.paymentMethodId`	Alternativo ao token
`installments`	`creditCard.installments`
`description`	`description`
`payer.email`	`customer.email`
`payer.first_name` + `payer.last_name`	`customer.name`	Concatenar
`payer.identification.number`	`customer.document`
`payment_method_id: "pix"`	`paymentMethod: "pix"`

Resposta

Campo Mercado Pago	Campo Toktus API
`id`	`externalId`
`status`	`status`
`transaction_amount` (reais)	`amount` (centavos)
`point_of_interaction.transaction_data.qr_code`	`pixCopyPaste`
`point_of_interaction.transaction_data.qr_code_base64`	`pixQrCode`
`transaction_details.external_resource_url`	`boletoUrl`

Status

Status Mercado Pago	Status Toktus API
`approved`	`approved`
`in_process`	`processing`
`pending`	`pending`
`rejected`	`declined`
`cancelled`	`cancelled`
`refunded`	`refunded`

Mapeamento de campos — PagSeguro

Payload de entrada

Campo PagSeguro	Campo Toktus API	Observação
`charges[0].amount.value` (reais, float)	`amount` (centavos, inteiro)	Multiplicar por 100
`charges[0].payment_method.type`	`paymentMethod`	Ver conversão abaixo
`charges[0].payment_method.card.encrypted`	`creditCard.token`
`charges[0].payment_method.card.holder.name`	`creditCard.holderName`
`charges[0].payment_method.installments`	`creditCard.installments`
`items[0].name`	`description`
`customer.name`	`customer.name`
`customer.email`	`customer.email`
`customer.tax_id`	`customer.document`
`charges[0].boleto.due_date`	`boleto.dueDate`

Conversão de payment_method.type:

`type` PagSeguro	`paymentMethod` Toktus API
`CREDIT_CARD`	`credit_card`
`BOLETO`	`boleto`
`PIX`	`pix`

Resposta

Campo PagSeguro	Campo Toktus API
`charges[0].id`	`externalId`
`charges[0].status`	`status`
`charges[0].amount.value` (reais)	`amount` (centavos)
`charges[0].boleto.links[0].href`	`boletoUrl`
`charges[0].boleto.formatted_barcode`	`boletoBarcode`
`charges[0].qr_codes[0].text`	`pixCopyPaste`
`charges[0].qr_codes[0].links[0].href`	`pixQrCode`

Status

Status PagSeguro	Status Toktus API
`PAID`	`approved`
`WAITING`	`pending`
`IN_ANALYSIS`	`processing`
`DECLINED`	`declined`
`CANCELLED`	`cancelled`
`REFUNDED`	`refunded`

Exemplo prático — antes e depois

Antes (Pagar.me direto)

    // Chamada direta à Pagar.me
    const response = await axios.post('https://api.pagar.me/core/v5/orders', {
      customer: { name: 'João', email: '[email protected]', document: '12345678900' },
      items: [{ amount: 10000, description: 'Produto', quantity: 1 }],
      payments: [{
        payment_method: 'pix',
        pix: { expires_in: 3600 }
      }]
    }, {
      auth: { username: 'sk_test_xxx', password: '' }
    });

    // Parsing específico da Pagar.me
    const pixCode = response.data.charges[0].last_transaction.qr_code_url;
    const status = response.data.status; // "paid"
    const isPaid = status === 'paid';
    ```

## Depois (Toktus API)

```javascript
    // Chamada ao Toktus API (campo gateway opcional se primaryGateway configurado)
    const response = await axios.post(
      'https://api.toktus.com/api/v1/charges',
      {
        paymentMethod: 'pix',
        amount: 10000,
        description: 'Produto',
        pix: { expiresInSeconds: 3600 },
        customer: { name: 'João', email: '[email protected]', document: '12345678900' }
      },
      { headers: { 'x-api-key': 'tk_SUA_CHAVE' } }
    );

    // Parsing normalizado — funciona com qualquer gateway e fallback
    const pixCode = response.data.data.pixCopyPaste;
    const status = response.data.data.status; // "approved"
    const isPaid = status === 'approved';
    ```

---

## Transparência do fallback

Quando um fallback é acionado, a resposta inclui campos extras:

```json
{
  "success": true,
  "data": {
    "gateway": "asaas",
    "gatewayFallbackUsed": true,
    "primaryGateway": "pagarme",
    "status": "approved",
    "pixCopyPaste": "00020126...",
    "externalId": "pay_asaas_xxx"
  }
}

Use gatewayFallbackUsed para logar ou alertar quando o fallback for acionado.

Independente do compatibilityMode, os headers X-RG-* sempre indicam o gateway real que processou — sem precisar parsear o body:

X-RG-Gateway: asaas
X-RG-Fallback-Used: true
X-RG-Charge-Id: ch-rg-uuid-interno

Migração do split

Antes — IDs fixos por gateway

"split": [
  { "type": "percentage", "amount": 92, "recipient_id": "re_abc123" }
]

Se o fallback cair no Asaas, re_abc123 não existe lá — o split falha silenciosamente.

Depois — referência por coprodutor

"split": [
  { "type": "percentage", "amount": 92, "coproducerEmail": "[email protected]" }
]

O sistema resolve o recipient_id correto para qualquer gateway, incluindo fallbacks.

Veja o Guia de Coprodutores para configurar.

Próximos Passos

Configuração de Gateway da Conta — Configure gateway principal e modo de compatibilidade para migração zero-código
Coprodutores e Split — Configure a divisão de recebimento entre múltiplos beneficiários