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    Referência da API

Métodos de Cobrança

Utilize as APIs de Cobrança cartão não presente da Zoop para realizar diferentes tipos de cobrança em nome dos vendedores do seu marketplace.

Com os dados de cartão tokenizados de maneira segura e associado à um comprador, você pode realizar uma cobrança do tipo card totalmente segura , ou então utilizar estes dados para realizar uma cobrança futuramente com o tipo customer.

Ainda de posse do identificador de um comprador criado, você pode realizar cobranças recorrentes, debitar diretamente a conta de pagamento do comprador através da cobrança tipo wallet, ou realizar cobranças do tipo boleto.

Configuração dinâmica de statement descriptor

Por padrão o statement descriptor (nome fantasia) configurado na conta do vendedor será exibido na fatura do comprador quando uma venda for realizada. Caso um statement descriptor não esteja configurado na conta do vendedor, será utilizado a razão social, no caso de conta PJ, ou nome completo, no caso de conta PF.

É possível realizar uma configuração dinâmica do statement descriptor por transação, bastando para isso incluir o parâmetro na chamada de api para criação de venda.

O statement descriptor é limitado à 22 caracteres, não devendo utilizar caracteres especiais ou somente números.

curl --request POST \
    --header "Content-Type: application/json" \
    --user zpk_test_EzCkzFFKibGQU6HFq7EYVuxI: \
    --url https://api.zoop.ws/v1/marketplaces/3249465a7753536b62545a6a684b0000/transactions \
    --data '{    
        "amount": 7,
        "currency": "BRL",
        "description": "venda",
        "on_behalf_of": "5715c67929994f919a21f1323e407e11",
        "customer": "c07ee65cda84495787cd091fea554549",
        "statement_descriptor": "LOJA JOAO",
        "payment_type": "credit"
    }'

Armazenando dados na transação

Você pode armazenar dados de referência nas transações criadas de maneira a facilitar a busca e conciliação das vendas com seu sistema.

Suportamos dois modelos de armazenamento de dados. Você pode enviar informações através do campo metadata, um campo chave / valor, sendo estes dados registrados na venda e retornados nas chamadas de api de transactions.

Uma forma aconselhável de registrar dados na transação é através do atributo reference_id. Através deste campo você pode enviar um identificador do pedido no seu sistema, sendo possível realizar um filtro de transações pelo id de referência nas apis ou no dashboard.

curl --request POST \
    --header "Content-Type: application/json" \
    --user zpk_test_EzCkzFFKibGQU6HFq7EYVuxI: \
    --url https://api.zoop.ws/v1/marketplaces/3249465a7753536b62545a6a684b0000/transactions \
    --data '{    
        "amount": 7,
        "currency": "BRL",
        "description": "venda",
        "on_behalf_of": "5715c67929994f919a21f1323e407e11",
        "customer": "c07ee65cda84495787cd091fea554549",
        "statement_descriptor": "LOJA JOAO",
        "reference_id": "10001",
        "payment_type": "credit",
        "metadata": {
            "my-own-tid": "12345"
        }
    }'

Cancelamento total e parcial

No cancelamento de um transação do tipo card uma solicitação de estorno é feita ao emissor do cartão, sendo gerado um crédito na fatura do comprador referente ao valor estornado.

Uma vez aprovado o cancelamento a transação é atualizada para o status de canceled, sendo emitido um evento do tipo transaction.canceled, sendo canceladas também as parcelas de recebimento associadas a transação não compensadas. Um lançamento de débito no extrato financeiro do lojista para as parcelas de recebimento já liquidadas também é realizado.

Estorno de venda liquidada

Para realizar o estorno de vendas já liquidadas deve ser feita uma solicitação especial de liberação em nome do marketplace/estabelecimento comercial, não sendo possível realizar este tipo de estorno sem uma liberação prévia.

Cancelamento parcial

O cancelamento parcial é o ato de cancelar um valor menor que o valor total autorizado/capturado. Esse modelo de cancelamento pode ocorrer inumeras vezes, até que o valor total da transação seja cancelado.

Cancelamento parcial disponível apenas para transações de crédito capturadas.

