Integrando ao Moip

1. Criando conta Moip Sandbox

Olá, bem-vindo ao Moip! Nessa página você encontrará informações práticas e condensadas de como integrar com as APIs do Moip. Mas primeiro, para que você possa começar a utilizá-las, você deve criar uma conta em nosso ambiente Sandbox. É um processo bem fácil e nesse ambiente de testes você vai poder dar uma olhada em todos os passos de integração. Lembrando que tudo que você fizer e criar lá continuará lá, para que você possa consultar mais tarde.

A Conta Sandbox é uma conta totalmente separada da Conta do Moip, tanto é que você acessa essas duas contas através de endereços diferentes e elas podem ter logins diferentes também, se desejar. Ah, e o mais importante: a criação de uma não implica na criação da outra. Quando você terminar a implementação utilizando a Conta Sandbox você deve criar uma Conta do Moip.

Mas agora a gente só precisa que você tenha uma conta em Sandbox mesmo! Você pode criá-la por aqui.

2. Obtendo as chaves de acesso

Uma vez que você criou a sua conta em Sandbox, você precisará pegar a chave e o token dela para poder realizar chamadas para as APIs. Essas informações ficam dentro da sua conta  Moip Sandbox e você pode acessá-las em Minha conta > Configurações > Chaves de Acesso.

Para autenticar as requisições, você deve gerar um hash base64 composto por seu token:chave.

Authorization: Basic BASE64(API_TOKEN:API_KEY)

O resultado será semelhante a:

Authorization: Basic MDEwMTAxMDEwMTAxMDEwMTAgMDEwMTAxMDEgMTAxMDE6QUJBQgFCQUJBQkFCQUJBQkFCQUJBQgFCQUJBQkFCQUJBQkFCQUJBQg==

Você pode utilizar as credenciais acima para efetuar os testes. Em todos exemplos de requisições há chaves de testes válidas para o consumo da API.

📘

LOGIN E SENHA SANDBOX

O login da sua Conta Sandbox é o e-mail utilizado no cadastro. A senha também é configurada no momento do cadastro. Você não precisa aguardar e-mail de confirmação do Moip para começar a usar nosso ambiente de testes.

3. Produtos

Escolha o tipo de integração que você terá com o Moip baseado no seu tipo de negócio!

Então você vai fazer vendas sem divisão ou repasse dos valores, certo? Legal, o Moip para E-commerces é um conjunto de ferramentas completo para criar seu e-commerce e receber pagamentos. Da criação de um simples pagamento por cartão de crédito à implementação de esquemas de pagamento por 1-click, reembolsos e pré-autorizações.

Aqui você vai dividir o valor com alguns fornecedores, ou possui uma plataforma com lojistas e precisa fazer o split desses valores na hora da transação. Nesse caso você vai precisar da nossa facilidade para esse processo que costuma ser bem complicadinho. Utilize o Connect para conectar-se à outras contas de modo tão simples quanto o "Logar-se com facebook" e comece a realizar operações em nome delas. Crie contas Moip dentro do seu próprio sistema, split de pagamentos, reembolsos e outras operações.

Agora se você possui uma solução que precisa de pagamentos recorrentes o Moip Assinaturas é a sua opção. Crie planos e assinaturas que nós nos encarregamos de gerar a fatura com a frequência que você precisar!

4. Você não é um desenvolvedor?

Acho que essa página deve estar parecendo um pouco confusa. Mas se você não for um desenvolvedor, talvez um módulo ou plataforma seja a melhor escolha para você, olha só:

Módulos: são softwares de simples aplicação ao seu site que disponibilizam os serviços necessários para uma loja virtual. Alguns dos módulos que já oferecem o Moip como meio de pagamento são o Magento, OpenCart, OsCommerce, PrestaShop e WooCommerce.

Plataformas: são sites que hospedam sua loja virtual e oferecem estrutura (servidores, ferramentas e layout) e serviços necessários para processar seu pagamento. O Moip já está integrado em diversas plataformas de e-commerce nacionais e internacionais. Se quiser dar uma olhada na lista de plataformas disponíveis, você pode acessar a nossa documentação por aqui. A lista fica no menu esquerdo, ao final dele! :)

