Zoop Developer Center

Bem-vindo ao hub do desenvolvedor Zoop. Você encontrará guias da API e uma documentação abrangente para ajudá-lo a começar a trabalhar com a Zoop o mais rápido possível, além de ajudá-lo se você tiver algum problema. Vamos lá!

Documentação

Dúvidas frequentes (FAQ)

Ao criar uma transaction tipo boleto, algo (email, etc) será enviado ao buyer?

R: Nas transações por boleto não realizamos nenhuma comunicação com o comprador, fica a cargo do marketplace fazer essa comunicação.

Existe alguma forma de configurar transferências diárias automáticas (quando houver saldo)?

R: Na configuração do marketplace podemos definir que o pagamento é feito automaticamente para o seller, ou seja, sempre que existir recebível de cartão/boleto para liquidar, é gerado automaticamente uma transferência bancária para a conta informada no cadastro do estabelecimento. Temos também a opção de pagamento manual, onde o saldo é gerado na conta zoop do estabelecimento, sendo necessário depois ele solicitar via api/portal um "saque" para sua conta bancária.

Os webhooks são configurados por marketplace ou eu conseguiria configurar uma URL de webhook por seller? Ou melhor ainda, poderia enviar uma URL de webhook por transaction?

R: Os webhooks são configurados por marketplace e tipo de evento, no caso de vocês seria um marketplace na zoop. No postback que fazemos para a url configurada no webhook do evento, vão todos os dados da transação, incluindo o id dela e os metadatos criados por vocês no momento do charge, sendo o seu sistema responsável por pegar estes dados e alterar os estados no seu lado.

O boleto criado é de qual banco? É registrado?

R: O boleto é registrado, do banco itaú.

Eu imagino que o valor fixo a ser cobrado pela Zoop por boleto recebido será descontado do valor recebido, e o restante fica disponível para transferência. É isso?

R: Correto, no momento da configuração do marketplace é definido um plano de recebimento, onde fica definido o valor negociado para cobranças por boleto, gerando um saldo para o estabelecimento no valor líquido, descontado a taxa definida.

Há forma de participar desse split, por exemplo, tirando X da Zoop, Y do parceiro, e liberando somente o saldo final ao seller?

R: Sim, existe. Todo marketplace é também um seller na nossa plataforma, podendo receber e vender.. poderíamos deixar pré-configurado no plano de recebimento do marketplace de vocês um valor fixo (percentual ou absoluto) para ser aplicado sob a transação, gerando um recebível do tipo comissão para o seller da dropo no valor da taxa. Neste modelo o fee de vocês ficaria fixo e aplicado para toda transação... existe também um outro modelo que chamamos de split, onde posse ser definido um regra de divisão (percentual ou absoluta) da venda entre diferentes estabelecimentos, sendo possível dessa maneira variar a taxa cobrada a critério de vocês.

No caso da criação de um bank account, há alguma conferência ou obrigação de a conta pertencer ao seller associado? Pergunto isso por questões de risco de fraude.

R: Sim, a conta bancária precisa ser de propriedade do estabelecimento, com o mesmo cpf/cnpj informado. Não é possível receber em um conta bancária cujo cpf/cnpj seja diferente do informado no cadastro do estabelecimento.

A API e demais recursos de emissão e recebimento de boleto já estão estáveis e disponíveis para uso imediato em produção?

R: Sim. Todos os serviços descritos acima estão em operação já há bastante tempo, sendo usados por diferentes clientes e tipos de negócio.

É possível cobrarmos alguma coisa da conta do seller na zoop? Ou seja, se ele tem um saldo de R$100,00 , quero cobrar dele uma taxa de R$10,00 (sem um pagamento associado). É possível?

R: No nosso modelo de marketplace, o administrador do marketplace também possui um seller próprio cadastrado na plataforma, sendo que você tem controle total sobre as contas dos estabelecimentos cadastrados na rede vocês. Para fazer esta cobrança na conta de um estabelecimento, bastaria realizar uma transferência da conta dele para a conta do seller principal através da API de transfers.

Vocês tem a opção de late capture no cartão não presente? Na documentação não aparece essa opção.

R: Temos sim, são as APIs de pre-authorization de cartão não presente.

Quando cobro um fee no pagamento, esse fee vai para a conta do marketplace, é isso? A conta do próprio marketplace tem as mesmas funções de um seller para controlar transferência, etc?

