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!
a) E-commerce
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.
c) Assinaturas
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.