Cobrando a sua primeira transação

Imagino que você esteja ansioso para começar, né? Tranquilo, nesse exemplo demonstramos o caso mais simples de integração com o Moip que é a criação de uma transação por cartão de crédito.

A integração começa com a criação de um Pedido . O Pedido deve conter as informações pertinentes ao que está sendo vendido, seja um produto, serviço ou uma simples cobrança. É importante que tenhamos essas informações para que você tenha mais segurança. Com elas faremos uma análise anti-fraude da transação.

Abaixo um exemplo (em cURL) da criação de um Pedido usando apenas os atributos obrigatórios.

{
  "ownId": "pedido_xyz",
  "items": [
    {
      "product": "Box de Seriado - Exterminate!",
      "quantity": 1,
      "detail": "Box de seriado com 8 dvds",
      "price": 7300
    }
  ],
  "customer": {
    "ownId": "cliente_xyz",
    "fullname": "João Silva",
    "email": "[email protected]"
  }
}
curl -v https://sandbox.moip.com.br/v2/orders \
   -H 'Content-Type: application/json'  \
   -H 'Authorization: Basic MDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDE6QUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQg==' \
   -d '{
  "ownId": "pedido_xyz",
  "items": [
    {
      "product": "Box de Seriado - Exterminate!",
      "quantity": 1,
      "detail": "Box de seriado com 8 dvds",
      "price": 7300
    }
  ],
  "customer": {
    "ownId": "cliente_xyz",
    "fullname": "João Silva",
    "email": "[email protected]"
  }
}'

Feito isso, você irá receber como resposta um objeto do tipo Pedido com os detalhes mostrados abaixo.

{
  "id": "ORD-KWH58PQA3RTG",
  "ownId": "pedido_xyz",
  "status": "CREATED",
  "createdAt": "2015-04-29T12:07:58-0300",
  "amount": {
    "total": 2300,
    "fees": 0,
    "refunds": 0,
    "liquid": 0,
    "otherReceivers": 0,
    "currency": "BRL",
    "subtotals": {
      "shipping": 0,
      "addition": 0,
      "discount": 0,
      "items": 2300
    }
  },
  "items": [
    {
      "product": "Box de Seriado",
      "price": 2300,
      "detail": "Box de seriado com 7 dvds",
      "quantity": 1
    }
  ],
  "customer": {
    "id": "CUS-BDKZ3SP6OUGX",
    "ownId": "cliente_xyz",
    "fullname": "João Silva",
    "createdAt": "2015-04-29T12:07:58-0300",
    "email": "[email protected]",
    "taxDocument": {
      "type": "UNKNOWN",
      "number": ""
    },
    "_links": {
      "self": {
        "href": "https://sandbox.moip.com.br/v2/customers/CUS-BDKZ3SP6OUGX"
      }
    }
  },
  "payments": [],
  "refunds": [],
  "entries": [],
  "events": [
    {
      "createdAt": "2015-04-29T12:07:58-0300",
      "description": "",
      "type": "ORDER.CREATED"
    }
  ],
  "receivers": [
    {
      "moipAccount": {
        "login": "[email protected]",
        "fullname": "Moip SandBox",
        "id": "MPA-CULBBYHD11"
      },
      "amount": {
        "fees": 0,
        "refunds": 0,
        "total": 2300
      },
      "type": "PRIMARY"
    }
  ],
  "_links": {
    "self": {
      "href": "https://sandbox.moip.com.br/v2/orders/ORD-KWH58PQA3RTG"
    },
    "checkout": {
      "payCreditCard": {
        "redirectHref": "https://checkout-sandbox.moip.com.br/creditcard/ORD-KWH58PQA3RTG"
      },
      "payBoleto": {
        "redirectHref": "https://checkout-sandbox.moip.com.br/boleto/ORD-KWH58PQA3RTG"
      }
    }
  }
}

