Sua primeira transação

Introdução

A Zoop oferece uma plataforma com para que você possa oferecer soluções de pagamentos utilizando oferece diversas formas de pagamentos. Sejam pagamentos presenciais (utilizando uma maquininha/POS), boletos ou pagamentos digitais, a Zoop vai oferecer uma plataforma completa pra você.

Primeiros Passos na Zoop

Aqui você conhecerá o mínimo que você vai precisar para realizar uma transação em nossas APIs de pagamento digital e já conseguir começar a operar

URLs da API

https://api.zoop.ws/v1 - Versão atual da maior parte das APIs
https://api-beta.zoop.ws/v1 - Caso se trate de uma funcionalidade que ainda está em testes

Como temos algumas APIs em estágios diferentes, observe para confirmar que você está utilizando o endpoint correto.

Autenticação

Em nossas APIs utilizamos a autenticação conhecida como Basic Auth.

Para autenticar, você deverá utilizar a sua chave de acesso (conhecida como zpk). Uma diferença sobre como nós utilizamos o Basic Auth, é que não utilizamos o campo senha, do Basic Auth. Por isso, você deve inserir sua ZPK no campo usuário e deixar a senha em branco.

No processo de onboarding, você receberá um email contendo links para gerar duas chaves de acesso, uma para o ambiente de testes e outra para o ambiente de produção. Caso o link não esteja mais disponível e você não tenha mais sua chave, solicite ao suporte.

Para autenticar, você utilizará a chave recebida como username em seu cliente HTTP. Caso ele não tenha suporte a Basic Auth, você deverá adicionar um header HTTP, exemplo: Authorization: Basic enBrX3Rlc3RfRXpDa3pGRktpYkdRVTZIRnE3RVlWdXhJOg==

Neste tutorial estamos utilizando a seguinte chave de teste: zpk_test_EzCkzFFKibGQU6HFq7EYVuxI

Toda as chamadas devem utilizar HTTPS, caso contrário a API negará o acesso.

Segurança das chaves

Você deverá salvar as suas chaves de API, independentemente de qualquer coisa. NÃO COMPARTILHE suas chaves de API com ninguém, nem mesmo nos canais de suporte da Zoop. Nenhum funcionário da Zoop está autorizado a pedir sua chave de API ou qualquer outro dado sensível.

🚧

Transações direto do Front-end

Caso você pretenda realizar transações em um comercio eletrônico e não possui certificação PCI, você deverá realizar chamada para tokenização do cartão através do front-end entretanto você só deve utilizar uma chave que seja específica para esse fim. Solicite ao suporte uma chave específica caso seja necessário.

Criando um vendedor

Para realizar vendas, o seu marketplace precisa de vendedores cadastrados. Por isso, o primeiro passo para fazer uma venda na Zoop, é garantir que você já tem um vendedor cadastrado.

Para criar um novo você precisará de diversos dados como:

  • Nome
  • Sobrenome
  • Email
  • Telefone
  • Data de nascimento
  • CPF
  • Entre outros

Exemplo com uma pessoa física

Primeiramente criamos um vendedor pessoa física.

curl --request POST \
  --url https://api.zoop.ws/v1/marketplaces/3249465a7753536b62545a6a684b0000/sellers/individuals \
  --header 'accept: application/json' \
  --header 'authorization: Basic enBrX3Rlc3RfRXpDa3pGRktpYkdRVTZIRnE3RVlWdXhJOg==' \
  --header 'content-type: application/json' \
  --data '{ 											
   "first_name":"João", 								
   "last_name":"Zooper", 								
   "email":"[email protected]", 					
   "phone_number":"+12195465432", 						
   "birthdate":"1983-09-11", 							
   "taxpayer_id":"{{insira_um_cpf_valido}}" 				
}'

Requisição e Resposta

POST https://api.zoop.ws/v1/marketplaces/{{marketplace_id}}/sellers/individuals