R: Conforme respondido no item 1, o marketplace possui uma conta de seller principal, com as mesmas características de qualquer outro seller do marketplace. O seller pode escolher entre receber automaticamente seus recebíveis, sendo que neste caso fazemos a liquidação em conta bancária ou cartão pré-pago escolhida, ou então ele pode escolher a opção de recebimento manual, onde o saldo fica acumulado na conta "zoop" dele, sendo necessário gerenciar manualmente as transferências para outras contas zoop, ou então fazendo uma transferência de "saque" para a própria conta bancária.

Como consigo saber quando uma transação de cartão de crédito vai ser paga pelo adquirente? Como vejo se ela já está na conta do seller.

R: A ZOOP opera no modelo de sub-adquirência, diferente de outros gateways do mercado que funcionam somente como van, nós gerenciamos a agenda de recebimentos do estabelecimento independente da agenda de pagamentos da adquirente utilizada na venda. Nós fazemos a liquidação para os estabelecimentos de acordo com a condição vinculada ao plano de recebimento escolhido no momento da venda. Temos dois serviços na API, um para consultar a agenda de recebimentos futuros do seller, e outra para listar os pagamentos realizados, sendo também informado a data de previsão de recebimento no objeto transaction, no atributo expected_on.

Como controlo quem deve pagar o chargeback, marketplace ou seller?

R: No nosso modelo comercial, a responsabilidade pelo chargeback é primeiro do estabelecimento, sendo descontado automaticamente dos próximos recebimentos. No caso de um estabelecimento receber um chargeback e depois encerrar sua operação, não realizando novas vendas, esta responsabilidade recai sobre o marketplace, que pode ter que honrar o débito.

Como recebemos o chargeback, não existe um webhook para isso?

R: A comunicação dos chargebacks é feita através de rotina no nosso backoffice, podendo ser encaminhado o email diretamente para o estabelecimento final ou então para o backoffice do marketplace. O encaminhamento da contestação por parte do estabelecimento/marketplace também é feita através de rotina de backoffice. Estamos trabalhando em uma API para amarrar este fluxo, está em desenvolvimento ainda.

Supondo que no acordo comercial do marketplace principal com os seus sellers, alguns clientes absorvem o chargeback, teria como configurar dessa maneira? Para todos os chargebacks virem para o marketplace.

R: Sim, nós conseguimos definir um percentual de responsabilidade do marketplace no chargeback das vendas dos sellers dele. No caso de vocês vamos configurar como 100%, assim o valor será sempre descontado no saldo do seller admin.

Na criação de Bank Account, tem uma propriedade chamada routing_number. Essa é a agência? Não precisa do digito verificador da agência? Não achei o campo para tal.

R. isso mesmo, o routing_number é a agência, sem dígito verificador... um detalhe importante sobre o account_number, coloque o numero da conta com o digito verificador na última posição a direita, sem espaço ou traço.

O pagamento (e alguns outros) tem um possível status Expired, que indica que uma operação foi "abandonada" no status New. Como funciona isso?

R. Quando uma solicitação de autorização é feita, o registro da transação é criado com status new, e a requisição de autorização (o post no /transactions) fica em waiting até que a transação seja aprovada (succeeded) ou negada (failed) no emissor, sendo o tempo máximo deste processamento 40s. Quando o emissor demora mais do que este tempo para responder, ou então a comunicação é perdida por qualquer motivo, você recebe um HTTP Error 408 na requisição, e a transação entra na fila para ser revertida. O processo de desfazimento é uma rotina automática que garante que a transação seja desfeita no emissor, sendo o status da transação alterado para reversed quando temos a confirmação do desfazimento do emissor. Na prática este status de expired não ocorre.

Sobre o processo de ativação de Sellers, qual é o prazo? Existe alguma ação pela parte do parceiro?

