Princípios básicos
Ambientes de teste e produção
Códigos de resposta
Erros
Criando uma transação
Para fazer uma cobrança você deve usar a rota /transactions para criar a sua transação, que pode ser feita por Cartão de crédito ou por Boleto bancário.
No caso de Cartão de crédito é possível utilizar um card_id, card_hash ou todos os dados do cartão diretamente. A segunda opção é a mais indicada, por fatores de segurança.
Objeto transaction (transação)
Objeto billing (dados de cobrança)
Objeto shipping (dados de envio)
Objeto items (itens)
Objeto address (endereço)
Objeto documents (documentos)
Status das transações
Capturando uma transação posteriormente
Essa rota é utilizada para capturar uma transação, após aprovada, utilizando o token ou o ID da transação.
Estorno de transação
Essa rota é utilizada quando se deseja estornar uma transação realizada por uma cobrança via Cartão de crédito ou Boleto bancário.
Em caso de estorno de uma transação realizada com Cartão de crédito, apenas o ID da transação é necessário para efetivação do estorno.
Caso a compra tenha sido feita por boleto bancário, você precisa informar os dados da conta bancária que irá receber o valor estornado ou o ID desta conta, que pode ser gerado através da rota /bank_accounts
.
Estorno Parcial de uma transação
O estorno parcial obedece as mesmas regras de um estorno total, e usa o parâmetro amount
como referência para o valor a ser estornado. É bom observar que o status da transação vai permanecer paid
até que o valor total da transação tenha sido estornado.
Caso a compra tenha sido feita por Boleto bancário, você precisa informar os dados da conta bancária que irá receber o valor estornado ou mesmo o id
desta conta, que pode ser gerado através da rota /bank_accounts
.
Estorno parcial com split
Além de estornos parciais regulares, em que você pode especificar apenas o valor, existe também o estorno com split. Neste caso, é possível especificar quanto e quem será responsável pelo valor sendo estornado. Isto é particularmente importante para quando parte da venda não foi finalizada ( e.g: produto devolvido), e o respectivo valor precisa ser estornado, mas somente do recebedor responsável. A seguir alguns exemplos de como executar esta operação.
Vale ressaltar que caso a transação seja por boleto, a regra de estorno permanece, e torna-se necessário enviar os dados de conta bancária de quem deve receber o estorno.
Retornando transações
Retorna um Array contendo objetos de transações, ordenadas a partir da transação realizada mais recentemente.
Retornando uma transação
Retorna os dados de uma transação em específico, com as informações em um único objeto.
Retornando recebíveis de uma transação
Retorna um array com objetos recebíveis (payables). Os recebíveis são os dados de pagamento referentes a uma transação.
Retornando um recebível da transação
Retorna um objeto recebível (payable) informando os dados de um pagamento referente a uma transação em específico.
Retornando histórico de uma transação
Retorna todo o histórico de uma transação, ou seja, toda e qualquer operação que já aconteceu com ela.
Ex: autorização, análise antifraude, captura, estorno, chargeback, emissão de boleto, conciliação, etc.
Tipos de operações
Notificando cliente sobre boleto a ser pago
Envia o link de um boleto pendente para o cliente.
Retornando eventos de uma transação
Retorna todos os eventos de mudança de status de uma transação.
Calculando Pagamentos Parcelados
Essa rota é utilizada para calcular o valor de cada uma das parcelas de uma compra e o valor final após aplicar os juros.
Testando pagamento de Boletos
Usado apenas em ambiente de Teste para simular o pagamento de um Boleto.
Gerando uma nova chave para encriptação do card_hash
Caso você queira/precise criar o card_hash
manualmente, essa rota deverá ser utilizada para obtenção de uma chave pública de encriptação dos dados do cartão de seu cliente.
Gerando card_hash manualmente
O card_hash representa uma versão criptografada das dados holder_name, expiration date, cvv, e number de um cartão. Nesta seção você vai aprender mais sobre como o hash é criado, e quais algoritmos utilizar.
Retornando estornos
Retorna os dados de todos os estornos realizados pela sua companhia.
Objeto de resposta
Criando um cartão
Você pode armazenar os dados do cartão do seu cliente através da rota /cards, assim você poderá usar o id do objeto gerado para realizar futuras transações, no lugar do card_hash.
Objeto cartão
Sempre que você faz uma requisição através da nossa API, nós guardamos as informações do portador do cartão, para que, futuramente, você possa utilizá-las em novas cobranças, ou até mesmo implementar features como one-click-buy.
Cobrança de R$1,23
Retornando cartões
Use a rota /cards/ para retornar todos os cartões salvos
Retornando um cartão salvo
Use a rota /cards/:id
para retornar os dados de um cartão previamente criado.
Criando Planos
Objeto Plano
Representa uma configuração de recorrência a qual um cliente consegue assinar.
É a entidade que define o preço, nome e periodicidade da recorrência
Retornando planos
Retorna todos os planos previamente criados levando em consideração os filtros e a paginação
Retornando um plano
Retorna um plano previamente criado.
Atualizando um plano
Atualiza um plano previamente criado
Criando assinaturas
Para efetivamente cobrar seu cliente de forma recorrente, você deve criar uma assinatura atrelada a um plano, que então conterá os dados de cobrança.
A criação de uma subscription (assinatura) é parecida com a criação de uma transação. Se for uma assinatura paga com Cartão de crédito, é possível usar um card_id, card_hash ou todos os dados do cartão. Para pagamento por Boleto bancário, você precisa especificar apenas o payment_method.
Objeto Assinatura
Esse objeto contém os dados das assinaturas geradas pelo seu sistema, que são atreladas a um plano.
Split com assinatura
Além de cobrar o seu cliente de forma recorrente, você também pode dividir as transações resultantes dessas assinaturas, entre dois ou mais recebedores de sua company. Os parâmetros a serem passados, além dos já existentes e explicados na seção anterior, são o conjunto split_rules
:
Retornando uma assinatura
Essa rota é utilizada para retornar os dados de uma determinada assinatura.
Retornando assinaturas
Essa rota é utilizada para retornar os dados de todas assinaturas.
Atualizando uma assinatura
Após criar uma assinatura, você pode atualizar os dados do método do pagamento e o plano que essa assinatura está atrelada.
Cancelando uma assinatura
Para cancelar uma assinatura você deve utilizar a rota /subscriptions/:id/cancel
Transações de assinatura
Retorna um array de objetos transaction contendo as transações feitas a partir de uma assinatura.
Pulando cobranças
Pula as x próximas cobranças de uma assinatura . Funciona apenas para assinaturas com status unpaid
ou pending_payment
Objeto-resposta Postback
Reenvio de postback
Com essa rota você pode reenviar qualquer postback que pertença a uma transação ou assinatura.
Lista de postbacks
Retorna todos os postbacks enviados, que estejam relacionados a transações ou assinaturas.