Referência do SDK

O assiny.js é o SDK do navegador do Assiny Gateway. Esta página lista tudo o que ele expõe; o que não está aqui não existe.

CarregarCopiar o link da seção

<script src="https://sdk-gateway-js.assiny.com.br/v1/assiny.js"></script>

Só pela tag. O script define a função global Assiny.

Nada lançaCopiar o link da seção

Nenhuma função lança exceção e nenhuma promessa rejeita. Argumento inválido vira o evento loaderror (assíncrono, depois do mount) ou { error } na promessa. Uma exceção dentro de uma função sua passada a on() vai ao console.error e não para o SDK. Se a criação da instância falhar de forma inesperada, Assiny() devolve uma instância que não monta nada e responde { error } com unknown a toda promessa.

Assiny(publishableKey, options)Copiar o link da seção

const assiny = Assiny('pk_test_...', { locale: 'pt-BR' });

Devolve a instância { fragments, createPaymentMethod, handleNextAction }. Com a chave aceita, Assiny() acrescenta ao body dois iframes invisíveis do SDK, que ficam na página; o recomendado é uma instância por página.

Chave recusada: nenhum iframe nasce, o mount emite loaderror com o código e toda promessa resolve { error } com ele.

assiny.fragments(options)Copiar o link da seção

O objeto que assiny.fragments() devolve é o Fragments; o que fragments.create('payment') devolve é o Payment Fragment. As mensagens de erro usam esses dois nomes.

const fragments = assiny.fragments({
  mode: 'payment',
  amount: 12990,
  currency: 'brl',
  clientSecret, // opcional
  appearance, // opcional
  fonts, // opcional
});

Devolve { update, create }. Opção inválida não lança: o código chega pelo loaderror do mount. amount, currency e clientSecret se corrigem com fragments.update(): o fragment guarda o seletor do mount e monta quando o valor fica válido. mode não muda depois.

• Um por instância: o segundo assiny.fragments() devolve um objeto cujo create() dá loaderror fragment_already_exists no mount e cujo update() resolve { error } com o mesmo código.
• O PIX exige currency: 'brl': com 'pix' em paymentMethodTypes e outra moeda, o mount emite payment_method_types_invalid.
• appearance e fonts entram só aqui; não há como trocá-los depois na mesma instância.

fragments.update(options)Copiar o link da seção

const { error } = await fragments.update({ amount: 15990 });

Resolve {} ou { error }. Com amount e parts juntos, a soma é conferida contra o amount novo; dois update seguidos valem em ordem. Outros códigos:

Chave desconhecida é ignorada, com aviso no console.

fragments.create('payment', options)Copiar o link da seção

const payment = fragments.create('payment', {
  paymentMethodTypes: ['card', 'pix'],
  combine: 'auto',
  partsFrom: 'component',
  fields: { billingDetails: { name: 'auto', address: { country: 'auto' } } },
  wallets: { applePay: 'auto' },
});

Devolve { mount, unmount, on, off }. O primeiro argumento só aceita 'payment'. Os erros da criação chegam pelo loaderror do mount:

Um create() com opções inválidas não ocupa o lugar do fragment da instância: um create() válido depois ainda funciona.

payment.mount(selector)Copiar o link da seção

payment.mount('#pagamento');

selector é um seletor CSS que casa com exatamente um elemento. O fragment ocupa 100% da largura dele e a altura acompanha o conteúdo. O ready sai uma vez por mount. Elemento removido do DOM conta como desmontado. Os erros chegam pelo loaderror:

payment.unmount()Copiar o link da seção

Remove o iframe do fragment e apaga o que foi digitado. Um createPaymentMethod em curso resolve { error } com fragments_not_ready. Depois, mount() monta de novo. Um handleNextAction em curso não para.

payment.on(event, handler) e payment.off(event, handler)Copiar o link da seção

Ligam e desligam uma função num evento e devolvem o próprio payment. Nome fora da lista, ou handler que não é função, é ignorado.

O payload do change:

Nenhum evento traz o que foi digitado no cartão.

assiny.createPaymentMethod({ fragments, params })Copiar o link da seção