Ao cancelar parcialmente uma transação, o amount estornado é reduzido do valor atual da venda, ficando o valor original_amount preservado com o valor original da venda, sendo regerado os recebíveis associados a esta venda, retornando erro caso uma regra de split ultrapasse o valor restante da venda após cancelamento.

No cancelamento parcial, o estado da venda permanece como succeeded enquanto restar valor amount a ser creditado ao EC. A venda passa para o estado de canceled quando o valor amount for zero.

No cancelamento parcial é também disparado o evento de transaction.canceled , porém mantendo o objeto da venda no estado de succeeded.

Para cada operação de cancelamento é registrado um histórico que pode ser visualizado nas apis de transactions.

Na API de cancelamento de cobrança deve ser enviado o valor a ser estornado, podendo ser o valor total ou parcial, enviando também novamente o identificador do vendedor no atributo on_behalf_of.

curl --request POST \
    --header "Content-Type: application/json" \
    --user zpk_test_EzCkzFFKibGQU6HFq7EYVuxI: \
    --url https://api.zoop.ws/v1/marketplaces/3249465a7753536b62545a6a684b0000/transactions/8220f8807b0c4920aa576afc53f0d6f9/void \
    --data '{    
        "amount": 7,
        "on_behalf_of": "5715c67929994f919a21f1323e407e11"
    }'

Captura total e parcial

Na captura de um transação do tipo card uma solicitação de captura é feita ao emissor do cartão, sendo confirmado o débito na fatura do comprador referente ao valor enviado.

Uma vez aprovada a captura a transação é atualizada para o status de succeeded, sendo emitido um evento do tipo transaction.succeeded, sendo gerado as parcelas de recebimento associadas a transação.

Caso uma chamada de captura retorne com falha é recomendado que seja feito uma nova tentativa, em outro momento.

Prazo para captura

O prazo padrão entre a aprovação de uma pre autorização e a sua captura é de 7 dias, não sendo possível a realização de captura após esse período sem uma liberação prévia.

Captura parcial

A captura parcial é o ato de capturar um valor menor que o valor autorizado. Esse modelo de captura pode ocorrer apenas 1 vez por transação.

Após uma captura realizada com sucesso, não é possível realizar capturas adicionais na mesma transação.

Por padrão as cobranças de cartão de crédito realizadas possuem o parâmetro de capture setado, indicando para a plataforma da zoop que a transação deve ser imediatamente captura, não sendo possível realizar uma captura posteriormente. Para realizar uma venda do tipo pré-autorização, onde o saldo fica reservado, basta enviar o atributo capture como false na requisição de transação.

curl --request POST \
    --header "Content-Type: application/json" \
    --user zpk_test_EzCkzFFKibGQU6HFq7EYVuxI: \
    --url https://api.zoop.ws/v1/marketplaces/3249465a7753536b62545a6a684b0000/transactions \
    --data '{    
        "amount": 7,
        "currency": "BRL",
        "description": "venda",
        "on_behalf_of": "5715c67929994f919a21f1323e407e11",
        "customer": "c07ee65cda84495787cd091fea554549",
        "capture": false,
        "payment_type": "credit"
    }'

Na API de captura de cobrança deve ser enviado o valor a ser capturado, podendo ser o valor total ou parcial, enviando também o identificador do vendedor no atributo on_behalf_of.

curl --request POST \
    --header "Content-Type: application/json" \
    --user zpk_test_EzCkzFFKibGQU6HFq7EYVuxI: \
    --url https://api.zoop.ws/v1/marketplaces/3249465a7753536b62545a6a684b0000/transactions/8220f8807b0c4920aa576afc53f0d6f9/capture \
    --data '{    
        "amount": 7,
        "on_behalf_of": "5715c67929994f919a21f1323e407e11"
    }'

Fluxo de Disputa e ChargeBack

No momento em que o portador do cartão recebe a sua fatura do cartão de crédito, normalmente ele verifica as suas compras. Caso o portador não identifique alguma compra, ele entra em contato com o banco emissor do seu cartão e o informa o não reconhecimento desta compra.
Com isso, o banco emissor do cartão abre junto a bandeira, o processo de disputa / chargeback.

