1. Cartão de Crédito
SYNC-DOCUMENTATION
  • Introdução
  • Auth Token
    • Gera o token de utilização da aplicação
      POST
  • Saldo
    • Retorna o Saldo do Usuário
      GET
  • Transações
    • Consultar transação V1
      GET
    • Consultar transação V2
      GET
  • Utmify
    • Salvar Token
      POST
    • Desativa Token
      POST
  • Partner
    • Consulta dados do Parceiro
      GET
  • Cartão de Crédito
    • Tokenização pública de cartão
    • IFrame
    • Cobrar no cartão
      POST
  • Pix - CashIn
    • Solicitação de depósito via Pix
      POST
  • Old API
    • CashIn
      POST
    • Consulta os dados do Parceiro
      GET
  • Assinaturas - Recorrência
    • Assinatura com Cartão de Crédito
    • Planos
      • Listar planos
      • Criar plano
      • Detalhe do plano
      • Editar plano
      • Arquivar plano
      • Assinantes do plano
    • Assinantes
      • Cadastrar assinante
      • Listar assinantes
      • Detalhe da assinatura
      • Cancelar assinatura
      • Pausar assinatura
      • Reativar assinatura
      • Reenviar cobrança
      • Trocar plano da assinatura
    • Notificações
      • Listar entregas de um webhook
    • Splits
      • Adicionar recebedor de split a um plano
      • Listar splits enviados (perspectiva do seller)
      • Listar convites recebidos (perspectiva do recebedor)
      • Aceitar convite de split
      • Rejeitar convite de split
      • Cancelar split (perspectiva do seller)
    • Produtos — Planos
      • Listar planos aninhados a um produto
      • Criar plano aninhado a um produto
      • Atualizar plano aninhado
      • Desativar plano aninhado
      • Marcar plano como padrão do produto
  • Reembolsos
    • Solicitar reembolso de uma venda
    • Consultar uma solicitação de reembolso
  • Webhooks
    • Cash-In
      • Cash-in criado (cobrança PIX gerada)
      • Cash-in atualizado (mudança de status)
      • Cash-in legado (notificação mínima)
    • Cash-Out
      • Cash-out criado (saque solicitado)
      • Cash-out atualizado (mudança de status do saque)
    • Cartão de Crédito
      • Cartão de crédito — cobrança criada
      • Cartão de crédito — mudança de status
    • Transações - Completo
      • Cobrança de transação criada
      • Transação teve mudança de status
    • Listar webhooks
    • Criar webhook
    • Atualizar webhook
    • Excluir webhook
    • Rotacionar o segredo de assinatura
  • Raiz
    • iFrame de pagamento (cartão e Apple Pay)
  • Esquemas
    • Webhook
      • CashIn
        • onCreate
        • onUpdate
        • CashinCreated
        • CashinUpdated
        • CashinOld
      • CashOut
        • onCreate
        • onUpdate
      • Cash-In
        • CashinCreated
        • CashinUpdated
        • CashinOld
    • WebhookInput
    • CashoutCreated
    • CreditCardCreated
    • CashinCreated
    • CardTokenRequest
    • CreditCardPaymentRequest
    • RefundReason
    • Transaction
    • BillingMethod
    • Message
    • TransactionEvent
    • CreditCardCreatePayload
    • CreditCardPaymentAccepted
    • CreditCardStatusPayload
    • CardToken
    • RefundStatus
    • CashinUpdated
    • CreditCardUpdated
    • CashoutUpdated
    • TransactionV2
    • PlanStatus
    • Webhook
    • CashinOld
    • SplitStatus
    • CreatedWebhook
    • RefundWebhookPayload
    • Customer
    • RefundRejectionCategory
    • DebtorAccount
    • SubscriptionSplit
    • PaymentMethod
    • WebhookListItem
    • WebhookDelivery
    • RefundRequest
    • SimpleError
    • SplitRecipientPayload
    • Payment
    • RotatedWebhookSecret
    • RefundTransaction
    • SubscriptionSplitInvite
    • StoreProductPlanRequest
    • CodedError
    • RefundEvent
    • SubscriptionStatus
    • UpdateProductPlanRequest
    • Checkout
    • Card
    • RefusedError
    • PaymentLink
    • ChargeStatus
    • AntiFraudError
    • Tracking
    • Error
    • DeliveryAddress
    • ValidationError
    • PlanResource
    • PaginationMeta
    • ChargeResource
    • SubscriptionResource
    • EnrollPaymentQrCode
    • EnrollPaymentPixAutomatico
    • WebhookResource
    • NotFoundError
    • WebhookEnvelope
    • ChargeBlock
    • MandateBlock
    • WebhookDeliveryResource
  1. Cartão de Crédito

IFrame

iFrame de pagamento (cartão e Apple Pay)#

Formulário de pagamento pronto para colocar no seu checkout. Ele mostra os campos de cartão e o botão do Apple Pay.
O iFrame só gera um token. Nada é cobrado dentro dele.
Quem cobra é o seu servidor. Ele chama Cobrar no cartão com esse token.
Os dados do cartão nunca passam pela sua página nem pelo seu servidor.
Comprador ──► iFrame SyncPay ──(postMessage: token)──► sua página
sua página ──(token + id do pedido)──► seu servidor
seu servidor ──(POST /api/partner/v1/credit-card)──► SyncPay
SyncPay ──(webhook transaction)──► seu servidor  →  libera o pedido em "completed"
Produção
Origem do iFrame (painel)https://app.syncpayments.com.br
APIhttps://api.syncpayments.com.br/api

1. Antes de começar#