R. O processo de ativação de um estabelecimento é feito em duas etapas, sem necessidade de nenhuma ação por parte do parceiro, a não ser o próprio cadastro; na primeira etapa fazemos uma validação completa dos dados cadastrais, geralmente entre 1 e 3 dias a partir do cadastro, no caso do cadastro ser liberado ele vai para o status enabled e o seller já pode começar a transacionar, ficando pendente ainda a segunda etapa da ativação, caso seja rejeitado na primeira etapa, o parceiro é notificado para verificar as informações cadastrais; na segunda etapa a aprovação do cadastro é finalizada, geralmente entre 1 e 5 dias a partir do cadastro, e sendo liberado o processo é finalizado e o status do seller vai para active, caso seja rejeitado o status volta para pending e o parceiro é notificado via backoffice sobre o problema, ficando o estabelecimento impedido de transacionar.

No caso do seller fazer um saque da conta Zoop. Ele só pode transferir para uma conta PJ no CNPJ dele? Ou qq conta bancária (PF ou PJ)?

R: A conta bancária utilizada deve ser obrigatoriamente de titularidade do seller, fazemos uma verificação pelo CPF/CNPJ do estabelecimento.

No caso o cartão BPP é um cartão emitido da nossa conta com a BPP e não da conta Zoop com a BPP. Pelo q vi vc só pediu pra eu passar o cardId do cartão. Somente com essa info vc será capaz de fazer a carga nesse cartão que está na nossa conta da BPP?

R: Entramos em contato com a BPP para verificar a possibilidade deles liberarem a conta de vocês para que possamos efetuar a carga nos cartões. Estamos aguardando uma resposta, acredito que seria possível sim.

Quem faz o processo de underwriting para passar o seller de pending para enabled ou active? Vcs ou nós?

R: O processo de ativação de um estabelecimento é feito em duas etapas, sem necessidade de nenhuma ação por parte de vocês a não ser o próprio cadastro; na primeira etapa fazemos uma validação completa dos dados cadastrais, geralmente entre 1 e 2 dias a partir do cadastro, no caso do cadastro ser liberado ele vai para o status enabled e o seller já pode começar a transacionar, ficando pendente ainda a segunda etapa da ativação, caso seja rejeitado na primeira etapa vocês são notificados para verificar as informações cadastrais; na segunda etapa a aprovação do cadastro é finalizada, geralmente entre 1 e 5 dias a partir do cadastro, e sendo liberado, o processo é finalizado e o status do seller vai para active, caso seja rejeitado o status volta para pending e vocês são notificados via backoffice do problema, ficando o estabelecimento impedido de transacionar.

Se nós fizermos o underwriting, aonde ativamos esse cadastro?

R: conforme respondido no item anterior, este processo é responsabilidade da zoop

Se vcs fazem o underwriting, temos que enviar documentação? Existe alguma coisa na API ou Dashboard?

R: O cadastro do estabelecimento e o envio da documentação podem ser feitos via portal de serviços que será disponibilizado na conta de vocês, ou então através das APIs de seller e document. Iremos encaminhar para você a especificação. Através dos webhooks, vocês conseguem também configurar um serviço do lado de vocês para ser notificado na mudança de estado do seller.

Pra que ele consiga cobrar, o underwriting tem que ter sido finalizado? Pq pelo que vi vc tem o status enabled pra permitir que ele já cobre até ser efetivamente aprovado

R: Correto. Para que o seu usuário comece a vender, ele precisa ter o cadastro aprovado pela zoop. Recomendamos que vocês cadastrem o estabelecimento na zoop, e aguardem o credenciamento, conforme respondido no item 1 a primeira etapa acontece em até 2 dias úteis, e só após o seller estar enbaled é que você enviaria a maquininha.

Pelo que entendi da API, o nosso usuário não precisa ter uma conta de recebimento cadastrada para começar a cobrar? Daí o dinheiro ficaria disponível na conta Zoop dele dentro do nosso marketplace?

R: Correto. Uma vez habilitado, o seller já pode começar a transacionar, sendo gerado um saldo na conta zoop dele a medida que os recebíveis vão vencendo.

Quanto tempo o dinheiro ficaria disponível na conta recebimento ou na conta Zoop dele? Tem como configurar a nível de API quando ele vai receber (com antecipação ou sem antecipação)?

R: Por padrão, a liquidação dos recebíveis é feita diariamente para a conta bancária do estabelecimento desde que ele tenha configurado uma conta para recebimento. Caso ele não tenha conta bancária cadastrada, o saldo fica acumulado por tempo indeterminado. Podemos configurar a frequência com que o pagamento é feito para o seller, o padrão é diário, porém podemos configurar, semanal, ou mensal.