{
   "first_name":"João",
   "last_name":"Zooper",
   "email":"[email protected]",
   "phone_number":"+12195465432",
   "birthdate":"1983-09-11",
   "taxpayer_id":"{{insira_um_cpf_valido}}"
}
{
    "id": "1e4c8c9b9886419098c60c53f2e7a57e",
    "status": "enabled",
    "resource": "seller",
    "type": "individual",
    "account_balance": "0.00",
    "current_balance": "0.00",
    "first_name": "João",
    "last_name": "Zooper",
    "email": "[email protected]",
    "description": null,
    "taxpayer_id": "00113788088",
    "phone_number": "+12195465432",
    "birthdate": "1983-09-11",
    "website": null,
    "facebook": null,
    "twitter": null,
    "address": {
        "line1": null,
        "line2": null,
        "line3": null,
        "neighborhood": null,
        "city": null,
        "state": null,
        "postal_code": null,
        "country_code": null
    },
    "statement_descriptor": null,
    "mcc": null,
    "show_profile_online": false,
    "is_mobile": false,
    "decline_on_fail_security_code": false,
    "decline_on_fail_zipcode": false,
    "delinquent": true,
    "payment_methods": null,
    "default_debit": null,
    "default_credit": null,
    "merchant_code": "012000000000001",
    "terminal_code": "GT0000CA",
    "uri": "\/v1\/marketplaces\/3249465a7753536b62545a6a684b0000\/sellers\/individuals\/1e4c8c9b9886419098c60c53f2e7a57e",
    "marketplace_id": "3249465a7753536b62545a6a684b0000",
    "metadata": {},
    "created_at": "2020-03-27T14:39:26+00:00",
    "updated_at": "2020-03-27T14:39:26+00:00"
}

Caso se trate de uma empresa, você deverá utilizar o endpoint para empresas.
Veja mais detalhes em: Criar vendedor do tipo empresa

Realizando uma transação com cartão sem tokenizar (API V1)

Tendo cadastrado vendedor, o que você precisa agora é coletar os dados de cartão de crédito e realizar uma transação.

curl --request POST \
  --url https://api.zoop.ws/v1/marketplaces/3249465a7753536b62545a6a684b0000/transactions \
  --header 'accept: application/json' \
  --header 'authorization: Basic enBrX3Rlc3RfRXpDa3pGRktpYkdRVTZIRnE3RVlWdXhJOg==' \
  --header 'content-type: application/json' \
  --data '{
   "source":{
      "usage":"single_use",
      "card":{
         "holder_name":"JOAO SILVA",
         "expiration_month":"9",
         "expiration_year":"2027",
         "card_number":"4539003370725497",
         "security_code":"123"
      },
      "currency":"BRL",
      "type":"card",
      "amount":7
   },
   "amount":7,
   "currency":"BRL",
   "description":"Venda",
   "on_behalf_of":"1e4c8c9b9886419098c60c53f2e7a57e",
   "payment_type":"credit"
}'

Requisição e Resposta

POST https://api.zoop.ws/v1/marketplaces/{{marketplace_id}}/transactions