O próximo passo é receber por esse pedido (oba!). Para isso você deve criar um Pagamento associado a este pedido. Neste exemplo faremos o pagamento por meio de um cartão de crédito capturado em um formulário do próprio cliente. Caso prefira, você pode direcionar o seu cliente para o Checkout Moip utilizando a uri correspondente a forma de pagamento desejada (ex: _links.checkout.payCreditCard) retornada na resposta da criação do pedido.

{
      "installmentCount":2,
      "fundingInstrument":{
        "method":"CREDIT_CARD",
        "creditCard":{
          "expirationMonth":12,
          "expirationYear": 25,
          "number": "5555666677778884",
          "cvc": "123",
          "holder":{
            "fullname":"João Portador da Silva",
            "birthdate":"1988-12-30",
            "taxDocument":{
              "type":"CPF",
              "number":"12345679891"
            },
            "phone":{
              "countryCode":"55",
              "areaCode":"11",
              "number":"66778899"
            }
          }
        }
      }
    }
curl -v https://sandbox.moip.com.br/v2/orders/{id}/payments \
     -H 'Content-Type: application/json'  \
     -H 'Authorization: Basic MDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDE6QUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQg==' \
     -d '{
      "installmentCount":2,
      "fundingInstrument":{
        "method":"CREDIT_CARD",
        "creditCard":{
          "expirationMonth":12,
          "expirationYear": 25,
          "number": "5555666677778884",
          "cvc": "123",
          "holder":{
            "fullname":"João Portador da Silva",
            "birthdate":"1988-12-30",
            "taxDocument":{
              "type":"CPF",
              "number":"12345679891"
            },
            "phone":{
              "countryCode":"55",
              "areaCode":"11",
              "number":"66778899"
            }
          }
        }
      }
    }'

❗️

ATENÇÃO

Os dados sensíveis do cartão devem sempre passar pela criptografia antes do envio ao Moip.

Após a criação do pagamento, você irá receber a resposta com o resultado da transação.

{
  "id": "PAY-3QHGJL1ORP6L",
  "status": "IN_ANALYSIS",
  "amount": {
    "fees": 187,
    "refunds": 0,
    "liquid": 1813,
    "currency": "BRL",
    "total": 2000
  },
  "installmentCount": 1,
  "fundingInstrument": {
    "creditCard": {
      "id": "CRC-TZW7KI7M46YF",
      "brand": "MASTERCARD",
      "first6": "555566",
      "last4": "8884",
      "holder": {
        "birthdate": "30/12/1988",
        "taxDocument": {
          "type": "CPF",
          "number": "33333333333"
        },
        "fullname": "Jose Portador da Silva"
      }
    },
    "method": "CREDIT_CARD"
  },
  "fees": [
    {
      "type": "TRANSACTION",
      "amount": 187
    }
  ],
  "events": [
    {
      "createdAt": "2015-04-01T15:45:04-0300",
      "type": "PAYMENT.IN_ANALYSIS"
    },
    {
      "createdAt": "2015-04-01T15:45:01-0300",
      "type": "PAYMENT.CREATED"
    }
  ],
  "_links": {
    "order": {
      "title": "ORD-F3BE7QOLKON3",
      "href": "https://sandbox.moip.com.br/v2/orders/ORD-F3BE7QOLKON3"
    },
    "self": {
      "href": "https://sandbox.moip.com.br/v2/payments/PAY-3QHGJL1ORP6L"
    }
  },
  "createdAt": "2015-04-01T15:45:01-0300",
  "updatedAt": "2015-04-01T15:45:04-0300"
}

Você pode acompanhar as alterações de status tanto do Pedido quanto do Pagamento por meio dos Webhooks ou realizando consultas nos recursos por meio de chamadas GET. Acesse o Guia básico para entender as sequências de status dos recursos para os diferentes meios de pagamento.

Solicitar Homologação

Assim que você finalizar a integração em Sandbox, você estará apto para a nossa homologação. Esse é o passo final antes de ir para produção. Nossa equipe fará alguns testes de compra e, caso a integração cumpra os requisitos, você receberá as credenciais para uso da API em produção.