const { parts, error } = await assiny.createPaymentMethod({
  fragments,
  params: { billing_details: { name, email, phone, tax_id, tax_id_type, address } },
});

• fragments: o objeto devolvido pelo assiny.fragments() desta instância.
• params.billing_details: os dados do pagador. Cada campo que você manda vale como veio, para todas as Partes; campo que você não manda entra do fragment se o campo correspondente está ligado ('auto') e preenchido: Nome no cartão em name, País em address.country, por cartão. Nada é sobrescrito; '', null e undefined contam como não mandado. No PIX, só o que você mandou. Chaves aceitas: name, email, phone, tax_id, tax_id_type e address com line1, line2, city, state, postal_code e country; outra chave é descartada, com aviso no console. Na política padrão, o pagador precisa de email no cartão e no PIX e de name no cartão; sem eles, a criação do método de pagamento ou o confirm recusa com payer_field_missing.

Resolve { parts: [{ method, amount, payment_method }] }, com method 'card' ou 'pix' e payment_method o pm_ criado, na ordem das Partes da aba selecionada (cartão ou PIX: uma Parte com o amount inteiro; Combinar: duas, que somam o amount), ou { error: { type, code, message, part } }, com part só quando a falha é de uma Parte.

O que acontece:

• O fragment confere os campos da aba selecionada; campo incompleto ou inválido resolve um validation_error sem ir à API e mostra o erro no campo.
• Enquanto os métodos são criados, os campos ficam desligados (.Input:disabled).
• Um pm_ por Parte, em ordem; a primeira falha interrompe as seguintes e o erro diz em part o índice da Parte que falhou.
• Depois de um { error }, o que foi digitado fica e o campo que a API apontou fica marcado; na nova tentativa, a Parte que não mudou reusa o pm_ já criado. Depois de um sucesso, a próxima chamada cria pm_ novos.

assiny.handleNextAction({ clientSecret })Copiar o link da seção

const { paymentIntent, error } = await assiny.handleNextAction({
  clientSecret: 'pi_..._secret_...',
});

• clientSecret: o client_secret do pagamento, na forma pi_..._secret_.... O da chamada vence o guardado por assiny.fragments({ clientSecret }) ou fragments.update({ clientSecret }).
• Funciona só com a instância de Assiny(): não precisa do fragment montado.

O SDK lê o pagamento a cada 3 s e segue o próximo passo, uma ação por vez, até o fim:

Esc ou Fechar na tela do QR param a leitura e resolvem { paymentIntent } com o estado da última leitura, em geral requires_action; uma nova chamada reabre a ação atual. Até a primeira leitura há 20 s; depois, a promessa vive enquanto a leitura vive.

Resolve:

{
  "paymentIntent": {
    "id": "pi_...",
    "object": "payment_intent",
    "livemode": false,
    "status": "succeeded",
    "amount": 12990,
    "currency": "brl",
    "parts": [
      { "id": "pip_...", "position": 1, "method": "pix", "amount": 12990, "status": "succeeded" }
    ],
    "last_payment_error": null
  }
}

parts traz id, position, method, amount e status de cada Parte; last_payment_error é { type, code, message } ou null. Sem next_action e sem os outros campos do pagamento.

Depois da primeira leitura, uma leitura que falha não encerra: o SDK tenta na volta seguinte e, depois de três falhas seguidas, a tela do QR mostra "Sem conexão. Tentando de novo.".

PrazosCopiar o link da seção

ErrosCopiar o link da seção

{ type, code, message }, e part quando a falha é de uma Parte no createPaymentMethod. A message vem do catálogo do SDK, no locale da instância, nunca do servidor. A lista é fechada: um código fora dela chega como api_error unknown.

Respostas da APICopiar o link da seção

Como o SDK traduz a resposta da API em type e code. A message do servidor nunca é lida.

Na criação de cada pm_ (createPaymentMethod):

Na leitura do pagamento (handleNextAction):

Na leitura, o erro só encerra o handleNextAction na primeira leitura; nas seguintes, o SDK tenta de novo.

Avisos no consoleCopiar o link da seção

Os avisos saem só em pt-BR, com o prefixo [Assiny], e nunca trazem o que foi digitado.