Em caso do dinheiro ficar na conta Zoop, o usuário que teria que pedir uma transferência para conta de recebimento da sua escolha qnd o dinheiro ficasse disponível?

R: Conforme respondido no item anterior, por padrão a liquidação é automática para conta bancária dele. Existe também a opção de não habilitar esta liquidação automática, ficando o saldo acumulado na conta do seller até que ele faça uma "saque" para a conta bancária. Assim como todas as outras funções, isso poderia ser feito também via API.

Vc poderia me indicar quais são os campos que tenho que usar pra fazer com que a conta de recebimento do nosso usuário seja o nosso cartão na BPP?

R: Basta criar um bank_account com as informações a seguir, e depois associar o token criado com o customer. Para usar um Cartão BPP, basta informar na criação do bankaccount o bank_code=10001, routing_number=0001 e account_number=<identificador do cartão na BPP, conforme vêem na carta berço - por exemplo no cartão *1181201-1254952* o identificador é tudo que vem após o '-', 1254952>.

Conseguimos criar subcontas que armazenam os valores e só resgatar quando solicitado?

R: No modelo da zoop não existe necessidade de criação de subconta. Todo seller criado dentro de um marketplace possui por padrão uma conta zoop, onde todos os recebíveis são creditados podendo ficar o saldo disponível para resgate/saque sob demanda.

Na configuração do marketplace de vocês temos habilitado somente o modelo de liquidação automático, onde todo saldo disponível é automaticamente transferido para a conta bancária associada ao seller, mas poderíamos habilitar também o modelo do sob demanda.

Conseguimos fazer transferências entre subcontas?

R: Existe a possibilidade de fazer transferências entre sellers do mesmo marketplace, informando somente o seller_id (que é o recipient da transfer) e o sender_id (id do seller que será debitado).

No momento só permitimos a liquidação direta em conta bancária, ou seja, ao criar esta transfer, o sender será debitado se tiver saldo, e o recipient receberá na conta bancária definida como default para ele. Estamos trabalhando em uma feature que vai permitir que o saldo seja movimentado entre contas zoop, sem liquidação direta em conta bancária.

Você pode utilizar a API de Transfers

Existe a possibilidade de divisão dos valores de uma transação?

Todo marketplace é também um seller na nossa plataforma, podendo receber e vender.. poderíamos deixar pré-configurado no plano de recebimento do marketplace de vocês um valor fixo (percentual ou absoluto) para ser aplicado sob a transação, gerando um recebível do tipo comissão para o seller da ipag, por ex, no valor da taxa. Neste modelo o fee de vocês ficaria fixo e aplicado para toda transação.

Existe também um outro modelo que chamamos de split, onde posse ser definido um regra de divisão (percentual ou absoluta) da venda entre diferentes estabelecimentos, sendo possível dessa maneira variar a taxa cobrada a critério de vocês.

Quero listar em um grid todos os 'sellers', porém com uma coluna indicando o plano tarifário dele. Na função que lista os sellers não encontrei como obter o pacote tarifário do seller.

R: GET /v1/marketplaces/:marketplace_id/sellers/:id/subscriptions

Você vai receber o plano associado ao estabelecimento, caso ele tenha selecionado algum. Se retornar vazio, é porque ele está no plano default definido por você.

Em transações, qual a diferença entre os campos abaixo?

"expected_on": "2017-08-21T22:11:18+00:00",
e
"created_at": "2017-08-21T23:57:56+00:00",

R: expected_on : data prevista do crédito em conta zoop, desta transação

created_at : data de criação em UTC 0

Em transações, a API retorna um array de taxas como no exemplo abaixo. Não entendi o porque de ser um array. Cada cliente não está associado a apenas um plano?

"fee_details": [
{
"amount": "1.83",
"prepaid": true,
"currency": "BRL",
"type": "custom_credit_fee_d0",
"description": "Custom prepaid card-present credit fee"
},
{
"amount": "2.06",
"prepaid": true,
"currency": "BRL",
"type": "zoop_custom_credit_fee_d0",
"description": " Zoop Custom prepaid card-present credit fee"
}
]

R: GET /v1/marketplaces/{marketplace_id}/subscriptions/
No nosso caso, o plano possui 2 taxas: a taxa Zoop e o Markup do parceiro. Ambas estão descritas.

Você pode utilizar a API de Split