1.
Peça ao suporte para liberar o "iFrame de pagamento" na sua conta. O Cartão na API também precisa estar liberado. Sem a liberação, o iFrame não carrega.
2.
Cadastre o domínio do seu site no painel, em Developer API → Chave pública, na seção de domínios. Exemplo: https://loja.exemplo.com.br. Se a origem não estiver na lista, o navegador não mostra o iFrame e as chamadas dele voltam 403.
3.
Pegue a sua chave pública (pk_live_...) na mesma tela.
4.
Apple Pay (opcional): peça ao suporte para cadastrar o domínio do seu site no Apple Pay. Depois publique o arquivo de verificação que o suporte enviar em https://<seu-dominio>/.well-known/apple-developer-merchantid-domain-association. Sem o domínio verificado, o botão não aparece.
Com o iFrame liberado, o painel mostra a aba Developer API → iFrame de pagamento. Ela traz os mesmos códigos desta página, já preenchidos com a sua chave e o seu domínio.

2. Embutir o iFrame#

ParâmetroRegra
amountValor em centavos, um número inteiro de 100 (R 19,90. Fora dessa faixa, o formulário não aparece.
parent_originA origem exata da página que embute, só https://host[:porta]. Não coloque caminho, query nem barra no fim. Ela tem que ser igual à origem real da página.
allow="payment"Obrigatório para o Apple Pay.
Monte a URL no seu servidor, a partir do pedido salvo. Não deixe o navegador escolher o amount.
Embuta o iFrame direto na página principal, nunca dentro de outro iFrame.
Não coloque background no iFrame. Ele é transparente e desenha o próprio cartão.
Não use referrerpolicy="no-referrer". Sem esse atributo, o navegador usa o padrão, que é o correto. Com no-referrer, a origem da sua página fica escondida e o formulário não carrega.
height: 440px é só a altura inicial. O iFrame avisa a altura real pela mensagem resize (passo 3).

3. Ouvir as mensagens#

typeCamposQuando
ready—O iFrame carregou e o site foi aceito. Pode chegar mais de uma vez.
resizeheightA altura do conteúdo mudou.
tokenmethod: "card", token, brand, last4, expires_atO cartão foi selado.
tokenmethod: "apple_pay", token, expires_atO Apple Pay foi selado.
errorcode: "tokenize_failed"A selagem falhou. O comprador pode tentar de novo.
errorcode: "apple_pay_unavailable"O Apple Pay não abriu. Ofereça o cartão.
errorcode: "config_unavailable"O formulário não carregou. Confira a chave, o domínio e a liberação.
Depois de token, o iFrame fica em "Processando…" para sempre. Quem mostra o resultado é a sua página. Para tentar de novo, recarregue o src do iFrame.
A comunicação só vai do iFrame para a sua página. O iFrame não ouve mensagens.

4. Cobrar no seu servidor#

Use o mesmo corpo para cartão e Apple Pay. Só o token muda: ele começa com card_token. ou com apple_pay_token.. Veja todos os campos em Cobrar no cartão.
Reais aqui, centavos no iFrame. 19.90 na API é o mesmo valor que 1990 no iFrame.
Calcule o valor pelo pedido salvo, nunca pelo que veio do navegador.
Apple Pay: use installments 1 (ou omita o campo). O amount precisa ser exatamente o valor do iFrame. Se não for, a cobrança volta 422 e o token é gastado.
device.ip é o IP do comprador. Se o seu servidor está atrás de um proxy, pegue o IP do X-Forwarded-For.
O client_secret e o bearer ficam só no servidor. Nunca vão para a página.
O token do cartão vale 15 minutos, e o do Apple Pay vale 2 minutos. Os dois são de uso único. Cobre assim que receber.
Uma resposta 200 pode vir com transaction_id: null. Nesse caso, espere o webhook.

5. Confirmar o pagamento (webhook)#

1.
Cadastre um webhook do evento transaction, pelo painel (Developer API → Webhooks) ou por Criar webhook.
2.
Confira a assinatura X-SyncPay-Signature em cada entrega.
3.
Libere o pedido só quando o status for completed. Veja os outros status em Transação teve mudança de status.
Não use o webhook_url da cobrança. Ele manda o formato antigo, sem assinatura.
Nunca libere o pedido pelo postMessage. O token só prova que o cartão foi selado, não que o pagamento foi aprovado.
Se uma cobrança com Apple Pay voltar 5xx e a nova tentativa voltar 422 "Invalid or expired", a primeira pode ter sido aprovada. Espere o webhook transaction.updated antes de marcar o pedido como falho.

6. Apple Pay#

Só funciona no Safari 17 ou superior. Nos outros navegadores, o botão não aparece e o comprador vê só o cartão.
Precisa de três coisas: o Apple Pay liberado na sua conta, o domínio verificado (passo 1, item 4) e allow="payment" no iFrame.
A folha do Apple Pay fecha antes da cobrança. O iFrame mostra "Processando…" e a sua página mostra o resultado.

Checklist#

O iFrame de pagamento está liberado na conta
O domínio está cadastrado em Developer API → Chave pública
A URL do iFrame é montada no servidor, com amount em centavos
A página confere event.origin e data.source
O servidor cobra com o valor do pedido salvo, com device.metadata
Existe um webhook transaction, com a assinatura conferida
O pedido só é liberado em completed

Integrar com IA#

Passe para a sua IA o link https://syncpay.apidog.io/llms.txt e esta página. Ou copie o texto pronto da aba iFrame de pagamento no painel. Ele já vem com a sua chave e o seu domínio.
Modificado em 2026-10-23 21:03:01
Página anterior
Tokenização pública de cartão
Próxima página
Cobrar no cartão
Built with