Neste momento, a bandeira funciona como "juiz" desta disputa e pede à credenciadora algumas evidências como nota de entrega do produto, nota fiscal, recibo, etc...

Caso as evidências sejam suficientes, a credenciadora / sub-credenciadora / estabelecimento comercial ganha (m) esta disputa e recebe o valor, caso o contrário a credenciadora / sub-credenciadora / estabelecimento comercial arca (m) com o prejuízo.

Está liberado no sistema o cadastro dos eventos de transaction.charged_back, transaction.disputed e transaction.dispute.succeeded.

O fluxo para uso dos eventos segue abaixo:

  1. O cliente solicita ao emissor o estorno / cancelamento de uma transação;

  2. O emissor informa à adquirente e consequentemente à Zoop que esta transação foi contestada pelo cliente;

  3. A Zoop atualiza o status da transação para "dispute" e suspende os pagamentos de recebíveis a vencer associados a esta venda;

  4. A notificação sobre transações em disputa é realizada automaticamente pelo sistema através do disparo do evento de "transaction.disputed" devendo este evento ser monitorado pelo marketplace para a que possa atuar caso desejado;

  5. Caso o EC ou o Marketplace envie a documentação necessária por email para o [email protected] no prazo de 7 dias (corridos) a Zoop encaminha a documentação ao adquirente / emissor e aguarda o resultado do processo, que pode ocorrer no prazo de até 30 dias (corridos)

  6. Caso o retorno seja favorável ao EC, a Zoop é notificada, confirma o processo de disputa e dispara o evento "transaction.dispute.succeeded", altera o status da transação para 'succeeded' e remove a suspensão dos recebíeis pendentes de pagamento;

  7. Caso o retorno seja favorável ao comprador, ou a Zoop não receba retorno no prazo estipulado, o processo de disputa é encerrado e o status da transação é alterado em definitivo para "charged_back", sendo disparado o evento "transaction.charged_back" e realizado o debito na conta do EC ou do Marketplace, dependendo de quem for o responsável pelos chargebacks no contrato comercial

  8. Caso o Marketplace / EC não envie a documentação dentro do prazo, o processo de disputa é encerrado e o status da transação é atualizado em definitivo para "transaction.charged_back"

Estados de uma transação

new - Uma nova transação foi criada e as informações foram recebidas com sucesso para processamento.

pending - A transação foi encaminhada para processamento;

pre_authorized - Quando as Transações são emitidas com o parâmetro de captura como falso, uma pré-autorização é criada e precisará ser capturada mais tarde.

succeeded - O pagamento foi autorizado e valor estará disponível para recebimento pelo vendedor.

failed - A solicitação de autorização falhou ou foi negada pelo emissor do cartão.

reversed - Uma ocorre quando existe um problema na comunicação entre a solução de captura, no caso de venda CP, ou entre a plataforma da zoop e o autorizador, podendo ocorrer antes que a transação tenha sido confirmada, não acarretando em débito para o comprador, ou posterior a aprovação da compra junto ao emissor. Neste último caso o sistema de captura da zoop registra a falha e desfaz automaticamente a venda através de uma operação de estorno com retorno do crédito na fatura do comprador.

canceled - O pagamento foi cancelado / anulado pelo vendedor ou pelo aplicativo. As taxas cobradas originalmente também são anuladas.

dispute - Quando o titular do cartão envia uma queixa comunicando-se com o banco emissor sobre a transação errada, o banco emissor abre uma disputa com o comerciante, solicitando a documentação necessária e a prova para remediar o estorno. Se a documentação fornecida for satisfatória, a disputa é simplesmente recusada e o cliente é cobrado com uma taxa de processamento. Se os documentos parecem ser insatisfatórios, o montante do reembolso será fornecido ao cliente e o comerciante será debitado.

charged_back - O status indica que a cobrança foi contestada pelo comprador e o vendedor perdeu a disputa, sendo o valor total da venda debitado da conta do vendedor.

Updated about a year ago

Métodos de Cobrança


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.