{
   "source":{
      "usage":"single_use",
      "card":{
         "holder_name":"JOAO SILVA",
         "expiration_month":"9",
         "expiration_year":"2027",
         "card_number":"4539003370725497",
         "security_code":"123"
      },
      "currency":"BRL",
      "type":"card",
      "amount":7
   },
   "amount":7,
   "currency":"BRL",
   "description":"Venda",
   "on_behalf_of":"1e4c8c9b9886419098c60c53f2e7a57e",
   "payment_type":"credit"
}
{
    "id": "433ce9df1edc4586865bbe86bdcd53ca",
    "resource": "transaction",
    "status": "succeeded",
    "amount": "0.07",
    "original_amount": "0.07",
    "currency": "BRL",
    "description": "Venda",
    "payment_type": "credit",
    "transaction_number": "Z133937-000260004",
    "gateway_authorizer": "cielo",
    "app_transaction_uid": null,
    "refunds": null,
    "rewards": null,
    "discounts": null,
    "pre_authorization": null,
    "sales_receipt": "7c80f6f51eaf440dba2c5b65fc1970a0",
    "on_behalf_of": "1e4c8c9b9886419098c60c53f2e7a57e",
    "customer": null,
    "statement_descriptor": "JOO ZOOPER",
    "payment_method": {
        "id": "f3018f5937e4469ba64df1a713f24bca",
        "resource": "card",
        "description": null,
        "card_brand": "Visa",
        "first4_digits": "4539",
        "last4_digits": "5497",
        "expiration_month": "9",
        "expiration_year": "2027",
        "holder_name": "JOAO SILVA",
        "is_active": false,
        "is_valid": true,
        "is_verified": false,
        "customer": null,
        "fingerprint": "db83a1f71dd0914c1f9e6b88e69e12a43f26381f0ae2de57235d75447493dde9",
        "address": null,
        "verification_checklist": {
            "postal_code_check": "unchecked",
            "security_code_check": "unchecked",
            "address_line1_check": "unchecked"
        },
        "metadata": {},
        "uri": "\/v1\/marketplaces\/3249465a7753536b62545a6a684b0000\/transactions\/f3018f5937e4469ba64df1a713f24bca",
        "created_at": "2020-03-27T14:50:08+00:00",
        "updated_at": "2020-03-27T14:50:08+00:00"
    },
    "source": {
        "id": "b0c8d1fd477545c2a444320be628cef2",
        "status": "used",
        "usage": "single_use",
        "amount": "0.07",
        "currency": "BRL",
        "description": null,
        "statement_descriptor": null,
        "type": "card",
        "card": {
            "id": "f3018f5937e4469ba64df1a713f24bca",
            "resource": "card",
            "description": null,
            "card_brand": "Visa",
            "first4_digits": "4539",
            "last4_digits": "5497",
            "expiration_month": "9",
            "expiration_year": "2027",
            "holder_name": "JOAO SILVA",
            "is_active": false,
            "is_valid": true,
            "is_verified": false,
            "customer": null,
            "fingerprint": "db83a1f71dd0914c1f9e6b88e69e12a43f26381f0ae2de57235d75447493dde9",
            "address": null,
            "verification_checklist": {
                "postal_code_check": "unchecked",
                "security_code_check": "unchecked",
                "address_line1_check": "unchecked"
            },
            "metadata": {},
            "uri": "\/v1\/marketplaces\/3249465a7753536b62545a6a684b0000\/transactions\/f3018f5937e4469ba64df1a713f24bca",
            "created_at": "2020-03-27T14:50:08+00:00",
            "updated_at": "2020-03-27T14:50:08+00:00",
            "amount": "0.07"
        }
    },
    "point_of_sale": {
        "entry_mode": "manually_keyed",
        "identification_number": null
    },
    "installment_plan": null,
    "refunded": false,
    "voided": false,
    "captured": true,
    "fees": "0.00",
    "fee_details": [
        {
            "amount": "0.00",
            "prepaid": false,
            "currency": "BRL",
            "type": "zoop_credit_fee",
            "is_gateway_fee": false,
            "description": "Zoop card-present credit fee"
        }
    ],
    "location_latitude": null,
    "location_longitude": null,
    "uri": "\/v1\/marketplaces\/3249465a7753536b62545a6a684b0000\/transactions\/433ce9df1edc4586865bbe86bdcd53ca",
    "metadata": {},
    "expected_on": "2020-04-27T00:00:00+00:00",
    "created_at": "2020-03-27T14:50:08+00:00",
    "updated_at": "2020-03-27T14:50:11+00:00",
    "payment_authorization": {
        "authorizer_id": "000260004",
        "authorization_code": "133937",
        "authorization_nsu": "20180510122911535"
    },
    "history": [
        {
            "id": "680e70ad61bc475fb7f68651942c5080",
            "transaction": "433ce9df1edc4586865bbe86bdcd53ca",
            "amount": "0.07",
            "operation_type": "created",
            "status": "succeeded",
            "response_code": null,
            "response_message": null,
            "authorization_code": null,
            "authorizer_id": null,
            "authorization_nsu": null,
            "gatewayResponseTime": null,
            "authorizer": null,
            "created_at": "2020-03-27 14:50:08"
        },
        {
            "id": "2e0a8d7d13614ac6890644432427f2b8",
            "transaction": "433ce9df1edc4586865bbe86bdcd53ca",
            "amount": "0.07",
            "operation_type": "authorization",
            "status": "succeeded",
            "response_code": "00",
            "response_message": "",
            "authorization_code": "133937",
            "authorizer_id": "000260004",
            "authorization_nsu": "20180510122911535",
            "gatewayResponseTime": "2204",
            "authorizer": "cielo",
            "created_at": "2020-03-27 14:50:10"
        }
    ]
}

Pronto! Você realizou sua primeira transação!