NAV

Visão Geral

Introdução

As novas APIs Rest do Moip permitem que você receba pagamentos em seu website ou em sua aplicação móvel de forma simples e segura. Nossas APIs de pagamento viabilizam desde uma integração simples, como a de uma loja virtual, até a implementação de Marketplaces que conectam compradores e vendedores.

As próximas seções apresentam uma visão geral dos serviços do Moip e dos principais usos que podem ser dados para nossas soluções. Devs podem preferir ir direto para a Referência completa ou para a seção Como começar.

Sobre o Moip

O Moip é uma solução completa (full stack) de pagamentos online. Isso significa que cuidamos de tudo o que é preciso para receber pagamentos na web ou em uma aplicação móvel. Análise anti-fraude, contratos com os meios de pagamento, gateways, segurança de dados sensíveis, tudo isso é por nossa conta e com uma única linha de código você ou o seu cliente já podem começar a cobrar pelos seus produtos e serviços.

Somos diferentes dos intermediadores. Não nos preocupamos em cadastrar compradores. Não intermediamos o fluxo de pagamento com redirecionamentos e cadastros desnecessários.

Somos diferentes dos gateways de pagamento. Fazemos muito mais do que simplesmente trafegar informações e conectar sistemas. Cuidamos da fraude, da segurança, dos contratos e de toda a burocracia para aceitar pagamentos online.

Histórico das nossas APIs

Em 2009, fomos a primeira empresa da América Latina a abrir as nossas APIs no mercado de pagamentos. Fomos também pioneiros e lançamos o conceito de Checkout Transparente. Ajudamos a desenvolver o mercado de Marketplaces e Assinaturas no Brasil, com as nossas soluções. Passaram-se 5 anos. A tecnologia mudou. O mercado mudou. Estava na hora de voltar às nossas origens e dar mais um passo. Por isso resolvemos re-escrever todas as nossas APIs baseado em um novo conceito que facilite a vida dos nossos desenvolvedores parceiros. E este é só o começo.

Usos mais comuns

  • E-commerce e M-commerce - O Moip é usado por milhares de websites e lojas virtuais como solução para o recebimento de pagamentos por cartão de crédito, boleto e débito online. Todo o fluxo de pagamento ocorre no checkout da loja/site. Oferecemos diversos serviços que aumentam a conversão de vendas e auxiliam os lojistas na operação de pós-venda. Esta é integração mais simples e requer apenas o uso das APIs de pagamento e do Moip.js.

  • Pagamentos em Apps - As mesmas funcionalidades disponíveis para websites agora podem ser utilizadas dentro de Aplicativos móveis. A nova versão da API do Moip foi pensada para propiciar a melhor experiência de compra em Apps. É possível submeter uma transação com número reduzido de dados do consumidor, cadastrar o cartão para uso posterior e controlar todos os passos do checkout. A integração é realizada combinando o uso das APIs de pagamento e dos SDKs Mobile.

  • Serviço de pagamento para terceiros - O Moip também é utilizado por parceiros que queiram oferecer a nossa solução de pagamentos como parte de sua plataforma de serviços. Este é o caso das plataformas de e-commerce, dos softwares de cobrança e de qualquer outro negócio que precise de uma solução de pagamentos para terceiros e que não possa ou não queira perder tempo construindo uma. Esta integração envolve o uso das APIs de pagamento em conjunto com o Moip connect.

  • Marketplaces - O Moip é a solução mais completa e poderosa do mercado para negócios que facilitam transações entre compradores e vendedores. Marketplaces podem fechar vendas em seu ambiente sem se preocupar com questões regulatórias, legais ou que envolvam o gerenciamento da segurança das transações. É possível dividir o pagamento em tempo real e com isso cobrar comissões de venda. Também é possível controlar o fluxo de liquidação e com isso gerenciar o comportamento de compra dentro do seu ambiente. Estas funcionalidades estão inclusas nas APIs de Marketplace e no Moip connect.

  • Assinaturas e cobranças recorrentes - Ideal para o gerenciamento e cobrança de mensalidades, assinaturas e pagamentos recorrentes. Por meio das APIs de Assinaturas você pode fazer cobranças automáticas, no valor e intervalo que escolher por meio da criação de planos que serão oferecidos aos seus clientes.

Segurança

O Moip recomenda que qualquer lojista que armazene, processe ou trafegue dados de cartão de crédito em sua aplicação siga as normas do PCI Compliance.

Para reduzir o trabalho de compliance com as normas, mantendo o fluxo de pagamento em seu site ou app, você pode optar por utilizar o Moip.js ou utilizar nossos sdks iOS e Android. Para integrações mais rápidas também é possível utilizar o Checkout Moip.

Suporte

Qualquer dúvida, entre em contato diretamente com nossos Devs pelo dev@moip.com.br, ou clicando aqui para abrir o widget de suporte, se preferir use o icone disponível nesta página localizado no canto inferior direito.

Caso queira conferir os nossos sdks acesse Github.com/moip.

Se você recebeu um erro inesperado em nossa API como erro 500 ou “Ops… We were not waiting for it” nos reporte através desse formulário

Changelog

Criamos uma página especial para que você possa acompanhar nossas principais mudanças alem de uma lista de notificação. Clique aqui para acessar essa página e se cadastre para receber as notificações de alteração por e-mail.

Acompanhe também pelo HitchHQ

Abordagem RESTFul

As novas APIs do Moip foram implementadas com base na arquiteura RESTful. Para nomear os recursos usamos nomes (Pedidos, Pagamentos, Clientes e outros) e suportamos diversas chamadas HTTP Verbs para cada recurso. Desta forma, o mesmo recurso, por exemplo, “v2/customers/” pode ser usado tanto para criar um novo Cliente, através do método “POST”, quanto para consultar uma lista de clientes “GET”.

Além disso, usamos o conceito de HATEOAS e cada recurso possui como atributo um conjunto de hyperlinks que podem ser usados para automatizar a sua aplicação.

Quer bater um papo sobre design de APIs? Fale com a gente pelo email dev@moip.com.br ou clicando aqui para abrir o widget de suporte.

Como começar

Esta seção te ajuda a entender rapidamente como as APIs do Moip funcionam e te auxilia a fazer a primeira transação. Para usos mais complexos, veja os tutoriais avançados listados na próximas seções ou consulte diretamente a referência da API.

Obter chaves de acesso

Ao iniciar sua integração com o Moip optando pelo modelo mais simples, você vai usar a autenticação básica Basic Authentication. Este modelo permite realizar qualquer ação na API utilizando sua própria Conta Moip.

Siga o Passo a Passo abaixo para obter suas credenciais:

  • Crie uma conta Moip para vendedores em ambiente sandbox. Clique aqui para criar a conta, caso ainda não tenha.
  • Acesse o menu Minha conta >> Configurações >> Chaves de Acesso para obter suas chaves de autenticação - Se preferir, clique aqui.

Com suas credenciais em mãos gere um hash base64 composto por seu token:chave, veja exemplo abaixo.

Authorization: Basic BASE64(MOIP_API_TOKEN:MOIP_API_KEY)

O resultado será semelhante a:

Authorization: Basic MDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDE6QUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQg==

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.

Cobrando a sua primeira transação

Neste exemplo vamos demonstrar 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. Estas informações são importantes para que o Moip possa realizar a análise anti-fraude da transação.

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

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": "joaosilva@email.com"
  }
}'
auth = Moip2::Auth::Basic.new("01010101010101010101010101010101", "ABABABABABABABABABABABABABABABABABABABAB")
client = Moip2::Client.new(:sandbox, auth)
api = Moip2::Api.new(client)

order = api.order.create(
    {
        own_id: "ruby_sdk_1",
        items: [
          {
            product: "Nome do produto",
            quantity: 1,
            detail: "Mais info...",
            price: 1000
          }
        ],
        customer: {
          own_id: "ruby_sdk_customer_1",
          fullname: "Jose da Silva",
          email: "sandbox_v2_1401147277@email.com",
        }
    }
)
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
<?
require 'vendor/autoload.php';

use Moip\Moip;
use Moip\MoipBasicAuth;

$token = '01010101010101010101010101010101';
$key = 'ABABABABABABABABABABABABABABABABABABABAB';

$moip = new Moip(new MoipBasicAuth($token, $key), Moip::ENDPOINT_SANDBOX);

$customer = $moip->customers()->setOwnId(uniqid())
                             ->setFullname('Fulano de Tal')
                             ->setEmail('fulano@email.com');

$order = $moip->orders()->setOwnId(uniqid())
                        ->addItem('Bicicleta Specialized Tarmac 26 Shimano Alivio', 1, 'uma linda bicicleta', 10000)
                        ->setCustomer($customer)
                        ->create();
?>

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": "joaosilva@email.com",
    "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": "integracao@labs.moip.com.br",
        "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 é realizar a cobrança. 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.

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"
            }
          }
        }
      }
    }'
api.payment.create(order.id,
    {
        installment_count: 1,
        funding_instrument: {
            method: "CREDIT_CARD",
            credit_card: {
                expiration_month: 04,
                expiration_year: 25,
                number: "5555666677778884",
                cvc: "123",
                holder: {
                    fullname: "Jose Portador da Silva",
                    birthdate: "1988-10-10",
                    tax_document: {
                        type: "CPF",
                        number: "22222222222"
                },
                    phone: {
                        country_code: "55",
                        area_code: "11",
                        number: "55667788"
                    }
                }
            }
        }
    }
)
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
<?
$payment = $order->payments()->setCreditCard(12, 25, '5555666677778884', '123', $customer)
                             ->execute();
?>

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 etender as sequências de status dos recursos para os diferentes meios de pagamento.

Homologação

Finalizada a integração em ambiente de Sandbox, antes de ir para produção, a sua integração deve passar pelo processo de homologação. Nossa equipe fará alguns testes de compra e, caso a integração cumpra os requisitos mínimos, você receberá as credenciais para uso da API em produção.

Check-list da interface de pagamento

Os requisitos apresentados abaixo tem como objetivo avaliar a sua consistência da integração e a comunicação na interface com o consumidor. O objetivo é garantir que não ocorram falhas ou problemas de comunicação com o consumidor quando você estiver recebendo pagamentos em produção.

Item E-Commerce Marketplace Assinaturas
As informações solicitadas ao pagador atendem as informações obrigatórias para se processar um pagamento
O pagador é informado com clareza sobre o valor total a ser pago em uma única cobrança, incluindo descontos e acréscimos
O cliente é comunicado na interface, de forma clara e direta, que se trata de um assinatura de determinado valor e intervalo de cobrança.
O cliente é notificado na interface do sucesso ou da falha da contratação da assinatura
Para contratar um assinatura, o cliente deve concordar com os “Termos da assinaturaExemplo de termo de uso para assinaturas
O Código da Assinatura é informado ao cliente no momento em que a assinatura é criada
O cliente é comunicado na interface, de forma discreta, que o pagamento será processado pelo Moip.
Utilize esta ou esta outra imagem
O Moip não pode ser mencionado em nenhum momento do checkout como o ponto de contato do cliente para tirar dúvidas ou tratar de problemas sobre a transação
O assinante é informado de como proceder para solicitar o cancelamento de sua assinatura
O assinante é notificado quando ele é cobrado pela assinatura contratada
O assinante é notificado sempre que houver qualquer mudança em sua assinatura
Caso a assinatura seja contratada por telefone, email ou presencialmente), todos os aspectos acima são informado e, depois, confirmados por email

Guia Básico

As APIs de pagamento possibilitam desde a 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.

As próximas sessões apresentam os guias para os usos mais comuns das APIs de Pagamentos:

Fluxo básico de um pagamento

Nas novas Apis, introduzimos o conceito do Pedido que deve ser criado anteriormente à submissão de um Pagamento. Uma vez criado o pedido (com as informações do produto/serviço e do consumidor) passa a ser possível submeter diversas tentativas de pagamento, com meios de pagamento distintos, até que o mesmo seja pago.

As informações contidas no pedido são importantes para que o Moip possa fazer a análise anti-fraude das transações. As novas APIs possibilitam que o integrador escolha quais informações são enviadas ao Moip optando ou não pelo uso do programa de cobertura contra fraudes.

Criando um pedido

A integração começa com a criação de um Pedido. Abaixo segue um exemplo de uma típica transação de e-commerce em que são informados os valores, dados de cliente e endereço de entrega. Veja que você pode utilizar um Cliente previamente criado no Moip ou criar um novo na chamada.

curl -v https://sandbox.moip.com.br/v2/orders \
   -H 'Content-Type: application/json'  \
   -H 'Authorization: Basic MDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDE6QUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQg==' \
   -d '{
                "ownId": "seu_identificador",
                "amount": {
                    "currency": "BRL",
                    "subtotals": {
                        "shipping": 1000
                    }
                },
                "items": [
                    {
                        "product": "Nome do produto",
                        "quantity": 1,
                        "detail": "Mais info...",
                        "price": 1000
                    }
                ],
                "customer": {
                    "ownId": "seu_identificador_de_cliente",
                    "fullname": "Jose Silva",
                    "email": "cliente@email.com",
                    "birthDate": "1988-12-30",
                    "taxDocument": {
                        "type": "CPF",
                        "number": "22222222222"
                    },
                    "phone": {
                        "countryCode": "55",
                        "areaCode": "11",
                        "number": "66778899"
                    },
                    "shippingAddress": 
                        {
                            "street": "Avenida Faria Lima",
                            "streetNumber": 2927,
                            "complement": 8,
                            "district": "Itaim",
                            "city": "Sao Paulo",
                            "state": "SP",
                            "country": "BRA",
                            "zipCode": "01234000"
                        }
                }
            }'
auth = Moip2::Auth::Basic.new("01010101010101010101010101010101", "ABABABABABABABABABABABABABABABABABABABAB")
client = Moip2::Client.new(:sandbox, auth)
api = Moip2::Api.new(client)

order = api.order.create(
    {
        own_id: "seu_identificador",
        items: [
          {
            product: "Nome do produto",
            quantity: 1,
            detail: "Mais info...",
            price: 1000
          }
        ],
        customer: {
          own_id: "seu_identificador_de_cliente",
          fullname: "Jose da Silva",
          email: "cliente@email.com",
          birthdate: "1988-12-30",
          tax_document: { number: "33333333333", type: "CPF" },
          phone: { country_code: "55", area_code: "11", number: "66778899" },
          shipping_address: 
            {
              street: "Avenida Faria Lima",
              street_number: 2927,
              complement: 8,
              district: "Itaim",
              city: "Sao Paulo",
              state: "SP",
              country: "BRA",
              zip_code: "01234000"
            }
        }
    }
)
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
<?
require 'vendor/autoload.php';

use Moip\Moip;
use Moip\MoipBasicAuth;

$token = '01010101010101010101010101010101';
$key = 'ABABABABABABABABABABABABABABABABABABABAB';

$moip = new Moip(new MoipBasicAuth($token, $key), Moip::ENDPOINT_SANDBOX);

$customer = $moip->customers()->setOwnId(uniqid())
                             ->setFullname('Fulano de Tal')
                             ->setEmail('fulano@email.com')
                             ->setBirthDate('1988-12-30')
                             ->setTaxDocument('22222222222')
                             ->setPhone(11, 66778899)
                             ->addAddress('BILLING',
                                          'Rua de teste', 123,
                                          'Bairro', 'Sao Paulo', 'SP',
                                          '01234567', 8);

$order = $moip->orders()->setOwnId(uniqid())
                        ->addItem('Bicicleta Specialized Tarmac 26 Shimano Alivio', 1, 'uma linda bicicleta', 10000)
                        ->setCustomer($customer)
                        ->create();
?>

Retorno:


{
  "id": "ORD-1AWC30TWYZMX",
  "ownId": "id_do_meu_pedido_xxxyyyzzz",
  [...]
}

Com o Id do pedido (ORD-XXXXXXXXXXXX) em mãos você poderá submeter diversas tentativas de pagamento, com meios de pagamento distintos, até que este pedido seja pago.

Capturando os dados do cartão de crédito

Para processar pagamentos de forma segura, você deve criptografar os dados do cartão antes de processá-los em seu servidor. Para isso você deve obter sua chave públicca e utilizar uma de nossas bibliotecas prontas para uso no browser, em aplicativos nativos iOS e Android.

O resultado final da criptografia será um hash que será utilizado para processar o pagamento no próximo passo.

Cobrando um pedido com cartão de crédito

Para criar um pagamento por cartão você pode redirecionar o comprador para um formulário hospedado pelo Moip (utilizando hyperlink enviado na resposta da chamada de criação do pedido) ou utilizar o hash do cartão criptografado obtido no passo anterior para processar a transação.

Abaixo um exemplo da criação de um pagamento por cartão.

Requisição

curl -v https://sandbox.moip.com.br/v2/orders/{id}/payments \
   -H 'Content-Type: application/json'  \
   -H 'Authorization: Basic MDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDE6QUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQg==' \
   -d '{
    "installmentCount": 1,
    "fundingInstrument": {
        "method": "CREDIT_CARD",
        "creditCard": {
            "hash": "2n9vykIkGX5tegvdl+ow5ngPxP3ItAkp9tc1tzuMTeAuF457uN99CJIG386RD/iV5JPjwr9uCgr0XNYraMulcNJnys2b+A2pl7VcNmO83N5YBkViG+mo9SSCXMcBYBIcGotInur49DpKwylMbMFFWWYFsO/pq8e+zAe6g7dOLcKwkGlVrNL1PKepWxd5ldt44yPZhMeG82eiLxbnXrkAtcY19Phjlg7GIhCj3hjxSYi0Y6iUtLYmTpsVQIs93myH7LLU30gZ88xRMAYbmshi7fc8clfDkLbUPcCCDDYwe6ltFYX1J0YA/TT87Amj9filRlTzLuU9qvKHlXpq2Q/H",
            "holder": {
                "fullname": "Jose Santos",
                "birthdate": "1980-01-02",
                "taxDocument": {
                    "type": "CPF",
                    "number": "12345679891"
                },
                "phone": {
                    "countryCode": "55",
                    "areaCode": "11",
                    "number": "25112511"
                }
            }
        }
    }
}'
api.payment.create(order.id,
    {
        installment_count: 1,
        funding_instrument: {
            method: "CREDIT_CARD",
            credit_card: {
                hash: "2n9vykIkGX5tegvdl+ow5ngPxP3ItAkp9tc1tzuMTeAuF457uN99CJIG386RD/iV5JPjwr9uCgr0XNYraMulcNJnys2b+A2pl7VcNmO83N5YBkViG+mo9SSCXMcBYBIcGotInur49DpKwylMbMFFWWYFsO/pq8e+zAe6g7dOLcKwkGlVrNL1PKepWxd5ldt44yPZhMeG82eiLxbnXrkAtcY19Phjlg7GIhCj3hjxSYi0Y6iUtLYmTpsVQIs93myH7LLU30gZ88xRMAYbmshi7fc8clfDkLbUPcCCDDYwe6ltFYX1J0YA/TT87Amj9filRlTzLuU9qvKHlXpq2Q/H",
                holder: {
                    fullname: "Jose Portador da Silva",
                    birthdate: "1988-10-10",
                    tax_document: {
                        type: "CPF",
                        number: "22222222222"
                    }
                }
            }
        }
    }
)
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
<?
$payment = $order->payments()->setCreditCardHash('2n9vykIkGX5tegvdl+ow5ngPxP3ItAkp9tc1tzuMTeAuF457uN99CJIG386RD/iV5JPjwr9uCgr0XNYraMulcNJnys2b+A2pl7VcNmO83N5YBkViG+mo9SSCXMcBYBIcGotInur49DpKwylMbMFFWWYFsO/pq8e+zAe6g7dOLcKwkGlVrNL1PKepWxd5ldt44yPZhMeG82eiLxbnXrkAtcY19Phjlg7GIhCj3hjxSYi0Y6iUtLYmTpsVQIs93myH7LLU30gZ88xRMAYbmshi7fc8clfDkLbUPcCCDDYwe6ltFYX1J0YA/TT87Amj9filRlTzLuU9qvKHlXpq2Q/H', $customer)
                             ->execute();
?>

Retorno

{
    "id": "PAY-NWB1SAWBQ30O",
    "status": "IN_ANALYSIS",
   [...]
}

Para ver todos os atributos e métodos disponíveis acesse o recurso Pagamento na referência.

Interação de status de pagamento

Veja abaixo a interação das alterações de pagamento e o reflexo dele no status do pedido.

Altareções de status

Cobrando um pedido com boleto

Para a cobrança de um pedido por boleto, basta redirecionar o usuário para o link enviado após a criação do pedido.

{
  [...]
    "_links":{
    "checkout":{

  [...]

            "payBoleto":{
        "redirect_href":"https://checkout-sandbox.moip.com.br/boleto/ORD-CRXW0DQA699O"
      },
  [...]
  }
}

Se for necessário alterar a data de vencimento ou os detalhes adicionais impressos no boleto, você pode fazer uma nova chamada criando um pagamento do tipo boleto e obter a URL de exibição. É possível redirecionar o usuário para a página de boleto pronta para impressão, basta concatenar /print ao final da URL de visualização do boleto.

curl -v https://sandbox.moip.com.br/v2/orders/{id}/payments \
   -H 'Content-Type: application/json'  \
   -H 'Authorization: Basic MDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDE6QUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQg==' \
   -d '{
    "fundingInstrument": {
        "method": "BOLETO",
        "boleto": {
            "expirationDate": "2013-09-30",
            "instructionLines": {
                "first": "Primeira linha se instrução",
                "second": "Segunda linha se instrução",
                "third": "Terceira linha se instrução"
            },
            "logoUri": "http://"
        }
    }
}'
api.payment.create(
    {
        funding_instrument: {
            method: "BOLETO",
            boleto: {
                expiration_date: "2016-12-30",
                instruction_lines: {
                    first: "Primeira linha do boleto",
                    second: "Segunda linha do boleto",
                    third: "Terceira linha do boleto"
                  },
                logo_uri: "https://"
            }
        }
    }
)
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
<?
$payment = $order->payments()->setBoleto('2016-12-30', 'http://', array('Primeira linha do boleto', 'Segunda linha do boleto', 'Terceira linha do boleto'))
                             ->execute();
?>

Na resposta você vai receber a URL que permite a visualização do boleto pelo comprador.

{
  "id": "PAY-UU9VYAGJO1X0",
  "[...]
    "payBoleto": {
      "redirectHref": "https://checkout-sandbox.moip.com.br/boleto/PAY-UU9VYAGJO1X0"
    }
    [...]
}

Acesse a referência da API para maiores informações do método.

Interação de status de pagamento

Veja abaixo a interação das alterações de pagamento por meio de boleto bancário e o reflexo dele no status do pedido.

Altareções de status

Cobrando um pedido com débito online

O débito online requer a autenticação do usuário no internet banking da instituição bancária escolhida. Para isso basta redirecionar o usuário para o link enviado após a criação do pedido.

{
  [...]
    "_links":{
    "checkout":{

            "payOnlineBankDebitItau":{
        "redirect_href":"https://checkout.test.moip.com.br/debit/itau/ORD-XES9017BQJT9"
      },
      "payOnlineBankDebitBB":{
        "redirect_href":"https://checkout.test.moip.com.br/debit/bancodobrasil/ORD-XES9017BQJT9"
      },
      "payOnlineBankDebitBradesco":{
        "redirect_href":"https://checkout.test.moip.com.br/debit/bradesco/ORD-XES9017BQJT9"
      },
      "payOnlineBankDebitBanrisul":{
        "redirect_href":"https://checkout.test.moip.com.br/debit/banrisul/ORD-XES9017BQJT9"
      }
      [...]
  }
}

Se preferir, você pode fazer uma nova chamada criando um pagamento por débito online já especificando a instituição bancária escolhida pelo usuário e obter a URL de redirecionamento no retorno.

curl -v https://sandbox.moip.com.br/v2/orders/{id}/payments \
   -H 'Content-Type: application/json'  \
   -H 'Authorization: Basic MDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDE6QUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQg==' \
   -d '{
    "fundingInstrument": {
        "method": "ONLINE_BANK_DEBIT",
        "onlineBankDebit": {
            "bankNumber":"001",
            "expirationDate": "2013-12-30",
            "returnUri": "http://"
        }
    }
}'
# Por enquanto não disponível no SDK Ruby, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK PHP, veja nosso exemplo em cURL.

Na resposta você vai receber a URL para redirecionar o comprador para o site do banco.

{
  "id": "PAY-F1EUJXNFI1OX",
  "status": "WAITING",
[...]

  "_links": {
    "payOnlineBankDebitBB": {
      "redirectHref": "https://desenvolvedor.moip.com.br/sandbox/ProcessarDebito.do?externalId=PAY-F1EUJXNFI1OX"
    }
[...]
}

Maiores informações sobre o método de criação de pagamento por débito podem ser vistas na referência da API.

Interação de status de pagamento

Veja abaixo a interação das alterações de pagamento e o reflexo dele no status do pedido.

Altareções de status

Utilizando o Checkout Moip

Caso você prefira que o seu cliente efetue o pagamento da transação no ambiente do Moip você pode direcioná-lo para o nosso checkout.

Ao criar um pedido o Moip retornará hyperlinks para que seja possível fazer o direcionamento do cliente para um formulário de pagamento hospedado por nós. Este fluxo reduz o seu escopo PCI e simplifica a implementação do fluxo de pagamento.

[...]
links: {
    self: {
        href: "https://sandbox.moip.com.br/v2/orders/ORD-E28ZI68VELEH"
    }
    checkout: {
        payOnlineBankDebitItau: {
            redirectHref: "https://checkout-sandbox.moip.com.br/debit/itau/ORD-E28ZI68VELEH"
    }-
        payOnlineBankDebitBB: {
            redirectHref: "https://checkout-sandbox.moip.com.br/debit/bancobrasil/ORD-E28ZI68VELEH"
    }-
        payCreditCard: {
            redirectHref: "https://checkout-sandbox.moip.com.br/creditcard/ORD-E28ZI68VELEH"
    }-
        payOnlineBankDebitBradesco: {
            redirectHref: "https://checkout-sandbox.moip.com.br/debit/bradesco/ORD-E28ZI68VELEH"
    }-
        payBoleto: {
            redirectHref: "https://checkout-sandbox.moip.com.br/boleto/ORD-E28ZI68VELEH"
    }-
        payOnlineBankDebitBanrisul: {
            redirectHref: "https://checkout-sandbox.moip.com.br/debit/banrisul/ORD-E28ZI68VELEH"
    }-
}
[...]

Vocẽ pode definir preferências de parcelamento e urls de redirecionamento para o seu checkout utilizando o parâmetro checkoutPreferences. Acesse a Referência da API para maiores informações.

Guia Avançado

Neste guia são apresentados casos avançados de integração com a API de pagamentos do Moip.

Salvando cartão para uso posterior

O Moip torna simples a implementação de esquemas de pagamento por 1 clique para compradores recorrentes em seu website ou aplicativo. Nós cuidamos do armazenamento dos dados do cartão do cliente.

Para isso você deve criar um Cliente com as informações do cartão de crédito. Abaixo um exemplo de uma chamada.

curl -v https://sandbox.moip.com.br/v2/customers \
-H 'Content-Type: application/json'  \
-H 'Authorization: OAuth 1tldio91gi74r34zv30d4saz8yuuws5' \
-d '{
      "ownId":"meu_id_de_cliente",
      "fullname":"Jose Silva",
      "email":"josedasilva@email.com",
      "phone":{
        "areaCode":"11",
        "number":"66778899"
      },
      "birthDate":"1988-12-30",
      "taxDocument":{
        "type":"CPF",
        "number":"22222222222"
      },
      "shippingAddress":
        {
           [...]
      },
      "fundingInstrument":{
        "method":"CREDIT_CARD",
        "creditCard":{
          "expirationMonth":12,
          "expirationYear":15,
          "number":"4073020000000002",
          "holder":{
            "fullname":"Jose Silva",
            "birthdate":"1988-12-30",
            "taxDocument":{
              "type":"CPF",
              "number":"22222222222"
            },
            "phone":{
              "areaCode":"11",
              "number":"66778899"
            }
          }
        }
      }
    }'

# Por enquanto não disponível no SDK Ruby, veja nosso exemplo em cURL.

# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
<?
require 'vendor/autoload.php';

use Moip\Moip;
use Moip\MoipBasicAuth;

$token = '01010101010101010101010101010101';
$key = 'ABABABABABABABABABABABABABABABABABABABAB';

$moip = new Moip(new MoipBasicAuth($token, $key), Moip::ENDPOINT_SANDBOX);

$customer = var_dump($moip->customers()->setOwnId(uniqid())
                             ->setFullname('Fulano de Tal')
                             ->setEmail('fulano@email.com')
                             ->setBirthDate('1988-12-30')
                             ->setTaxDocument('22222222222')
                             ->setPhone(11, 66778899)
                             ->addAddress('BILLING',
                                          'Rua de teste', 123,
                                          'Bairro', 'Sao Paulo', 'SP',
                                          '01234567', 8)
                             ->setCreditCard(12, 25, '5555666677778884', '123')
                             ->create());

?>

resposta:


{
  "id":"CUS-A1B2C3D4E5F6",
 [...],

  "fundingInstrument":{
    "method":"CREDIT_CARD",
    "creditCard":{
      "id":"CRC-A1B2C3D4E5F6",
      "customerOwnId":"meu_id_de_cliente",
      "brand":"VISA",
      "first6":"407302",
      "last4":"0002",
      "holder":{
        "fullname":"Jose Silva",
        "taxDocument":{
          "type":"CPF",
          "number":"22222222222"
        },
        "phone":{
          "areaCode":"11",
          "number":"66778899"
        }
      }
    }
  }

  [...]

  }
}

Feito isso, ao criar um pagamento realizado por cartão, ao invés de capturar os dados e enviar ao Moip, você pode enviar o id do Cliente e o id de seu cartão do crédito, assim a cobrança será realizada.

Criando o pedido

curl -v https://sandbox.moip.com.br/v2/orders \
     -H 'Content-Type: application/json'  \
     -H 'Authorization: Basic MDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDE6QUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQg==' \
     -d '{
      "ownId": "id_proprio",
      "amount": {
        "currency": "BRL"
      },
      "items": [
        {
          "product": "Bicicleta Specialized Tarmac 26 Shimano Alivio",
          "quantity": 1,
          "detail": "uma linda bicicleta",
          "price": 10000
        }
      ],
      "customer": {
        "id": "CUS-A1B2C3D4E5F6"
      }
    }'
# Por enquanto não disponível no SDK Ruby, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK PHP, veja nosso exemplo em cURL.

Criando o pagamento

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":{
          "id":"CRC-A1B2C3D4E5F6",
          "cvc":"123"
        }
      }
    }'

# Por enquanto não disponível no SDK Ruby, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK PHP, veja nosso exemplo em cURL.

Você também pode recuperar o id Moip (Ex: CRC-XXXXXXXX ) do cartão de crẽdito em qualquer requisiçao de pagamento efetuada para uso posterior.

Pré-autorizando um pagamento por cartão

As novas APIs permitem que você controle o fluxo de pré-autorização e captura de uma transação de cartão de crédito. Desta forma, ao contrário da configuração padrão, em que o Moip realizar a captura da transação após a análise anti-fraude (status autorizado), você pode controlar quando a captura será realizada. O prazo máximo para realizar a captura é de 5 dias após a pré-autorização do pagamento.

Para pré-autorizar um pagamento basta utilizar o parâmetro delayCapture na requisição de criação do pagamento. Abaixo um exemplo de uma chamada com o parâmetro configurado.

curl -v https://sandbox.moip.com.br/v2/orders/{id}/payments \
   -H 'Content-Type: application/json'  \
   -H 'Authorization: Basic MDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDE6QUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQg==' \
   -d '{
  "installmentCount": 1,
  "delayCapture": true,
  "fundingInstrument": {
    "method": "CREDIT_CARD",
    "creditCard": {
        "hash": "HhL0kbhfid+jwgj5l6Kt9EPdetDxQN8s7uKUHDYxDC/XoULjzik44rSda3EcWuOcL17Eb8JjWc1JI7gsuwg9P0rJv1mJQx+d3Dv1puQYz1iRjEWWhnB1bw0gTvnnC/05KbWN5M8oTiugmhVK02Rt2gpbcTtpS7VWyacfgesBJFavYYMljYg8p2YGHXkXrMuQiOCeemKLk420d0OTMBba27jDVVJ663HZDrObnjFXJH/4B5irkj+HO5genV+V4PYoLcOESG4nrI3oFAsMGsLLcdJo0NNvkEmJpn0e9GzureKKFYisYU+BEd9EMr/odS0VMvOYRV65HbPTspIkjl2+3Q==",
      "holder": {
        "fullname": "Jose Portador da Silva",
        "birthdate": "1988-12-30",
        "taxDocument": {
          "type": "CPF",
          "number": "33333333333"
        },
        "phone": {
          "countryCode": "55",
          "areaCode": "11",
          "number": "66778899"
        }
      }
    }
  }
}'
# Por enquanto não disponível no SDK Ruby, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK PHP, veja nosso exemplo em cURL.

Você receberá no retorno o status de pagamento IN_ANALYSIS. Após a análise anti-fraude, ao invés de alteramos o status para AUTHORIZED e capturarmos o pagamento, o status será alterado para PRE_AUTHORIZED. O pagamento fica então disponível para ser capturado posteriormente em até 5 dias.

Para realizar a captura basta utilizar o método abaixo. Você também pode desfazer a pré-autorização.

POST https://sandbox.moip.com.br/v2/payments/PAY-ZJOE0VPNGIM5/capture

curl -v https://sandbox.moip.com.br/v2/payments/{id}/capture \
   -H 'Content-Type: application/json'  \
   -H 'Authorization: Basic MDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDE6QUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQg==' \
   -d ''
# Por enquanto não disponível no SDK Ruby, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK PHP, veja nosso exemplo em cURL.

No retorno você irá receber o recurso Pagamento com o status AUTHORIZED.

20o (OK)
Content-Type: application/json
{
  [...]

  "id": "PAY-ZJOE0VPNGIM5",
  "status": "AUTHORIZED"

  [...]
  }

Reembolsando um pedido

Com as novas APIs do Moip agora é possível efetuar o reembolso de transações diretamente por nossa API. Os reembolsos de pagamentos realizados por cartão de crédito serão feitos diretamente no cartão do cliente. Pagamentos feitos por meio de boleto/débito online deverão ter seu destino específicados(conta bancária ou conta Moip).

Para reembolsar um pedido pago por cartão de crédito, basta realizar uma chamada para o Moip como a que consta abaixo. O valor será devolvido ao mesmo cartão de crédito utilizado na compra pelo comprador.

Caso você seja um marketplace use o accessToken do recebedor primário para se autenticar no request de reembolso.

curl -v https://sandbox.moip.com.br/v2/orders/{id}/refunds \
   -H 'Content-Type: application/json'  \
   -H 'Authorization: Basic MDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDE6QUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQg==' \
   -d '{}'
# Por enquanto não disponível no SDK Ruby, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK PHP, veja nosso exemplo em cURL.

Na resposta você recebe a confirmação do reembolso.

{
    "id": "REF-Q6LLDNEBXL52",
    "status": "COMPLETED",
    "amount": {
        "fees": 0,
        "currency": "BRL",
        "total": 4000
[...]
}

Para reembolsar um pedido pago por boleto ou débito online, você precisa enviar na chamada os dados da conta bancária do comprador. O reembolso será feito diretamente para a conta em até 4 dias úteis.

curl -v https://sandbox.moip.com.br/v2/orders/{id}/refunds \
   -H 'Content-Type: application/json'  \
   -H 'Authorization: Basic MDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDE6QUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQg==' \
   -d '{
  "refundingInstrument": {
    "method": "BANK_ACCOUNT",
    "bankAccount": {
      "type": "CHECKING",
      "bankNumber": "001",
      "agencyNumber": 4444444,
      "agencyCheckNumber": 2,
      "accountNumber": 1234,
      "accountCheckNumber": 1,
      "holder": {
        "fullname": "Nome do Portador",
        "taxDocument": {
          "type": "CPF",
          "number": "22222222222"
        }
      }
    }
  }
}'
# Por enquanto não disponível no SDK Ruby, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK PHP, veja nosso exemplo em cURL.

Na resposta você receberá um objeto do tipo Reembolso com a confirmação.

{
  "id": "REF-EUFRIJNZT3SI",
  "status": "REQUESTED",
  [...]
}

Para maiores informações de como utilizar o recurso de reembolso acesse a nossa referência.

Recuperando pagamento cancelado

Para que você possa tentar recuperar seus pagamentos cancelados de maneira simples, o Moip criou as classificações de cancelamento, baseadas nas respostas que recebemos dos bancos. Esta classificação é uma maneira de auxiliá-lo a entender o motivo de cada cancelamento e, ao mesmo tempo, orientá-lo de como tratar cada caso.

Você terá as informações de classificação dos pagamentos cancelados na resposta, no GET e nos webhooks de pagamentos.

Exemplo de classificação de cancelamento.

{
...
  "cancellationDetails": {
    "cancelledBy": "ACQUIRER",
    "description": "Politica do banco emissor",
    "code": "3"
  }
...
}

Exemplo completo de JSON com dados de classificação.

{
  "id": "PAY-4DTXRX7KJYP2",
  "status": "CANCELLED",
  "installmentCount": 1,
  "amount": {
    "refunds": 0,
    "fees": 46,
    "liquid": 54,
    "currency": "BRL",
    "total": 100
  },
  "fees": [
    {
      "type": "TRANSACTION",
      "amount": 46
    }
  ],
  "cancellationDetails": {
    "cancelledBy": "ACQUIRER",
    "description": "Politica do banco emissor",
    "code": "3"
  },
  "fundingInstrument": {
    "creditCard": {
      "id": "CRC-L7VZM4B7U68E",
      "brand": "HIPER",
      "first6": "637095",
      "last4": "0005",
      "holder": {
        "birthdate": "30/12/1988",
        "taxDocument": {
          "type": "CPF",
          "number": "22222222222"
        },
        "fullname": "Jose Silva"
      }
    },
    "method": "CREDIT_CARD"
  },
  "events": [
    {
      "createdAt": "2015-12-07T20:39:39-0200",
      "type": "PAYMENT.CANCELLED"
    },
    {
      "createdAt": "2015-12-07T20:39:37-0200",
      "type": "PAYMENT.CREATED"
    }
  ],
  "_links": {
    "order": {
      "title": "ORD-M05KJCELI74N",
      "href": "https://api.moip.com.br/v2/orders/ORD-M05KJCELI74N"
    },
    "self": {
      "href": "https://api.moip.com.br/v2/payments/PAY-4DTXRX7KJYP2"
    }
  },
  "createdAt": "2015-12-07T20:39:37-0200",
  "updatedAt": "2015-12-07T20:39:39-0200"
}

Importante: Importante: Para manter uma visão de conversão por pedido (mais limpa) use sempre o mesmo pedido para criar um novo pagamento. Nesse cenário em que seu pagamento foi cancelado faça um novo request de pagamento no pedido usado anteriormente com dados de outro cartão de crédito, ou se preferir oferecendo o Boleto como forma de pagamento alternativa.

Vale lembrar que o processamento de multipagamentos é assíncrono, ou seja, você nunca receberá o classificationDetails no response da criação de um multipayment, esse atributo estará nos eventos de webhooks de PAYMENT.CANCELLED e MULTIPAYMENT.CANCELLED, assim como nos GETs do recurso multipagamentos.

Acesse nossa referência API aqui para ver a lista completa dos valores possíveis e como tratar.

Identificando sua marca na fatura

Quando seu cliente contesta o pagamento por não reconhecer a compra que fez acaba gerando diversos problemas em sua operação, e muitas vezes isso acontece simplesmente porque ele não se lembra do que comprou na internet.

Para evitar esse tipo de situação disponibilizamos para você a funcionalidade de “Nome na fatura” ou como chamamos tecnicamente statementDescriptor. Com esse campo você tem a disposição 13 caracteres que pode ser usado para indicar a sua marca na fatura de cartão de crédito do seu comprador, fazendo com que assim ele se lembre da loja, da sua marca e o que se refere esse pagamento em sua fatura.

Você só precisa passar essa informação com o nome desejado na criação de um pagamento com cartão de crédito no Moip. Veja exemplo de JSON abaixo.

{
...
  "statementDescriptor": "Minha loja",
...
}

Exemplo completo de JSON com nome na fatura.

POST /v2/orders/{order_id}/payments
{
  "installmentCount": 1,
  "statementDescriptor": "Minha loja",
  "fundingInstrument": {
    "method": "CREDIT_CARD",
    "creditCard": {
      "hash": "2n9vykIkGX5tegvdl+ow5ngPxP3ItAkp9tc1tzuMTeAuF457uN99CJIG386RD/iV5JPjwr9uCgr0XNYraMulcNJnys2b+A2pl7VcNmO83N5YBkViG+mo9SSCXMcBYBIcGotInur49DpKwylMbMFFWWYFsO/pq8e+zAe6g7dOLcKwkGlVrNL1PKepWxd5ldt44yPZhMeG82eiLxbnXrkAtcY19Phjlg7GIhCj3hjxSYi0Y6iUtLYmTpsVQIs93myH7LLU30gZ88xRMAYbmshi7fc8clfDkLbUPcCCDDYwe6ltFYX1J0YA/TT87Amj9filRlTzLuU9qvKHlXpq2Q/H",
      "holder": {
        "fullname": "Jose Santos",
        "birthdate": "1980-01-02",
        "taxDocument": {
          "type": "CPF",
          "number": "12345679891"
        },
        "phone": {
          "countryCode": "55",
          "areaCode": "11",
          "number": "25112511"
        }
      }
    }
  }
}

Importante: O nome na fatura está disponivel apenas para pagamentos com cartão de crédito nas bandeiras Visa e MasterCard.

Acesse nossa referência API aqui para ver os detalhes de especificações desse campo.

Guia para Assinaturas

O Moip Assinaturas é a solução do Moip para o gerenciamento e cobrança de mensalidades, assinaturas e pagamentos recorrentes. Este produto permite que você faça cobranças de forma automática, no valor e intervalo mais convenientes, por meio da criação de planos que serão oferecidos aos seus clientes.

Atualmente todas as contas do Moip já possuem o Moip Assinaturas habilitado por padrão para uso via interface.

Lembre-se:

A sua integração deve ser realizada sempre em ambiente sandbox. Após finalizar sua integração você deve submeter a aplicação para homologação onde nossa equipe fará a validação, tudo certo com a homologação iremos habilitar as APIs do Moip Assinaturas em sua conta de produção.

Todas as descrições a seguir podem ser executadas tanto usando as APIs do Moip Assinaturas, quanto via interface (usando via interface não requer homologação). Entenda mais sobre as APIs de Assinaturas nas sessões abaixo.

Autenticando no assinaturas

Após o release do Moip Assinaturas de 15/12/2015 a autenticação no Moip assinaturas passa a ser a mesma de sua conta Moip convencional, usando sua conta de produção para se autenticar exclusivamente em produção e sua conta em ambiente de sandbox para se autenticar em sandbox.

Separamos os ambientes para que você tenha mais liberdade em cada ambiente e não se perca no meio do caminho.

Ao iniciar sua integração com o Moip Assinaturas a autenticação a ser usada será o modelo de autenticação básica Basic Authentication. Este modelo permite realizar qualquer ação nas APIs do Moip Assinaturas em sua própria conta.

Veja na sessão Obter chaves de acesso como obter e usar as credenciais de sua conta.

Criando Planos

Fazendo uma analogia simples, um plano está para uma assinatura, assim como um pedido está para um pagamento. O Plano é o objeto que representa um serviço contratado, ele contém as informações base para a criação de uma assinatura, tais como valor, periodicidade, limite de contratações, trial, taxa de contratação e formas de pagamento aceitas.

Caso opte por criar planos através da API é necessário enviar uma requisição semelhante ao que mostramos abaixo:

curl -v https://sandbox.moip.com.br/assinaturas/v1/plans \
-H 'Content-Type: application/json'  \
-H 'Authorization: Basic MDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDE6QUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQg==' \
-d '{
    "code": "plano01",
    "name": "Plano Especial",
    "description": "Descrição do Plano Especial",
    "amount": 990, //em centavos
    "setup_fee": 500, // em centavos
    "max_qty": 1,
    "status": "ACTIVE",
    "payment_method": "CREDIT_CARD", // BOLETO ou ALL    
    "interval": {
        "length": 1,
        "unit": "MONTH"
    },
    "billing_cycles": 12,
    "trial": {
        "days": 30,
        "enabled": true
    }
}'
# Por enquanto não disponível no SDK Ruby, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK PHP, veja nosso exemplo em cURL.

Em resposta você receberá a confirmação de criação do objeto do tipo Plano.

{
    "message": "Plano criado com sucesso"
}

Criando Assinaturas

O Assinante pode contratar um plano criado pelo vendedor das seguintes maneiras:

  • Pelo próprio site do vendedor (caso ele utilize o moip-assinaturas.js ou a integração com as APIs);
  • Solicitando ao vendedor por telefone ou email (nesse caso o vendedor deve criar a assinatura pela área logada).

É importante ressaltar que o cliente não precisa ter cadastro no Moip. O processo de contratação pode ser transparente para ele caso o vendedor utilize o JavaScript ou nossas APIs. É de responsabilidade do vendedor notificar o assinante a respeito de todos os detalhes do plano contratado e também avisá-lo que o pagamento será processado pelo Moip.

Antes de criar uma Assinatura é necessário ter o registro das informações do cliente, incluindo os dados de pagamento (caso a aforma de pagamento seja cartão de crédito). É possível criar o cliente através de uma API específica para esse objeto ou criá-lo no mesmo momento em que é criada a assinatura. Abaixo está o modelo de request criando cliente e assinatura simultaneamente.

curl -v https://sandbox.moip.com.br/assinaturas/v1/subscriptions?new_customer=true \
-H 'Content-Type: application/json'  \
-H 'Authorization: Basic MDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDE6QUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQg==' \
-d '{
    "code": "assinatura01",
    "amount": "9990", // em centavos
    "plan": {
        "code": "plano01"
    },
    "payment_method": "CREDIT_CARD", // ou BOLETO    
    "customer": {
        "code": "cliente01",
        "email": "nome@exemplo.com.br",
        "fullname": "Nome Sobrenome",
        "cpf": "22222222222",
        "phone_number": "934343434",
        "phone_area_code": "11",
        "birthdate_day": "26",
        "birthdate_month": "04",
        "birthdate_year": "1986",
        "address": {
            "street": "Rua nome da Rua",
            "number": "170",
            "complement": "Casa",
            "district": "Bairro",
            "city": "São Paulo",
            "state": "SP",
            "country": "BRA",
            "zipcode": "00000000"
        },
        "billing_info": {
            "credit_card": {
                "holder_name": "Nome Completo",
                "number": "4073020000000002",
                "expiration_month": "04",
                "expiration_year": "15"
            } 
        } // o node billing_info não é necessário em caso de pagamento via boleto
    }
}'
# Por enquanto não disponível no SDK Ruby, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK PHP, veja nosso exemplo em cURL.

Em resposta você receberá a confirmação de criação de um objeto do tipo Assinatura.

{
    "amount": 9990, // em centavos
    "message": "Assinatura criada com sucesso",
    "errors": [],
    "plan": {
        "name": "Plano Especial",
        "code": "plano01"
    },
    "status": "TRIAL",
    "invoice": {
        "amount": 0, // em centavos
        "id": 1000,
        "status": {
            "description": "Pago",
            "code": 3
        }
    },
    "alerts": [],
    "next_invoice_date": {
        "month": 01,
        "year": 2013,
        "day": 31
    },
    "code": "assinatura01",
    "customer": {
        "email": "nome@exemplo.com.br",
        "code": "cliente01",
        "fullname": "Nome e Sobrenome"
    }
}

Caso a forma de pagamento seja boleto, a resposta conterá um node chamado _links, onde haverá uma URL do boleto gerado.

{
    "amount": 9990, // em centavos
    "message": "Assinatura criada com sucesso",
    "errors": [],
    "plan": {
        "name": "Plano Especial",
        "code": "plano01"
    },
  "status": "ACTIVE",
  "invoice": {
    "amount": 100,
    "id": 1330856,
    "status": {
      "description": "Aguardando confirmação",
      "code": 2
    }
  },
  "alerts": [],
  "_links": {
    "boleto": {
      "redirect_href": "https://checkout-sandbox.moip.com.br/boleto/PAY-H1M7FFZ8ZYHQ"
    }
  },
    "next_invoice_date": {
        "month": 01,
        "year": 2013,
        "day": 31
    },
    "code": "assinatura01",
    "customer": {
        "email": "nome@exemplo.com.br",
        "code": "cliente01",
        "fullname": "Nome e Sobrenome"
    }
}

Configurando retentativas de pagamento em Cartão de Crédito

O Moip Assinaturas oferece aos vendedores a opção de configurar retentativas de cobranças, para casos em que uma Assinatura esteja com status “Atrasada”. As retentativas podem ser automáticas (executadas conforme configurado pelo vendedor), ou manuais, mediante ação do lojista ou do assinante.

As retentativas automáticas são executadas em casos onde uma fatura (pagamento periódico) esteja atrasada. Caso o pagamento de uma fatura seja cancelado, a Assinatura receberá o status atrasada e entrará em um fluxo de retentativa, o Moip fará uma nova tentativa de cobrança 1, 3, 5 ou 7 dias após o primeiro cancelamento (de acordo com as preferências configuradas pelo vendedor). Caso essa nova tentativa também seja cancelada, o Moip fará uma nova cobrança e assim consecutivamente até o máximo de 3 retentativas.

A configuração das retentativas pode ser feito diretamente na sua Conta Moip Assinaturas ou por meio do método mostrado abaixo.

curl -v https://sandbox.moip.com.br/assinaturas/v1/users/preferences/retry \
-H 'Content-Type: application/json'  \
-H 'Authorization: Basic MDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDE6QUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQg==' \
-d '
{
    "first_try": 1,
    "second_try": 3,
    "third_try": 5,
    "finally": "cancel"
}'
# Por enquanto não disponível no SDK Ruby, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK PHP, veja nosso exemplo em cURL.

Mudando o plano de uma assinatura (upgrade e downgrade)

Se um vendedor oferecer mais de um plano para seus clientes poderá migrar assinaturas de planos, se necessário, ou seja, ampliar ou reduzir o pacote de serviços.

Para tal, basta enviar uma request sobrescrevendo o plano de uma assinatura.

curl -v https://sandbox.moip.com.br/assinaturas/v1/subscriptions/{subscription_code} \
-H 'Content-Type: application/json'  \
-H 'Authorization: Basic MDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDEwMTAxMDE6QUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQkFCQUJBQg==' \
-d '{
    "plan": {
        "code": "codigo_do_novo_plano"
    },
    "amount": "9990", // informe apenas se quiser sobrescrever o valor do plano (em centavos)
    "next_invoice_date": {
        "day": "05",
        "month": "01",
        "year": "2013"
    }
}'
# Por enquanto não disponível no SDK Ruby, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK PHP, veja nosso exemplo em cURL.

Alterações de status

Status de uma assinatura

Uma assinatura pode passar por diversos status durante o seu ciclo de vida, abaixo temos a relação dos status que uma assinatura pode ter.

1 - “Active”

A assinatura está ativa, ou seja, o cliente assinante será cobrado a cada ciclo.

2 - “Suspended”

As cobranças da assinatura estão suspensas, ou seja, o cliente assinante não será cobrado a cada ciclo.

3 - “Expired”

A assinatura está expirada, ou seja, já atingiu o limite de cobranças configuradas no plano contratado e não gerará mais cobranças.

4 - “Overdue”

A assinatura está com o pagamento de sua fatura atrasada e entrou no fluxo de retentativas. Para saber mais sobre retentativas de pagamentos, clique aqui.

5 - “Canceled”

A assinatura foi cancelada e não poderá mais ser reativada ou editada de nenhuma maneira. Em outras palavras, o cancelamento é a inativação definitiva de uma assinatura.

6 - “Trial”

O trial é um período de testes de uma assinatura, ele pode ter uma taxa de inscrição ou ser gratuito. Para configurar as preferências do seu trial, você deve utilizar a API de Planos ou utilizar a interface do Moip Assinaturas.

Fluxo

[A] - Após criada, a Assinatura gera uma nova fatura;

[B] - Dentro da fatura, foi criado um novo pagamento;

[C] - O pagamento foi “Iniciado” no Moip Assinaturas;

[D] - O pagamento tem o status “Iniciado” ou “Em análise”, o status da fatura é “Aguardando Confirmação”;

[E] - Enquanto o pagamento e fatura estão no cenário (D), a Assinatura mantém o status “Ativo”.

[F] - Quando o pagamento é “Autorizado” o status da fatura torna-se “Paga” e a Assinatura continua “Ativa”;

[G] - O pagamento que estava “Autorizado”/”Concluído” foi “Estornado” ou “Reembolsado”;

[H] - O pagamento foi “Cancelado”;

[I] - O pagamento “Estornado”/”Reembolsado” muda o status da fatura para “Não Paga”;

[J] - A terceira retentativa automática de pagamento foi executada, a fatura torna-se “Não paga”;

[K] - O primeiro pagamento da fatura foi cancelado e ela entrou no fluxo de retentativa automática, a fatura torna-se “Atrasada”;

[L] - A primeira ou a segunda ou retentativa de pagamento foi cancelada, a fatura continua no fluxo de retentativa automática;

[M] - A fatura “Paga” mantém a assinatura “Ativa”;

[N] - A fatura “Não Paga”, suspende a assinatura.

[O] - Os cenários (K) ou (L) alteraram o status da assinatura para “Atrasada”;

[P] - Após o prazo determinado no plano a assinatura expirou;

[Q] - Os cenários (K) e (L) foi executada uma retentativa automática.

Status de uma fatura

É importante conhecer e entender os status da fatura e suas possíveis transições para gerenciar inadimplência e permissão aos serviços contratados em seu sistema.

Código Descrição O que significa?
1 Em aberto A fatura foi gerada mas ainda não foi paga pelo assinante.
2 Aguardando confirmação A fatura foi paga pelo assinante, mas o pagamento está em processo de análise de risco.
3 Pago A fatura foi paga pelo assinante e confirmada.
4 Não pago O assinante tentou pagar a fatura, mas o pagamento foi negado pelo banco emissor do cartão de crédito ou a análise de risco detectou algum problema. Veja os motivos possíveis.
5 Atrasada O pagamento da fatura foi cancelado e serão feitas novas tentativas de cobrança de acordo com a configuração de retentativa automática.

Transições de status:

Transições de status [A] O pagamento está em análise. [B] O pagamento foi autorizado. [C] O pagamento foi cancelado, veja aqui os possíveis motivos. [D] O pagamento foi cancelado e entrou no fluxo de retentativas. [E] O pagamento teve um reembolso/chargeback. [F] O pagamento de retentativa foi cancelado. [G] O pagamento de retentativa foi autorizado.

Sugestões de termos

Como no modelo de cobranças recorrentes a sua empresa possui um vínculo comercial mais forte e contínuo com o cliente, é necessário apresentar aos seus clientes Termos e Condições da contratação do seu produto ou serviço. Abaixo, uma sugestão de modelo de contrato, que deve ser adaptado às especificidades de sua empresa.

| Importante | trata-se apenas de um exemplo de Termos. É altamente recomendado a consulta a um escritório de advocacia para saber quais devem ser os termos para o seu tipo de negócio.|

Exemplo

Guia para Marketplaces

O Moip Marketplace possui o pacote completo para viabilizar a implementação de soluções de pagamento dentro de uma plataforma (ou marketplace). Utilizando o serviço é possível:

  • Receber e gerenciar pagamentos em nome dos seus usuários vendedores
  • Facilitar o cadastro dos seus vendedores no Moip
  • Dividir um pagamento para mais de uma conta Moip em tempo real
  • Cobrar pela sua tarifa de serviços diretamente em uma transação
  • Definir qual das partes envolvidas em um pagamento dividido é responsável por arcar com as tarifas do Moip
  • Realizar pagamentos para vários vendedores em um mesmo carrinho de compras
  • Usar eventos para controlar quando os vendedores receberão os valores das vendas

Para saber como executar as ações acima, leia as próximas sessões:

Entendendo a estrutura de pagamentos divididos

A transação mais simples que pode ser gerada com as APIs do Moip possui um Pagador e um único Recebedor. Este é o padrão utilizado para as transações tradicionais no e-commerce.

ecommerce

O Moip permite que um pagamento realizado seja dividido (split) entre Contas Moip diferentes em tempo real. Este esquema viabiliza o uso do Moip como solução para Marketplaces/Plataformas por facilitar o pagamento da cadeia de envolvidos, permitindo o funcionamento de diversos modelos de negócios.

recebedor_secundario

Os recebedores secundários não possuem relação com os compradores. Isto é, um comprador que realiza um pagamento, neste esquema, não “enxerga” o recebedor secundário na transação, nem a forma com que os pagamentos foram divididos entre as partes. Pode haver mais de um recebedor secundário por transação, mas só um recebedor primário.

Abaixo um quadro comparativo com as características de cada papel assumido em uma transação dividida.

Funcionalidade Pagador Recebedor primário Recebedor secundário
Obrigatoriedade na transação Sim Sim Não
Obrigatoriedade de Conta Moip Não Sim, conta negócios Sim, conta negócios
Relacionamento comercial com pagador Sim Sim Não
Recebimento de e-mails Não Não Não
Reembolsos Pode solicitar Pode realizar Não, mas tem saldo debitado
Reclamações e disputas Pode abrir Responde Não, mas tem o saldo bloqueado/debitado
Contestações (chargebacks) Pode abrir Responde Não, mas tem o saldo bloqueado/debitado
Relatórios transacionais Visualiza apenas recebedor Visualiza pagador e recebedores secundários Visualiza pagador e recebedor primário
Tarifa Moip Não paga Paga por padrão Paga se configurado
NF-e de serviços do Moip Não recebe Recebe por padrão Recebe caso pague a tarifa

Uma vez definido o escopo de seu negócio você pode utilizar as APIs do moip para fazer a divisão dos valores de acordo com sua necessidade.

Conectando com a Conta Moip de seus usuários

Para gerenciar os pagamentos em nome de seus usuários é necessário que você crie um Aplicativo no Moip para o seu Marketplace ou Plataforma.

Registrado o aplicativo, o próximo passo é conectá-lo às Contas Moip dos seus seu usuários. Você também pode optar por criar Contas Moip transparentes e com isso gerenciar toda a gestão de saldos e transferências bancárias em sua própria plataforma. Neste caso o seu usuário não precisa acessar a área administrativa do Moip e o resultado é uma experiência transparente.

A conexão (seja transparente ou não) é necessária para que você possa processar os pagamentos diretamente para os usuários, sem se envolver, como intermediário. Veja como realizar a conexão na documentação do Moip Connect.

Criando um pedido simples para a Conta Moip de um usuário

Feita a conexão com o seu aplicativo, já é possível começar a processar transações na Conta Moip do seu usuário vendedor. Para isso, basta realizar a chamada de criação de um Pedido utilizando como autenticação o token Oauth do usuário obtido por meio do Moip Connect.

curl -v https://sandbox.moip.com.br/v2/orders \
-H 'Content-Type: application/json'  \
-H 'Authorization: OAuth 79u55ov666d09u3xs4j4n50pq5mdnh8' \
-d '{
  "ownId": "id_proprio",
  "amount": {
    "currency": "BRL"
  },
  "items": [
    {
      "product": "Bicicleta Specialized Tarmac 26 Shimano Alivio",
      "quantity": 1,
      "detail": "uma linda bicicleta",
      "price": 10000
    }
  ],
  "customer": {
    "ownId": "meu_id_de_cliente",
    "fullname": "Jose Silva",
    "email": "josedasilva@email.com",
    "birthDate": "1988-12-30",
    "taxDocument": {
      "type": "CPF",
      "number": "22222222222"
    },
    "phone": {
      "countryCode": "55",
      "areaCode": "11",
      "number": "66778899"
    },
    "shippingAddress": 
      {
        "street": "Avenida Faria Lima",
        "streetNumber": 2927,
        "complement": 8,
        "district": "Itaim",
        "city": "Sao Paulo",
        "state": "SP",
        "country": "BRA",
        "zipCode": "01234000"
      }
  }
}'

# Por enquanto não disponível no SDK Ruby, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK PHP, veja nosso exemplo em cURL.

resposta:


{
  "id": "ORD-K0PUM2WCISFC",
  "ownId": "id_do_meu_pedido_xxxyyyzzz",

  [...]

  "receivers": [
    {
      "amount": {
        "refunds": 0,
        "fees": 0,
        "total": 10500
      },
      "moipAccount": {
        "fullname": "Lojista 1 Moip",
        "login": "lojista_1@labs.moip.com.br",
        "id": "MPA-VB5OGTVPCI52"
      },
      "type": "PRIMARY"
    }
  ]

  [...]

}

A identificação do recebedor sempre será retornada pelo Moip na criação do pedido, assim como o seu papel na transação (PRIMARY ou SECONDARY).

Criando um pedido dividido (split)

As APIs do Moip permitem que um pedido seja dividido para 2 (ou mais recebedores). Isto é, parte do total do pagamento, será liquidado na Conta Moip de um recebedor e a outra parte na Conta Moip de outro recebedor. Esta funcionalidade pode ser utilizada, por exemplo, para realizar a cobrança da taxa de serviço do seu Marketplace em tempo real (na própria transação). Uma outra aplicação é o pagamento de comissões para terceiros envolvidos em uma transação comercial.

Abaixo são listadas algumas características da transação divida que devem ser levadas em consideração ao usar a funcionalidade.

Responsável pelo relacionamento com o comprador

Apesar do pagamento ser dividido em 2 (ou mais) partes, sempre uma delas, deve ser a parte responsável pela venda e pelo relacionamento com o consumidor final. Chamamos esta entidade de Recebedor primário. O tratamento de disputas, contestações e reembolsos, apenas pode ser realizado por ele. Da mesma forma, toda a comunicação recebida para o consumidor final, tais como e-mail e o nome na fatura do cartão, são identificados com os dados do recebedor primário. Plataformas de e-commerce e Marketplaces com a característica de “classificados” tendêm a optar por definir seus vendedores como Recebedores primários. Ao contrário, Marketplaces que queiram gerenciar o relacionamento com o consumidor, definem os vendedores como recebedores secundários tornando-os “fornecedores” dos produtos/serviços.

Para definir o seu usuário vendedor como “Recebedor primário” basta que você utilize o token Oauth dele para criar o pedido. Desta forma o seu usuário será o resource owner do pedido que foi criado. Para tornar o Marketplace o Recebedor primário, utilize o token do Marketplace na criação do pedido.

Valor a ser dividido

As regras de divisão são configuradas por pedido. A divisão pode ser feita: i) por meio de um valor percentual de 0 a 100% (exemplo: 20%) ou ii) por meio de um valor fixo (exemplo: R$5,00).

{
[...]
    "receivers": [
        {
            "moipAccount": {
                "id": "MPA-OXZ6ULK9A5"
            },
            "type": "SECONDARY",
            "amount": {
                "percentual": 20
            }
        },
        {
            "moipAccount": {
                "id": "MPA-73YA1Y4R0B"
            },
            "type": "SECONDARY",
            "amount": {
                "fixed": 1000
            }
        }
    ]
[...]
}

Responsável pela tarifa de processamento de pagamentos do Moip

A tarifa do Moip pode ser paga por um responsável específico, ou todas as partes envolvidas no pagamento. Esta também é uma definição que varia de acordo com o modelo de negócios do Marketplace. Por padrão o Recebedor primário é o responsável pelo pagamento das tarifas. Para alterar esta configuração basta incluir a informação no JSON.

Definindo um responsável específico

{
[...]
     "payerFee": {
        "payer": "SPECIFIC_RECEIVERS",
        "specificReceivers": [
            {
                "id": "MPA-OXZ6ULK9A5"
            }
        ]
    }
[...]
}

Definindo que todas as partes são responsáveis

{
[...]
     "payerFee": {
        "payer": "ALL"
    }
[...]
}

Abaixo um exemplo completo da criação de um pedido dividido para um Marketplace.

{
  "ownId": "id_proprio",
  "amount": {
    "currency": "BRL"
  },
  "items": [
    {
      "product": "Bicicleta Specialized Tarmac 26 Shimano Alivio",
      "quantity": 1,
      "detail": "uma linda bicicleta",
      "price": 10000
    }
  ],
  "customer": {
    "ownId": "meu_id_de_cliente",
    "fullname": "Jose Silva",
    "email": "josedasilva@email.com",
    "birthDate": "1988-12-30",
    "taxDocument": {
      "type": "CPF",
      "number": "22222222222"
    },
    "phone": {
      "countryCode": "55",
      "areaCode": "11",
      "number": "66778899"
    },
    "shippingAddress": {
      "street": "Avenida Faria Lima",
      "streetNumber": 2927,
      "complement": 8,
      "district": "Itaim",
      "city": "Sao Paulo",
      "state": "SP",
      "country": "BRA",
      "zipCode": "01234000"
    }
  },
  "receivers": [
    {
      "moipAccount": {
        "id": "MPA-OXZ6ULK9A5"
      },
      "type": "SECONDARY",
      "amount": {
        "percentual": 20
      }
    },
    {
      "moipAccount": {
        "id": "MPA-73YA1Y4R0B"
      },
      "type": "SECONDARY",
      "amount": {
        "fixed": 1000
      }
    }
  ]
}

Criando pedidos com mais de um lojista

Para implementar transações em que mais de um vendedor esteja presente em uma mesma compra (carrinho compartilhado) o Moip disponibiliza o recurso Multipedido. De forma geral, o Multipedido é uma lista de Pedidos, que pode ser cobrada por meio de uma única chamada de pagamento. Desta forma, é possível, fazer com que em um único clique do usuário, ou com o pagamento de um único boleto, todos os pedidos sejam pagos individualmente e tenham seus próprios pagamentos associados a ele. Esta implementação auxilia o pós-venda facilitando o tratamento de reembolsos, disputas e contestações.

Carrinho Compartilhado

Lembrando que, para que você possa envolver outros lojistas em um Multipedido é necessário que você obtenha os seus ids após ter recebido a permissão dos mesmos através do Moip Connect.

Abaixo um exemplo de criação de um Multipedido.

curl -v https://sandbox.moip.com.br/v2/multiorders \
-H 'Content-Type: application/json'  \
-H 'Authorization: OAuth qguusgp05mxaa9adyy8kvo4nuq380z7' \
-d '{
  "ownId": "meu_multiorder_id",
  "orders": [
    {
      "ownId": "pedido_1_id",
      "amount": {
        "currency": "BRL",
        "subtotals": {
          "shipping": 2000
        }
      },
      "items": [
        {
          "product": "Camisa Verde e Amarelo - Brasil",
          "quantity": 1,
          "detail": "Seleção Brasileira",
          "price": 2000
        }
      ],
      "customer": {
        "ownId": "customer[1234]",
        "fullname": "Joao Sousa",
        "email": "joao.sousa@email.com",
        "birthDate": "1988-12-30",
        "taxDocument": {
          "type": "CPF",
          "number": "22222222222"
        },
        "phone": {
          "countryCode": "55",
          "areaCode": "11",
          "number": "66778899"
        },
        "shippingAddress": 
          {
            "street": "Avenida Faria Lima",
            "streetNumber": 2927,
            "complement": 8,
            "district": "Itaim",
            "city": "Sao Paulo",
            "state": "SP",
            "country": "BRA",
            "zipCode": "01234000"
          }
      },
      "receivers": [
        {
          "moipAccount": {
            "id": "MPA-VB5OGTVPCI52"
          },
          "type": "PRIMARY"
        }
      ]
    },
    {
      "ownId": "pedido_2_id",
      "amount": {
        "currency": "BRL",
        "subtotals": {
          "shipping": 3000
        }
      },
      "items": [
        {
          "product": "Camisa Preta - Alemanha",
          "quantity": 1,
          "detail": "Camiseta da Copa 2014",
          "price": 1000
        }
      ],
      "customer": {
        "ownId": "customer[1234]",
        "fullname": "Joao Sousa",
        "email": "joao.sousa@email.com",
        "birthDate": "1988-12-30",
        "taxDocument": {
          "type": "CPF",
          "number": "22222222222"
        },
        "phone": {
          "countryCode": "55",
          "areaCode": "11",
          "number": "66778899"
        },
        "shippingAddress": 
          {
            "street": "Avenida Faria Lima",
            "streetNumber": 2927,
            "complement": 8,
            "district": "Itaim",
            "city": "Sao Paulo",
            "state": "SP",
            "country": "BRA",
            "zipCode": "01234000"
          }
      },
      "receivers": [
        {
          "moipAccount": {
            "id": "MPA-IFYRB1HBL73Z"
          },
          "type": "PRIMARY"
        },
        {
          "moipAccount": {
            "id": "MPA-KQB1QFWS6QNM"
          },
          "type": "SECONDARY",
          "amount": {
            "fixed": 55
          }
        }
      ]
    }
  ]
}'
# Por enquanto não disponível no SDK Ruby, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK PHP, veja nosso exemplo em cURL.

Retorno do json.

{
  "id": "MOR-X5X9RRHBT2ZY",
  "ownId": "meu_multiorder_id",
  "status": "CREATED",
  "createdAt": "2015-01-22T17:43:10-0200",
  "updatedAt": "",
  "amount": {
    "total": 8000,
    "currency": "BRL"
  },
  "orders": [
    {
      "id": "ORD-K32PRY8P4RKX",
      "ownId": "pedido_1_id",

      [...]

      "receivers": [
        {
          "amount": {
            "refunds": 0,
            "fees": 0,
            "total": 4000
          },
          "moipAccount": {
            "fullname": "Lojista 4 Moip",
            "login": "lojista_4@labs.moip.com.br",
            "id": "MPA-VB5OGTVPCI52"
          },
          "type": "PRIMARY"
        }
      ],

        [...]

    },
    {
      "id": "ORD-IN18JU0RRI0C",
      "ownId": "pedido_2_id",
      [...]
      "receivers": [
        {
          "amount": {
            "refunds": 0,
            "fees": 0,
            "total": 3945
          },
          "moipAccount": {
            "fullname": "Lojista 3 Moip",
            "login": "lojista_3@labs.moip.com.br",
            "id": "MPA-IFYRB1HBL73Z"
          },
          "type": "PRIMARY"
        },
        {
          "amount": {
            "refunds": 0,
            "total": 55
          },
          "moipAccount": {
            "fullname": "Maria da Silva Santos",
            "login": "secundario_1@labs.moip.com.br",
            "id": "MPA-KQB1QFWS6QNM"
          },
          "type": "SECONDARY"
        }

      [...]

  }
}

Com o Id do Multipedido em mãos, já é possível realizar a cobrança por meio da criação de um multipagamento, como no exemplo abaixo:

Exemplo de Multipayment com Cartão de crédito

curl -v https://sandbox.moip.com.br/v2/multiorders/{id}/multipayments \
-H 'Content-Type: application/json'  \
-H 'Authorization: OAuth qguusgp05mxaa9adyy8kvo4nuq380z7' \
-d '{
    "installmentCount": 1,
    "fundingInstrument": {
        "method": "CREDIT_CARD",
        "creditCard": {
            "hash": "2n9vykIkGX5tegvdl+ow5ngPxP3ItAkp9tc1tzuMTeAuF457uN99CJIG386RD/iV5JPjwr9uCgr0XNYraMulcNJnys2b+A2pl7VcNmO83N5YBkViG+mo9SSCXMcBYBIcGotInur49DpKwylMbMFFWWYFsO/pq8e+zAe6g7dOLcKwkGlVrNL1PKepWxd5ldt44yPZhMeG82eiLxbnXrkAtcY19Phjlg7GIhCj3hjxSYi0Y6iUtLYmTpsVQIs93myH7LLU30gZ88xRMAYbmshi7fc8clfDkLbUPcCCDDYwe6ltFYX1J0YA/TT87Amj9filRlTzLuU9qvKHlXpq2Q/H",
            "holder": {
                "fullname": "Jose Santos",
                "birthdate": "1980-01-02",
                "taxDocument": {
                    "type": "CPF",
                    "number": "12345679891"
                },
                "phone": {
                    "countryCode": "55",
                    "areaCode": "11",
                    "number": "25112511"
                }
            }
        }
    }
}'
# Por enquanto não disponível no SDK Ruby, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK PHP, veja nosso exemplo em cURL.

resposta:

{
  "id": "MPY-1JOENEKJF2PM",
  "status": "WAITING",
  "amount": {
    "total": 8000,
    "currency": "BRL"
  },
  "installmentCount": 2,
  "payments": [
    {
      "id": "PAY-Z2U55OS1OC1B",
      "status": "WAITING",
      [...]
   },
    {
      "id": "PAY-KAY5LQK9G4X4",
      "status": "WAITING",
      [...]
  }
}

Neste caso, o Moip irá gerar um pagamento para cada Pedido no seu respectivo valor e na fatura do consumidor serão gerados lançamentos distintos. Com isso, em caso de problema de desacordo comercial com um vendedor, os demais não serão envolvidos.

O preceito de criação de pagamento para o multipedido é o mesmo de pagamentos para pedidos, sendo assim para criar um pagamento por boleto ou débito basta utilizar a mesma estrutura utilizada na criação de pagamentos para pedidos, porém com a url e o id do Multipedido.

Exemplo de Multipayment com Boleto bancário

curl -v https://sandbox.moip.com.br/v2/multiorders/{id}/multipayments \
-H 'Content-Type: application/json'  \
-H 'Authorization: OAuth qguusgp05mxaa9adyy8kvo4nuq380z7' \
-d '{
  "fundingInstrument": {
    "method": "BOLETO",
    "boleto": {
      "expirationDate": "2020-09-30",
      "instructionLines": {
        "first": "Primeira linha se instrução",
        "second": "Segunda linha se instrução",
        "third": "Terceira linha se instrução"
      },
      "logoUri": "http://"
    }
  }
}'
# Por enquanto não disponível no SDK Ruby, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK PHP, veja nosso exemplo em cURL.

resposta:

{
  "id": "MPY-7X3JO2E2AMFL",
  "status": "WAITING",
  "amount": {
    "currency": "BRL",
    "total": 8000
  },
  "installmentCount": 1,
  "fundingInstrument": {
    "boleto": {
      "expirationDate": "2016-09-30",
      "lineCode": "23793.39126 60000.032957 96001.747904 7 69330000008000",
      "instructionLines": {
        "third": "Terceira linha se instrução",
        "second": "Segunda linha se instrução",
        "first": "Primeira linha se instrução"
      }
    },
    "method": "BOLETO"
  },
  "payments": [
    {
      "id": "PAY-FJ6MWU4YM7YO",
      "status": "WAITING",
      [...]
    },
    {
      "id": "PAY-TRYJXY9V2KR0",
      "status": "WAITING",
      [...]
    }
  ],
  "_links": {
    "multiorder": {
      "href": "https://sandbox.moip.com.br/v2/multiorders/MOR-QXZKIF6GPN5V"
    },
    "self": {
      "href": "https://sandbox.moip.com.br/v2/multipayments/MPY-7X3JO2E2AMFL"
    },
    "checkout": {
      "payBoleto": {
        "redirectHref": "https://checkout-sandbox.moip.com.br/boleto/MPY-7X3JO2E2AMFL"
      }
    }
  }
}

Acesse a referência de nossa API caso queira informações completas sobre o recurso.

Criptografia

Para aumentar a segurança das transações e reduzir o escopo da sua certificação PCI Compliance essa API trabalha com o conceito de criptografia ponta-a-ponta. Isto é, os dados sensíveis de cartão de crédito são criptografados nas aplicações clientes (browser, apps nativos) e somente são decriptografados nos servidores do Moip. Veja abaixo o passo-a-passo de como realizar criptografia nos principais clientes:

Obtendo uma chave pública

As chaves públicas de criptografia são disponibilizadas dentro de sua Conta Moip. Acesse pelo link da conta de sandbox ou de produção caso já esteja preperado para transacionar de verdade.

Criptografia no Browser

Como o Moip.js é uma biblioteca client-side e está disponível em nosso GitHub, você deve utilizá-lo caso esteja fazendo a criptografia dos dados do cliente no browser ou em apps que rodem em frameworks html5 (Ionic, Meteor, etc.). Para integrações em ambientes Mobile você deve criptografar os dados usando nossos sdks (Android e iOS).

Para fazer a criptografia dos dados do seu cliente, primeiramente importe o Moip.js:

<script type="text/javascript" src="//assets.moip.com.br/v2/moip.min.js"></script>

Você também deve incluir o script que fará a criptografia em sua página:

  <script type="text/javascript">
    $(document).ready(function() {
        $("#encrypt").click(function() {
          var cc = new Moip.CreditCard({
            number  : $("#number").val(),
            cvc     : $("#cvc").val(),
            expMonth: $("#month").val(),
            expYear : $("#year").val(),
            pubKey  : $("#public_key").val()
          });
          console.log(cc);
          if( cc.isValid()){
            $("#encrypted_value").val(cc.hash());
          }
          else{
            $("#encrypted_value").val('');
            alert('Invalid credit card. Verify parameters: number, cvc, expiration Month, expiration Year');
          }
        });
    });
  </script>

Com o Moip.js em sua página, basta que você crie os campos de seu checkout referênciando o script que irá fazer a criptografia dos dados do pagamento.

Formulário HTML

Insira a sua chave pública em um campo com o id correspondente na sua função que faz a comunicação com o Moip.js.

<textarea id="public_key" style="display:none;">
  -----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsXkulsKdAQLMH/zjzTLf
0lrbgulfb6ZShEtRpmDnyX93EQqPdez7LyptvQBeTC+0pN57rNcWen9ApdsIMsNr
YHjNQf/kI4Ka7Xnlx0U/v7bW1D8teDoD5glBTXLjU8hRi7qlOpupiPx4ldSnK9Jj
tYApWuZMiCpWh/YRAlNW/N+ffm7ulq6H2atmgd+OFB2SghpbRJkqJiLaNJW8UkaR
oXLHkF5WJD/RPrCxsZztYJQThxLX5gBgZ12YG5+7G26Ad/mWkPqF0GLSkd1gcnbP
vF9Nw3ckKaIvh4Q4Vp3XI1hLvX41lg9CBxPPHkiJwM1M1coF9xsMP7kpJ2eujMBd
mwIDAQAB
-----END PUBLIC KEY-----</textarea>

Você também deve criar um campo referente a cada parâmetro que devem ser enviados para o Moip:

<input type="text" placeholder="Credit card number" id="number"/>
<input type="text" placeholder="CVC" id="cvc"/>
<input type="text" placeholder="Month" id="month"/>
<input type="text" placeholder="Year" id="year" />

Com os dados criptografados, você receberá o hash dos dados do cartão de crédito do cliente cc.hash() que será utilizado no momento do pagamento.

Criptografia no Android

Criamos um SDK para facilitar a criptografia dos dados do cartão de seu cliente em apps Android nativos. Em nosso Github você pode encontrar um zip com as dependências para que você adicione o sdk em seu projeto. Caso você utilize o Gradle você pode utilizar a linha abaixo:

  compile 'com.madgag.spongycastle:pkix:1.51.0.0'

Para fazer a criptografia dos dados do cartão, você deve adicionar a sua chave pública em seu app.

   final String PUBLIC_KEY = "-----BEGIN PUBLIC KEY-----\n"+
        "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoBttaXwRoI1Fbcond5mS\n"+
        "7QOb7X2lykY5hvvDeLJelvFhpeLnS4YDwkrnziM3W00UNH1yiSDU+3JhfHu5G387\n"+
        "O6uN9rIHXvL+TRzkVfa5iIjG+ap2N0/toPzy5ekpgxBicjtyPHEgoU6dRzdszEF4\n"+
        "ItimGk5ACx/lMOvctncS5j3uWBaTPwyn0hshmtDwClf6dEZgQvm/dNaIkxHKV+9j\n"+
        "Mn3ZfK/liT8A3xwaVvRzzuxf09xJTXrAd9v5VQbeWGxwFcW05oJulSFjmJA9Hcmb\n"+
        "DYHJT+sG2mlZDEruCGAzCVubJwGY1aRlcs9AQc1jIm/l8JwH7le2kpk3QoX+gz0w\n"+
        "WwIDAQAB\n"+
        "-----END PUBLIC KEY-----";

Após adicionar sua chave pública, você deve criar o objeto Credit Card.

    CreditCard creditCard = new CreditCard();
        creditCard.setCvc("123");
        creditCard.setNumber("4340948565343648");
        creditCard.setExpirationMonth("12");
        creditCard.setExpirationYear("2030");
        creditCard.setPublicKey(PUBLIC_KEY);

Uma vez que você tem o objeto com os dados do cartão de seu cliente, você deverá utilizar o método encrypt(), esse método fará a criptografia dos dados do cartão criado por você.

 try{
        creditCard.encrypt();
    }catch(MoipEncryptionException mee){

    }

Após a criptografia ocorrer você receberá uma string que será correspondente a um hash do cartão de crédito, com esse hash em mãos você poderá criar um Pagamento ou um Multipagamento no Moip.

Criptografia no iOS

Após fazer a integração da criação dos pedidos em sua aplicação no iOS, você deve utilizar o nosso SDK (open source) para fazer a criptografia dos dados e assim poder criar pagamentos sem se preocupar com o escopo PCI. O SDK iOS está em nosso Github.

O primeiro passo para fazer a criptografia é importar o SDK em sua aplicação.

#import <MoipSDK/MoipSDK.h>

Após importar o sdk, você deve adicionar a sua chave pública em seu app.

NSString *myPublicKey = @"-----BEGIN PUBLIC KEY-----\n"+
        "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoBttaXwRoI1Fbcond5mS\n"+
        "7QOb7X2lykY5hvvDeLJelvFhpeLnS4YDwkrnziM3W00UNH1yiSDU+3JhfHu5G387\n"+
        "O6uN9rIHXvL+TRzkVfa5iIjG+ap2N0/toPzy5ekpgxBicjtyPHEgoU6dRzdszEF4\n"+
        "ItimGk5ACx/lMOvctncS5j3uWBaTPwyn0hshmtDwClf6dEZgQvm/dNaIkxHKV+9j\n"+
        "Mn3ZfK/liT8A3xwaVvRzzuxf09xJTXrAd9v5VQbeWGxwFcW05oJulSFjmJA9Hcmb\n"+
        "DYHJT+sG2mlZDEruCGAzCVubJwGY1aRlcs9AQc1jIm/l8JwH7le2kpk3QoX+gz0w\n"+
        "WwIDAQAB\n"+
        "-----END PUBLIC KEY-----";
[MoipSDK importPublicKey:myPublicKey];
MPKCreditCard *creditCard = [MPKCreditCard new];
creditCard.number = @"4111111111111111";
creditCard.cvc = @"999";
creditCard.expirationMonth = @"07";
creditCard.expirationYear = @"15";

Após adicionar sua chave pública, você deve criar o objeto Credit Card.

Com o objeto criado, você irá utilizar nosso método para criptografar os dados do cartão.

NSString * cryptData = [MoipSDK encryptCreditCard:creditCard];

Fazendo a criptografia você receberá um hash do cartão de crédito(string), uma vez que você tiver esse hash você poderá criar um Pagamento ou um Multipagamento no Moip.

Moip Connect

O Moip Connect permite que a sua aplicação, seja ela um Marketplace, um App para chamar serviços, uma plataforma de e-commerce, ou qualquer sistema que auxilie pessoas ou empresas a receber pagamentos, possa ter acesso à Contas Moip dos seus usuários. Você registra o seu aplicativo no Moip, conecta com as Contas Moip clássicas dos seus usuários ou cria Contas Transparentes e com isso você passa a ter permissão para:

  • Processar pagamentos em nome dos seus usuários
  • Obter dados das Contas Moip dos seus usuários

Existem duas formas de utilizar o Connect: i) obtendo permissões para utilizar Contas Moip clássicas de usuários do Moip por meio do OAuth 2.0 ou ii) criando Contas transparentes gerenciadas pelo seu próprio aplicativo.

Leia as próximas sessões e entenda mais sobre o Moip Connect:

Contas Moip clássicas

Conta Moip clássica é a conta Moip gerenciada pelo próprio usuário. Isto é, o seu usuário (vendedor de um Marketplace ou prestador de serviço do seu App) é responsável por criar a Conta (pelo site Moip ou pelo Cadastro facilitado em seu site ou app), pode acessar a área administrativa da Conta Moip, realiza o cadastro e transferências para contas bancárias. Geralmente este tipo de integração é indicado para:

  • implementações rápidas de Marketplaces e plataformas pois requer menos codificação
  • conectar com usuários que já possuam Contas Moip (mercado de e-commerce por exemplo)
  • deixar a cargo do Moip toda a comunicação referente a gestão do dinheiro dos seus usuários (relatórios, saques, limites, validação de conta e etc)

Contas Moip transparentes

Conta Moip transparente é uma Conta Moip criada para o seu usuário que será utilizada apenas dentro do contexto do seu aplicativo. Isto é, o usuário, excluindo o aceite dos termos (que pode ser realizado no seu site/app) praticamente não tem visibilidade da Conta e toda a gestão é realizada pela sua plataforma. Por meio de APIs, você pode alterar dados cadastrais, incluir contas bancárias e realizar transferências em nome do usuário. Este tipo de integração é indicado para:

  • marketplaces e plataformas que querem ter controle completo da experiência de repasse para vendedores e prestadores de serviço
  • simplificar a comunicação com usuários por meio de apenas um canal. Neste caso o Moip não entra em contato com os usuários, apenas o App.
  • quem quer gerir de forma personalizada os riscos de chargeback e de uso indevido do Marketplace e/ou plataforma

Registrando seu aplicativo

Para gerenciar os pagamentos em nome de seus usuários vendedores é necessário que você crie um Aplicativo no Moip. Para isso durante o beta você deve solicitar a criação do seu APP para nosso time, acesse aqui e solicite o cadastro de seu APP.

Você irá receber as seguintes informações:

  • ID do aplicativo appId
  • Chave privada do aplicativo appSecret
  • Token de autenticação do aplicativo accessToken

Com elas você irá montar o link para solicitar permissão e para a gerar o token OAuth(accessToken) da conta Moip do seu usuário.

Criando uma Conta Moip clássica

Para criar uma Conta Moip clássica você deve realizar uma chamada informando uma coleção de dados. Os dados obrigatórios são importante por questões regulatórias e de segurança. O usuário irá receber em seu e-mail um link para a confirmação do cadastro e para a definição de sua senha. Neste caso, o aceite dos termos de uso do Moip, deve ser realizado em seu website/app. Abaixo um exemplo da criação de uma conta.

O cadastro de seu cliente deve ser feito pela url https://sandbox.moip.com.br/v2/accounts utilizando o token OAuth (accessToken) do seu Aplicativo na autenticação.

curl -v https://sandbox.moip.com.br/v2/accounts \
-H 'Content-Type: application/json'  \
-H 'Authorization: OAuth 1tldio91gi74r34zv30d4saz8yuuws5' \
-d '{
    "email": {
        "address": "email@dominio.com.br"
    },
    "person": {
        "name": "José da Silva Junior",
        "taxDocument": {
            "type": "CPF",
            "number": "222.222.222-22"
        },
        "identityDocument": {
            "type": "RG",
            "number": "123456789",
            "issuer": "ssp",
            "issueDate": "1990-01-01"
        },
        "birthDate": "1990-01-01",
        "nationality": "BRA",
        "birthPlace": "São Paulo",
        "parentsName": {
            "father": "João da Silva",
            "mother": "Maria da Silva"
        },
        "phone": {
            "countryCode": "55",
            "areaCode": "11",
            "number": "965213244"
        },
        "alternativePhones": [
            {
                "countryCode": "55",
                "areaCode": "11",
                "number": "912341234"
            }
        ],
        "address": {
            "street": "Av. Brigadeiro Faria Lima",
            "streetNumber": "2927",
            "complement": "8º andar",
            "district": "Itaim",
            "zipcode": "01234-000",
            "city": "São Paulo",
            "state": "SP",
            "country": "BRA"
        }
    },
    "businessSegment": {
        "id": "5"
    },
    "site": "http://moip.com.br",
    "type": "MERCHANT"
}'

# Por enquanto não disponível no SDK Ruby, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK PHP, veja nosso exemplo em cURL.

No retorno, você irá receber o objeto do tipo Conta Moip com o identificador da conta id. Lembre-se que após este passo, ainda é necessário realizar a conexão da conta com o seu app para que você possa receber as credenciais da conta e com isso realizar pagamentos e outras ações em nome dela.

{
  "site": "http://moip.com.br",
  "type": "MERCHANT",
  "createdAt": "2015-01-28 15:56:08 UTC",
  "id": "MPA-11F00C9A1E03",
  "person": {

    [...]

  },
  "email": {
    "address": "email@dominio.com.br",
    "confirmed": false
  },
  "login": "email@dominio.com.br"
}

Veja o recurso completo com descrição de cada parâmetros da conta Moip em nossa referência API clicando aqui.

Conectando uma Conta Moip ao seu aplicativo

Depois de cadastrar o aplicativo na sua conta você terá acesso ao appId e poderá solicitar a conexão aos seus usuários que já possuem uma Conta Moip. A conexão é feita por meio do padrão OAuth 2.0 e segue o fluxo abaixo.

1 - Redirecionar o usuário

Redirecione o usuário para a página de permissões do Moip informando o identificador de seu aplicativo.

Exemplo: https://sandbox.moip.com.br/oauth/authorize?responseType=CODE&appId=APP1A2B3C4D5E6F&redirectUri=https://url.com.br/callback.php&scope=RECEIVE_FUNDS|REFUNDS|TRANSFER_FUNDS|RETRIEVE_FINANCIAL_INFO

URL de permissão

Assim que o usuário for redirecionado o Moip irá checar se ele está logado. Se ele estiver, serão exibidas as opções de aceitar ou recusar o vínculo com informações de seu aplicativo.

Página de permissão

Caso a permissão seja concedida o usuário será redirecionado para a sua url de redirecionamento com o code referente a confirmação do aceite do usuário.

Exemplo

https://www.meusite.com.br/&code=sdfdsgrwtrt66ert5ertret7srt556dsgse

Caso o usuário não esteja logado, será redirecionado para página de login, voltando para o fluxo descrito acima após a autenticação.

2 - Gerar token OAuth accessToken

Após a permissão concedida você receberá uma chave temporária code para efetivar o vinculo através de uma integração via API. Após a efetivação do vínculo você receberá o token OAuth do cliente em questão.

curl 
-X POST 
-H "Content-Type: application/x-www-form-urlencoded" 
-H "Authorization: Basic Tk0wRTdZR1hGUFhURVVZM0NUNjhJRlJBUEVWRjhNRkU6S0FSVlI0RFZDNVVHVEJLMUwzR01JTUI0TkdTUkZDVUVaSVFLUUJTRg==" 
-d 'client_id=APP-XO3OHU2SLYEB&client_secret=af7c0b2617fc4a4fac3a814ceddf8573&grant_type=authorization_code&code=sdfdsgrwtrt66ert5ertret7srt556dsgse&redirect_uri=https://www.meusite.com.br/' 
"https://connect.moip.com.br/oauth/token"

# Por enquanto não disponível no SDK Ruby, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK PHP, veja nosso exemplo em cURL.

retorno:

{
  "accessToken": "33031e2aad484051b89030487e59d133_v2",
  "access_token": "33031e2aad484051b89030487e59d133_v2",
  "expires_in": "2027-01-09",
  "refreshToken": "a60598142bb4436587a77baf0ea7183f_v2",
  "refresh_token": "a60598142bb4436587a77baf0ea7183f_v2",
  "scope": "RECEIVE_FUNDS,REFUND,MANAGE_ACCOUNT_INFO",
  "moipAccount": {
    "id": "MPA-ZT6YMSSIGU7O"
  }
}

Cadastrando dados bancários

Uma vez criada a Conta transparente, para realizar repasses para os seus usuários, é preciso cadastrar uma Conta Bancária. A Conta bancária deve ser de mesma titularidade da Conta Moip transparente do usuário.

curl -v https://sandbox.moip.com.br/v2/accounts/{id}/bankaccounts \
-H 'Content-Type: application/json'  \
-H 'Authorization: OAuth qguusgp05mxaa9adyy8kvo4nuq380z7' \
-d '{
    "bankNumber": "237",
    "agencyNumber": "12345",
    "agencyCheckNumber": "0",
    "accountNumber": "12345678",
    "accountCheckNumber": "7",
    "type": "CHECKING",
    "holder": {
        "taxDocument": {
            "type": "CPF",
            "number": "22222222222"
        },
        "fullname": "Teste Moip"
    }
}'

# Por enquanto não disponível no SDK Ruby, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK PHP, veja nosso exemplo em cURL.

No retorno você receberá as informações abaixo.

{
  "id": "BKA-NLEU6YZE04UH",
  "bankNumber": "237",
  "bankName": "BANCO BRADESCO S.A.",
  "agencyCheckNumber": "0",
  "agencyNumber": 12345,
  "accountCheckNumber": "7",
  "accountNumber": 12345678,
  "type": "CHECKING",
  "status": "NOT_VERIFIED",
  "holder": {
    "taxDocument": {
      "number": "742.520.863-61",
      "type": "CPF"
    },
    "fullname": "Runscope Random 9123"
  },
  "_links": {
    "self": {
      "href": "https://sandbox.moip.com.br/accounts/BKA-NLEU6YZE04UH/bankaccounts"
    }
  },
  "createdAt": "2015-11-16T20:20:26.295-02:00"
}

Solicitando transferência para contas bancárias

Com a conta criada e com uma conta bancária associada, caso o seu usuário possua saldo disponível para saque, é possível realizar uma transferência para a conta bancária. Para isso basta informar o valor e o identificador da conta bancária em questão.

curl -v https://sandbox.moip.com.br/v2/transfers \
-H 'Content-Type: application/json'  \
-H 'Authorization: OAuth qguusgp05mxaa9adyy8kvo4nuq380z7' \
-d '{
    "amount": 500,
    "transferInstrument": {
        "method": "BANK_ACCOUNT",
        "bankAccount": {
            "type": "CHECKING",
            "bankNumber": "001",
            "agencyNumber": "1111",
            "agencyCheckNumber": "2",
            "accountNumber": "9999",
            "accountCheckNumber": "8",
            "holder": {
                "fullname": "Nome do Portador",
                "taxDocument": {
                    "type": "CPF",
                    "number": "22222222222"
                }
            }
        }
    }
}'

# Por enquanto não disponível no SDK Ruby, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK JAVA, veja nosso exemplo em cURL.
# Por enquanto não disponível no SDK PHP, veja nosso exemplo em cURL.

No retorno você receberá as informações abaixo.

{
  "id": "TRA-EWDRK2USOTQK",
  "status": "REQUESTED",
  "amount": 500,
  "fee": 0,
  "transferInstrument": {
    "method": "BANK_ACCOUNT",
    "bankAccount": {
      "id": "BKA-3TYM4T4KOUT4",
      "agencyNumber": "1111",
      "holder": {
        "taxDocument": {
          "number": "255.328.259-12",
          "type": "CPF"
        },
        "fullname": "Jose Silva dos Santos"
      },
      "accountNumber": "9999",
      "accountCheckNumber": "8",
      "bankName": "BANCO DO BRASIL S.A.",
      "type": "CHECKING",
      "agencyCheckNumber": "2",
      "bankNumber": "001"
    }
  },
  "events": [...],
  "entries": [...],
  "_links": {
    "self": {
      "href": "https://sandbox.moip.com.br/v2/transfers/TRA-EWDRK2USOTQK"
    }
  },
  "createdAt": "2015-11-16T20:24:39.167-02",
  "updatedAt": "2015-11-16T20:24:39.167-02"
}

veja a relação detalhada dos parâmetros retornados em nossa referência API.

Para receber a notificação de conclusão ou falha da transferência é necessário ativar os Webhooks para a sua aplicação.

Webhooks

Os Webhooks foram criados para permitir que seu sistema seja atualizado em tempo real sobre os principais eventos que ocorrem no Moip. Um exemplo é a autorização de um pagamento após a análise anti-fraude. Neste caso, o seu sistema recebe (de forma síncrona) na resposta da criação de um pagamento o retorno com a informação de que o pagamento entrou em análise. No entanto, como a análise é feita em um segundo momento, você precisa atualizar o seu sistema com o resultado da análise. Para isso, você irá cadastrar URLs no Moip e enviaremos as notificações por meio de chamadas HTTP Post.

Você pode utilizar os webhooks para:

  • Receber o resultado da análise de transações de cartão de crédito
  • Receber notificações de pagamentos por boleto
  • Enviar e-mails para seus usuários com base nas alterações de status dos pedidos
  • Receber atualizações de assinaturas pagas ou vencidas
  • Atualizar sistemas contábeis de lançamentos liquidados na Conta Moip
  • Outros usos diversos

Entendendo os webhooks

Como descrito acima os Webhooks são as notificações automáticas que o Moip te envia sobre as alterações de status.

Vamos colocar em etapas para simplificar o entendimento.

1) Preparar a sua conta Moip

Primeiramente você deve preparar a sua conta para enviar os webhook, por padrão no Moip os webhooks são desabilitados em todas as contas, então você precisa habilitar o envio em sua conta cadastrando uma URL para receber essas notificações, veja abaixo em Configurando URLs de recebimento como fazer.

2) Tratar os webhooks

Depois de criada a configuração em sua conta Moip sua aplicação passará a receber os webhooks sempre que alguma coisa mudar em seus pedidos, pagamento e etc. Nesse caso sua aplicação deve saber interpretar essas notificação e trata-las de acordo com o seu modelo de negócio.

O conteúdo que enviamos nos webhooks é o mesmo que retornamos na API, apenas estará dentro de um nova parâmetro. Veja a seguir em Recebendo um webhook um exemplo dessa estrutura na prática.

Configurando URLs de recebimento

Você deve cadastrar suas URLs de Webhook através da API de configurações. É possível cadastrar múltiplas URLs e definir o tipo de webhook que deve ser enviado para cada uma delas. Isso faz com que você possa por exemplo receber notificações de pedidos pagos em um sistema (plataforma de e-commerce) e as notificações de lançamentos liquidados em um sistema diferente (sistema contábil). Caso você configure o mesmo webhook em mais de uma URL você receberá as notificações em todas as URLs.

No exemplo abaixo será enviado todos os webhooks possíveis do recurso Pedido e os webhooks de Pagamento autorizado e Pagamento cancelado para a URL que definimos.

{
  "events": [
    "ORDER.*",
    "PAYMENT.AUTHORIZED",
    "PAYMENT.CANCELLED"
  ],
  "target": "http://requestb.in/1dhjesw1",
  "media": "WEBHOOK"
}       

Como resposta você irá receber:

200 (OK)
Content-Type: application/json
{
  "events": [
    "ORDER.*",
    "PAYMENT.AUTHORIZED",
    "PAYMENT.CANCELLED"
  ],
  "target": "http://requestb.in/1dhjesw1",
  "media": "WEBHOOK",
  "token": "0081d6af29ec431b9a1f25a4ef7b6d9f",
  "id": "NPR-DV61EEGGUFCQ"
}

Também é possível consultar as configurações já criadas anteriormente por meio da API.

Recebendo um webhook

Veja abaixo o exemplo de webhook enviado pelo Moip. Nesse caso enviamos o recurso payment referente ao status PAYMENT.IN_ANALYSIS. Repare que o JSON desse recurso em sua representação completa (todos atributos) está encapsulado dentro da estrutura resource.payment.

{
  "event": "PAYMENT.IN_ANALYSIS",
  "resource": {
    "payment": {
      "id": "PAY-32LJ77AT4JNN",
      "status": "IN_ANALYSIS",
      "installmentCount": 1,
      "amount": {
        "total": 2000,
        "liquid": 1813,
        "refunds": 0,
        "fees": 187,
        "currency": "BRL"
      },
      "fundingInstrument": {
        "method": "CREDIT_CARD",
        "creditCard": {
          "id": "CRC-BXXOA5RLGQR8",
          "holder": {
            "taxDocument": {
              "number": "33333333333",
              "type": "CPF"
            },
            "birthdate": "30/12/1988",
            "fullname": "Jose Portador da Silva"
          },
          "brand": "MASTERCARD",
          "first6": "555566",
          "last4": "8884"
        }
      },
      "events": [
        {
          "createdAt": "2015-03-16T18:11:19-0300",
          "type": "PAYMENT.IN_ANALYSIS"
        },
        {
          "createdAt": "2015-03-16T18:11:16-0300",
          "type": "PAYMENT.CREATED"
        }
      ],
      "fees": [
        {
          "amount": 187,
          "type": "TRANSACTION"
        }
      ],
      "createdAt": "2015-03-16T18:11:16-0300",
      "updatedAt": "2015-03-16T18:11:19-0300",
      "_links": {
        "order": {
          "title": "ORD-SDZARE29MWVY",
          "href": "https://sandbox.moip.com.br/v2/orders/ORD-SDZARE29MWVY"
        },
        "self": {
          "href": "https://sandbox.moip.com.br/v2/payments/PAY-32LJ77AT4JNN"
        }
      }
    }
  }
}

Respondendo a um webhook

Para confirmar o recebimento de um webhook, o seu sistema deve retornar um código 2xx HTTP status. Informações retornadas no header ou no body serão ignoradas. Quaisquer respostas diferentes de 2xx serão interpretadas pelo Moip como não recebimento do webhook. Para estes casos, faremos retentativas automáticas conforme a régua apresentada abaixo.

Retentativa Descrição
____________
Ocorre 10 SEGUNDOS após o envio inicial
Ocorre 60 SEGUNDOS após a 1º retentativa
Ocorre 10 MINUTOS após a 2º retentativa
Ocorre 1 HORA após a 3º retentativa
Ocorre 24 HORAS após a 4º retentativa sendo a última retentativa automática

Caso você não tenha conseguido receber o webhook durante esse período, ainda é possível realizar o reenvio manual através de nossa API.

Melhores práticas para trabalhar com webhooks

O uso de retentativas e a possibilidade de reenvio manual de webhooks faz com que seja possível que você receba várias vezes a mesma notificação. Para proteger a sua aplicação, aconselhamos que você torne o processamento dos webhooks idempotent. Uma forma de fazer isso é logar o evento processado e garantir que outros eventos iguais sejam desconsiderados.

Para aumentar a segurança da sua aplicação e garantir que apenas o Moip pode enviar notificações para o seu sistema, você pode conferir o token enviado no header dos webhooks. Este token é o mesmo que é gerado no momento do cadastro da sua URL.

Venda protegida

O Venda Protegida oferece cobertura contra fraudes em pagamentos não autorizados pelo titular do cartão de crédito. Isto quer dizer que se a sua transação for elegível ao programa, as contestações geradas por motivo de fraude não serão debitadas da sua conta. Você passa a contar com uma tranquilidade adicional para realizar as suas vendas.

Caso queira obter maiores informações sobre as regras e limitaçõe do Venda Protegida, clique aqui.

Para que sua transação se enquadre no Venda Protegida é necessário que alguns campos sejam enviados obrigatoriamente na criação do Pedido e do Pagamento.

Conciliação Financeira

Visão geral de conciliação

Nesta seção mostramos como você pode sincronizar os dados financeiros e transacionais do Moip com ERPs, sistemas contábeis, sistemas de re-conciliação entre outros. De forma geral, os principais usos do produto são:

  • Permitir uma visão de fluxo de caixa previsto com base nos eventos da operação (vendas, reembolsos, chargebacks);
  • Permitir que o sistema do cliente realize a conciliação financeira com base nos eventos financeiros ocorridos no Moip.

Existem duas formas de realizar a integração com o sistema de conciliação.

  • Por meio do tratamento dos eventos que ocorrem em tempo real (conciliação online)
  • Por meio da leitura de arquivos diários de conciliação (conciliação por arquivos)

Fluxo transacional

Os principais recursos das APIs do Moip são os Pedidos e os Pagamentos. Em uma integração tradicional, para que uma cobrança seja realizada, um pedido com os dados do item vendido é criado e posteriormente um pagamento é associado a este pedido.

Caso o pagamento seja autorizado, o seu status é atualizado para AUTHORIZEDe consequentemente o status do Pedido alterado para PAID. Neste momento, como foi gerado um recebível, um novo recurso nomeado Lançamento é gerado e associado ao Pedido em questão. O Lançamento é criado com o status SCHEDULED que posteriormente é alterado para SETTLED quando o valor é liquidado na Conta Moip do usuário.

Todas as mudanças de estado dos recursos podem ser notificadadas para o seu sistema. Para mais informações veja a seção Webhooks. No corpo da notificação são enviados os detalhes do evento (tipo, data) e uma cópia completa do recurso que originou o evento.

A conciliação online é realizada com base na leitura dos eventos transacionais (que geram lançamentos) e eventos financeiros (liquidação de lançamentos). No caso de uso de arquivos, os conceitos permanecem os mesmos, porém os eventos são sumarizados em arquivos gerados diariamente contendo as informações do dia anterior.

Eventos que impactam a conciliação

Os eventos que geram lançamentos

  • PAYMENT.AUTHORIZED - Evento ocorre quando um Pagamento, seja qual for o meio, é autorizado;
  • PAYMENT.REFUNDED - Evento ocorre quando um Pagamento é reembolsado;
  • PAYMENT.REVERSED - Evento ocorre quando um Pagamento é revertido por meio de um chargeback;

Os eventos de liquidação de lançamentos

  • ENTRY.SETTLED - Evento ocorre quando um Lançamento é liquidado;

Conciliação online

Obtendo o fluxo de caixa previsto

Para criar a visão de fluxo de caixa previsto, você pode programar o seu sistema para a partir dos eventos da operação e inferir o fluxo de caixa futuro. Todos estes eventos estão disponíveis para serem consumidos pela sua aplicação (ver Webhooks).

Assim que o seu sistema recebe as notificações, você deve salvar os lançamentos (de crédito e débito) e deve atentar para as datas esperadas de liquidação scheduledFor.

Com essa data e os valores dos lançamentos, você já tem o seu fluxo de caixa esperado.

Segue abaixo um exemplo:

Data (scheduledFor) Credito/Debito Valor Taxa Liquido
01/10/2014 Credito R$ 100,00 R$ 2,00 R$ 98,00
01/10/2014 Credito R$ 100,00 R$ 3,00 R$ 97,00
01/10/2014 Debito R$ 98,00 R$ 0,00 R$ 98,00
Soma na data - - - R$ 293,00

Relatório 1 - Exemplo de créditos e débitos recebidos para uma data futura

Com base nas informações do exemplo acima, temos de fluxo de caixa esperado no dia 01/10/2014 o valor de R$ 293,00.

Obtendo o fluxo de caixa realizado

Uma vez que já temos o fluxo de caixa previsto, o próximo passo é a geração do relatório de fluxo de caixa realizado. Considere a data atual como o dia 01/10/2014. Nesse dia, o fluxo de caixa realizado deveria ser igual ao que havíamos previsto. Os créditos e débitos da data (veja Relatório 1) devem ser liquidados, ou seja, o status do recurso irá passar de SCHEDULED para SETTLED. Após esse momento, o valor estará disponível para ser enviado para a conta bancária.

O evento de liquidação, envia um novo Webhook de ENTRY.SETTLED para o seu sistema.

Assim que o seu sistema receber essa notificação, você já pode conferir na conta Moip o valor disponível para saque. Dessa forma, você consegue criar um outro relatório, dessa vez com as datas settledAt, para saber os valores liberados dia-a-dia e ter o fluxo de caixa realizado. Veja um exemplo abaixo:

Relatório 2 - Exemplo de créditos e débitos recebidos para uma data já passada (viraram lançamentos)

Data (settledAt) Credito/Debito Valor Taxa Liquido
01/10/2014 Credito R$ 100,00 R$ 2,00 R$ 98,00
01/10/2014 Credito R$ 100,00 R$ 3,00 R$ 97,00
01/10/2014 Debito R$ 98,00 R$ 0,00 R$ 98,00
Soma na data - - - R$ 293,00

Conciliação por arquivos

Obtendo o fluxo de caixa previsto

Para criar a visão de fluxo de caixa previsto, você deve recuperar todos os eventos que geraram lançamentos no dia anterior. Para isso você deve fazer o dowload do arquivo de vendas informando a data de referência no formato AAAAMMDD.

Obtendo o fluxo de caixa realizado

Para criar a visão de fluxo de caixa previsto, você deve recuperar todos os eventos que financeiros realizados no dia anterior. Para isso você deve fazer o download do arquivo financeiro informando a data de referência no formato AAAAMMDD.

Testando

Os métodos de teste e simuladores estão disponiveis apenas em ambiente de testes, ou seja apenas no Sandbox Moip.

Simulando diferentes status de pagamento

Os pagamentos criados no ambiente de testes, por padrão serão criados com o status IN_ANALYSIS e após alguns segundos o status será atualizado para AUTHORIZED.

Alem disso você ainda pode simular o pagamento deixando ele com o status IN_ANALYSIS ou CANCELLED, veja os status disponíveis para simulação com cartão de crédito.

  • AUTHORIZED - Pedido pago
  • IN_ANALYSIS - Pedido ainda aguardando confirmação de pagamento, ou análise de risco.
  • CANCELLED - Pedido não pago, cancelado pela operadora ou pela análise de risco Moip.

Exemplos

Com esses simuladores o status será definido na criação do pagamento ou seja, você deve criar o pedido previamente, caso não saiba como criar o pedido veja aqui.

AUTHORIZED - Pago

Para simular transações com status AUTHORIZED, ou seja, pedido Pago, basta informar qualquer nome para definir o portador do cartão. Por padrão, pedidos que não passam pela regra do simulador serão autorizados, veja exemplo abaixo.

{
    "installmentCount": 1,
    "fundingInstrument": {
        "method": "CREDIT_CARD",
        "creditCard": {
            "hash": "2n9vykIkGX5tegvdl+ow5ngPxP3ItAkp9tc1tzuMTeAuF457uN99CJIG386RD/iV5JPjwr9uCgr0XNYraMulcNJnys2b+A2pl7VcNmO83N5YBkViG+mo9SSCXMcBYBIcGotInur49DpKwylMbMFFWWYFsO/pq8e+zAe6g7dOLcKwkGlVrNL1PKepWxd5ldt44yPZhMeG82eiLxbnXrkAtcY19Phjlg7GIhCj3hjxSYi0Y6iUtLYmTpsVQIs93myH7LLU30gZ88xRMAYbmshi7fc8clfDkLbUPcCCDDYwe6ltFYX1J0YA/TT87Amj9filRlTzLuU9qvKHlXpq2Q/H",
            "holder": {
                "fullname": "Jose Santos",
                "birthdate": "1980-01-02",
                "taxDocument": {
                    "type": "CPF",
                    "number": "12345679891"
                },
                "phone": {
                    "countryCode": "55",
                    "areaCode": "11",
                    "number": "25112511"
                }
            }
        }
    }
}

Lembre-se: Nesse cenário o pagamento será criado como status IN_ANALYSIS e depois de alguns segundos mudará para AUTHORIZED.

Você também pode forçar a autorização de um pagamento que esteja em um status intermediário, ou apenas autorizar um pagamento do tipo Boleto bancário, veja em nossa referência API.

IN_ANALYSIS - Aguardando pagamento

Para deixar o status do pagamento em IN_ANALYSIS, ou seja, o pedido como Aguardando pagamento, basta informar ANALYZE como o nome do portador do cartão, veja exemplo abaixo.

{
    "installmentCount": 1,
    "fundingInstrument": {
        "method": "CREDIT_CARD",
        "creditCard": {
            "hash": "2n9vykIkGX5tegvdl+ow5ngPxP3ItAkp9tc1tzuMTeAuF457uN99CJIG386RD/iV5JPjwr9uCgr0XNYraMulcNJnys2b+A2pl7VcNmO83N5YBkViG+mo9SSCXMcBYBIcGotInur49DpKwylMbMFFWWYFsO/pq8e+zAe6g7dOLcKwkGlVrNL1PKepWxd5ldt44yPZhMeG82eiLxbnXrkAtcY19Phjlg7GIhCj3hjxSYi0Y6iUtLYmTpsVQIs93myH7LLU30gZ88xRMAYbmshi7fc8clfDkLbUPcCCDDYwe6ltFYX1J0YA/TT87Amj9filRlTzLuU9qvKHlXpq2Q/H",
            "holder": {
                "fullname": "ANALYZE",
                "birthdate": "1980-01-02",
                "taxDocument": {
                    "type": "CPF",
                    "number": "12345679891"
                },
                "phone": {
                    "countryCode": "55",
                    "areaCode": "11",
                    "number": "25112511"
                }
            }
        }
    }
}

CANCELLED - Não pago

Para deixar o status do pagamento em CANCELLED, ou seja, o pedido como Não pago, informe REJECT como o nome do portador do cartão, veja exemplo abaixo.

{
    "installmentCount": 1,
    "fundingInstrument": {
        "method": "CREDIT_CARD",
        "creditCard": {
            "hash": "2n9vykIkGX5tegvdl+ow5ngPxP3ItAkp9tc1tzuMTeAuF457uN99CJIG386RD/iV5JPjwr9uCgr0XNYraMulcNJnys2b+A2pl7VcNmO83N5YBkViG+mo9SSCXMcBYBIcGotInur49DpKwylMbMFFWWYFsO/pq8e+zAe6g7dOLcKwkGlVrNL1PKepWxd5ldt44yPZhMeG82eiLxbnXrkAtcY19Phjlg7GIhCj3hjxSYi0Y6iUtLYmTpsVQIs93myH7LLU30gZ88xRMAYbmshi7fc8clfDkLbUPcCCDDYwe6ltFYX1J0YA/TT87Amj9filRlTzLuU9qvKHlXpq2Q/H",
            "holder": {
                "fullname": "REJECT",
                "birthdate": "1980-01-02",
                "taxDocument": {
                    "type": "CPF",
                    "number": "12345679891"
                },
                "phone": {
                    "countryCode": "55",
                    "areaCode": "11",
                    "number": "25112511"
                }
            }
        }
    }
}

O REJECT simula um cancelamento feito pelo Moip, para simular um cancelamento feito pela adquirente, basta informar CANCEL como o nome do pagador.

Lembrando que esse processo ocorre apenas no ambiente de testes e tem como intuíto facilitar a simulação de diferentes status de suas transações. Posteriormente adicionaremos cenários mais complexos para simular diferentes fluxos de uma transação.

Números de cartão para teste

Bandeira Número Vencimento CVC
Mastercard 5555666677778884 05/2018 123
Visa 4012001037141112 05/2018 123
Amex 376449047333005 05/2018 1234
Elo 6362970000457013 05/2018 123
Diners 36490102462661 05/2018 123
Hiper 6370950000000005 05/2018 123
Hipercard 6062825624254001 05/2018 123

Testando os webhooks

Para receber os webhooks do Moip você deve ter em seu servidor uma url pronta para receber e tratar as notificações do Moip. Caso você queira testar o recebimento das informações antes de fazer a implementação você pode utilizar ferramentas como o requestbin para receber seus webhooks.

Testando transferências bancárias

Para simular o retorno de uma transferência bancária você deve:

  • enviar 9000 no campo bankAccount.agencyNumber para simular o status de falha
  • enviar qualquer outro número no campo bankAccount.agencyNumber para simular o status de sucesso

Referência

Moip.js

O Moip.js é uma biblioteca client-side que facilita a criptografia dos dados de cartão de crédito de seus clientes. Além disso, você pode utilizar as validações que facilitam a identificação de bandeiras, validação de data de vencimento, validação de código de segurança e validação para certificar que o número do cartão ínserido é um número válido.

Iniciando o Moip.js

Para utilizar nossa biblioteca, importe o Moip.js:

<script type="text/javascript" src="//assets.moip.com.br/v2/moip.min.js"></script>

Chave Pública

Você deve definir a sua chave pública em seu app para que seja possível fazer a criptografia. Caso ainda não possua sua chave pública clique aqui.

Com o Moip.js em sua página, você deve inserir a sua chave pública em um campo com o id correspondente a sua função que fará a comunicação com o Moip.js

<textarea id="public_key" style="display:none;">
  -----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsXkulsKdAQLMH/zjzTLf
0lrbgulfb6ZShEtRpmDnyX93EQqPdez7LyptvQBeTC+0pN57rNcWen9ApdsIMsNr
YHjNQf/kI4Ka7Xnlx0U/v7bW1D8teDoD5glBTXLjU8hRi7qlOpupiPx4ldSnK9Jj
tYApWuZMiCpWh/YRAlNW/N+ffm7ulq6H2atmgd+OFB2SghpbRJkqJiLaNJW8UkaR
oXLHkF5WJD/RPrCxsZztYJQThxLX5gBgZ12YG5+7G26Ad/mWkPqF0GLSkd1gcnbP
vF9Nw3ckKaIvh4Q4Vp3XI1hLvX41lg9CBxPPHkiJwM1M1coF9xsMP7kpJ2eujMBd
mwIDAQAB
-----END PUBLIC KEY-----</textarea>

Criptografando os dados do cartão

Você também deve incluir o script que fará a criptografia em sua página:

  <script type="text/javascript">
    $(document).ready(function() {
        $("#encrypt").click(function() {
          var cc = new Moip.CreditCard({
            number  : $("#number").val(),
            cvc     : $("#cvc").val(),
            expMonth: $("#month").val(),
            expYear : $("#year").val(),
            pubKey  : $("#public_key").val()
          });
          console.log(cc);
          if( cc.isValid()){
            $("#encrypted_value").val(cc.hash());
          }
          else{
            $("#encrypted_value").val('');
            alert('Invalid credit card. Verify parameters: number, cvc, expiration Month, expiration Year');
          }
        });
    });
  </script>

Com os scripts do Moip.js setados em sua página, você deve criar campos em seu checkout referênciando a biblioteca, o Moip.js irá fazer a criptografia dos dados do pagamento e transformá-los em um hash, que você utilizará para efetuar um pagamento.

<input type="text" placeholder="Credit card number" id="number"/>
<input type="text" placeholder="CVC" id="cvc"/>
<input type="text" placeholder="Month" id="month"/>
<input type="text" placeholder="Year" id="year" />

Validações

Com o Moip.js você pode efetuar diversas validações em seu checkout.

Validando apenas o número de cartão

Moip.Validator.isValid("4111111111111111");    //return true
Moip.Validator.isValid("4111 1111-1111.1111"); //return true
Moip.Validator.isValid("1919191919191919");    //return false
Moip.Validator.isValid("41111");               //return false

Possíveis retornos:

true ou false

Validando cartão com código de segurança

Moip.Validator.isSecurityCodeValid("5105105105105100", "123");    //return true
Moip.Validator.isSecurityCodeValid("5105105105105100", "12");     //return false

Possíveis retornos:

true ou false

Identificando a bandeira de um cartão

Moip.Validator.cardType("5105105105105100");    //return [Object]MASTERCARD
Moip.Validator.cardType("4111111111111111");    //return [Object]VISA
Moip.Validator.cardType("341111111111111");     //return [Object]AMEX
moip.Validator.cardType("30569309025904");      //return [Object]DINERS
Moip.Validator.cardType("3841001111222233334"); //return [Object]HIPERCARD
Moip.Valditor.cardType("4514160123456789");    //return [Object]ELO
Moip.Valditor.cardType("6370950000000005");    //return [Object]HIPER
Moip.Validator.cardType("9191919191919191");    //return [Object]null

Possíveis retornos: Object: [brand]

MASTERCARD VISA AMEX DINERS HIPERCARD ELO HIPER

Verificado se a data de expiração do cartão é valida

Moip.Validator.isExpiryDateValid("10", "2020");    //return true
Moip.Validator.isExpiryDateValid("10", "2000");    //return false

//Usando objeto Date
var now = new Date();
var isExpiryDateValid = Moip.Validator.isExpiryDateValid(now.getMonth()+1+"", now.getYear()+1900+""); // return true

Possíveis retornos:

true ou false

Assinaturas.js

O moip-assinaturas.min.js é uma biblioteca JavaScript feita para facilitar a integração do Moip Assinaturas com o seu site, permitindo o desenvolvimento do seu próprio fluxo de contratação sem que seu cliente precise sair do seu ambiente, assim como funciona o Checkout Transparente do Moip. Além de possuir uma estrutura de validações pré-definidas, utilizando essa biblioteca você também reduz o seu escopo para o PCI, uma vez que os dados de cartão de crédito vão direto do navegador do seu cliente para o Moip.

Configurando (Obrigatório)

O Moip Assinaturas dispõe de dois ambientes: SANDBOX e PRODUÇÃO, permitindo flexibilidade entre testes de homologação e ambiente real. A biblioteca possui dependência do JQuery, portanto, é importande adicioná-la antes de realizar a importação da biblioteca JS do Moip Assianturas.

Sandbox:
<script type="text/javascript" src="https://s3.amazonaws.com/assets-sandbox.moip.com.br/assinaturas/moip-assinaturas.min.js"></script>

Produção:
<script type="text/javascript" src="https://s3.amazonaws.com/assets.moip.com.br/assinaturas/moip-assinaturas.min.js"></script>

Identificação

Todos os serviços do Moip Assinaturas são autenticados e deve ser informada na hora de instânciar um objeto do tipo MoipAssinaturas(). Sua chave pública é seu Token Moip.

Exemplo:


    var moip = new MoipAssinaturas("SEU_TOKEN");

Como conseguir o Token e Key

O Moip assinaturas utiliza os mesmo token e key disponíveis em sua Conta Moip. Assim, não só estamos unificando as chaves, como estamos mantendo integradas as contas do Moip e do Moip Assinaturas.

Para obter seu token e key, siga os procedimentos abaixo:

  • Acesse o moip.com.br;
  • Clique na opção “Ferramentas” no Menu;
  • Selecione a opção “API Moip” e depois “Chaves de Acesso”;
  • Seu TOKEN será exibido na página seguinte, a KEY estará oculta, mas basta clicar no link e ela será exibida na mesma página.

Criar uma assinatura

Pré-requisitos

  • Criação prévia de um plano.
  • Importação da biblioteca moip-assinaturas.min.js.
  • Possuir TOKEN de identificação.

Criando um cliente

new Customer()

A criação de uma assinatura prevê a existência de um cliente, para criá-lo basta instânciar o objeto new Customer(). O cliente possui as informações pessoais do assinante (nome, e-mail, código do cliente, cpf, data de nascimento, etc), o endereço new Address() (rua, numero, bairro, etc) e o os dados de cobrança new BillingInfo()(cartão de crédito).

Criando a assinatura

new MoipAssinaturas()

O primeiro passo para a utilização do moip-assinaturas.min.js é instanciar o objeto new MoipAssinaturas('SEU_TOKEN'), essa classe JavaScript é responsável por realizar a integração com o Moip Assinaturas. Em seu construtor, ela recebe apenas o seu token de autorização.

O metódo MoipAssinaturas.subscribe é responsavel por criar uma nova assinatura com um novo cliente. Ele recebe como parâmetro um objeto new Subscription() contendo como parâmetros o código da assinatura, o novo cliente (criado atráves do objeto Customer) e o código do plano.

Abaixo há um exemplo de um JavaScript para gerar uma assinatura.

Exemplo:


var moip = new MoipAssinaturas("SEU_TOKEN");
var customer = build_customer();
var plan_code = $("#plan_code").val();

moip.subscribe(
    new Subscription()
        .with_code(new Date().getTime())
        .with_new_customer(customer)
        .with_plan_code(plan_code)
        .with_coupon(coupon_code)
).callback(function(response){
    if (response.has_errors()) {
        for (i = 0; i < response.errors.length; i++) {
          var erro = response.errors[i].description;
          $("#erros").append(erro);
        }
        return;
    }
    alert("Assinatura criada com sucesso")
});

var build_customer = function() {
  var customer_params = {
      fullname: $("#fullname").val(),
      email: $("#email").val(),
      code: new Date().getTime(),
      cpf : $("#cpf").val(),
      birthdate_day : $("#birthdate_day").val(),
      birthdate_month: $("#birthdate_month").val(),
      birthdate_year: $("#birthdate_year").val(),
      phone_area_code: $("#ddd").val(),
      phone_number: $("#phone").val(),
      billing_info: build_billing_info(),
      address: build_address()
  }
  return new Customer(customer_params);
};

var build_billing_info = function() {
  var billing_info_params = {
      fullname : $("#holder_name").val(), 
      expiration_month: $("#expiration_month").val(),
      expiration_year: $("#expiration_year").val(),
      credit_card_number: $("#credit_card").val()
  };
  return new BillingInfo(billing_info_params);
};

var build_address = function() {
  var address_params = {
      street: $("#rua").val(),
      number: $("#numero").val(),
      complement: $("#complemento").val(),
      district: $("#bairro").val(),
      zipcode: $("#cep").val(),
      city: $("#cidade").val(),
      state: $("#estado").val(),
      country: "BRA"
  };
  return new Address(address_params);
};

Criar um cliente com dados de cartão

Para criar um cliente com dados de cartão sem relacioná-lo a uma assinatura, o processo é semelhante. Você cria um new Customer() e instância o objeto new MoipAssinaturas('SEU_TOKEN'), porém, você deverá chamar o método MoipAssinaturas.create_customer(). Nesse caso, apenas o cliente será criado e não estará associado a nenhuma assiantura.

Exemplo:


var token = "MEU_TOKEN";
var customer = new Customer(); // Especifique todos os atributos de um Customer
moip = new MoipAssinaturas(token);
moip.create_customer(customer)
.callback(function(response){
  if (response.has_errors()) {
    for (i = 0; i < response.errors.length; i++) {
      var erro = response.errors[i].description;
      $("#erros").append(erro);
    }
    return;
  } 
  alert("Cliente criado com sucesso");
});

Atualizar dados de cartão

Para atualizar os dados de cartão de um cliente é necessário construir um objeto Customer() onde obrigatoriamente deve haver o código do cliente no qual você deseja atualizar os dados de cartão e a nova BillingInfo() com os novos dados de cobrança.

Exemplo:


var token = "MEU_TOKEN";
var moip = new MoipAssinaturas(token);

var customer = new Customer();
customer.code = "cliente01"; // Código identificador do seu cliente
customer.billing_info = new BillingInfo(); // Especifique um novo cartão para fazer a cobrança

moip.update_credit_card(customer).callback(function(response){
    if (response.has_errors()) {
        for (i = 0; i < response.errors.length; i++) {
            var erro = response.errors[i].description;
            $("#erros").append(erro);
        }
    return;
});;

Callback

Personalizando o retorno do Moip Assinaturas.

Passando um método de callback

Assim que o Moip Assinaturas concluir a sua requisição o metódo de callback é executado. Isto é útil para você dar sequência ao seu checkout ou mesmo exibir mensagens de erros para o cliente ao preencher o formulário de pagamento.

Para que possamos chamar seu metódo de callback, é necessário que você passe o bloco de função para o metódo callback.


var moip = new MoipAssinaturas("SEU_TOKEN");
moip.callback(function(response){
  // aqui você adiciona os seus comportamentos esperados
});

Processando a resposta

O Moip Assinaturas irá chamar seu callback passando como parâmetro um objeto Response(). Ele contém uma lista de possíveis erros da integração ou de informações preenchidas pelo seu cliente no checkout. O Response() também possui uma lista de alertas que auxiliam você na sua integração.


{
    "code": "ass_homolog_72",
    "amount": "100",
    "next_invoice_date": {
        "day": "05",
        "month": "01",
        "year": "2013"
    },
    "status": "ACTIVE",
    "plan": {
        "name": "Plano de homologação",
        "code": "homolog1"
    },
    "customer": {
        "email": "fulano@homolog.com",
        "code": "homolog2",
        "fullname": "Fulano Homologador"
    },
    "invoice": {
        "id": 134,
        "moip_id": "14000000",
        "amount": 110,
        "status": {
            "description": "Em análise",
            "code": 2
        }
    },
    "message": "Assinatura criada com Sucesso",
    "errors": [],
    "alerts": [
        {
            "code": "MA90",
            "description": "O nome do portador do cartão deve ter no máximo 45 caracteres. Os demais caracteres serão ignorados"
        }
    ]
}

Para verificar se há erros ou alertas na resposta do Moip Assinaturas, basta chamar o metódos has_errors() ou has_alerts().

Exemplo:


var moip = new MoipAssinaturas("SEU_TOKEN");
moip.callback(function(response){
  alert(response.has_errors());
  alert(response.has_alerts());
});

Visão geral Mobile

Os SDKs Moip permitem cobrar pagamentos dentro da sua solução mobile de uma maneira mais simples e com uma melhor experiência de uso dentro do seu negócio.

Vantagens

  • Criar o pedido na sua plataforma de ecommerce de uma maneira mais simples e rápida;
  • Receber pagamentos de forma ágil e com a melhor experiência mobile;
  • Receber pagamentos com apenas 1 toque (one click payment);
  • Oferecimento de componentes de pagamento, que facilitam a captura dos dados de cartão de credito, a identificação da bandeira do cartão e a formatação do número do cartão, dentre outros;
  • Mais segurança por meio de criptografia forte, com chave pública RSA;
  • Tratativas de erro de conexão e problemas com a rede;
  • Facilidade de integração.

Integração com o Moip

Antes de iniciar o nosso passo-a-passo para integrar o SDK Moip no seu App, é necessario integrar o seu negocio com a API do Moip. O SDK será responsável apenas pela criptografia dos dados do cartão de crédito diretamente no seu App. Contudo, ainda será necessário integrar a sua aplicação na API do Moip, pois o pedido e o pagamento é criado sempre de forma server-side pela sua aplicação.

Para integrar a sua aplicação na API do Moip, escolha a solução mais adequada ao seu negocio e veja como integrar os sistemas:

Mobile SDK iOS

O Moip traz em seu DNA o relacionamento com desenvolvedores, levando isso como base decidimos por disponibilizar nossos SDKs para download como código aberto através do GitHub, faça o download do SDK para iOS sample pelo link moip/ios-sdk-sample.

Veja abaixo o tutorial passo-a-passo como integrar com o SDK para iOS.

Iniciando no iOS

O primeiro passo é importar o SDK em sua aplicação.

#import <MoipSDK/MoipSDK.h>

Chave Pública

Você deve definir a sua chave pública em seu app para que seja possível fazer a criptografia. Caso ainda não possua sua chave pública clique aqui.

NSString *myPublicKey = @"-----BEGIN PUBLIC KEY-----\n"+
        "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoBttaXwRoI1Fbcond5mS\n"+
        "7QOb7X2lykY5hvvDeLJelvFhpeLnS4YDwkrnziM3W00UNH1yiSDU+3JhfHu5G387\n"+
        "O6uN9rIHXvL+TRzkVfa5iIjG+ap2N0/toPzy5ekpgxBicjtyPHEgoU6dRzdszEF4\n"+
        "ItimGk5ACx/lMOvctncS5j3uWBaTPwyn0hshmtDwClf6dEZgQvm/dNaIkxHKV+9j\n"+
        "Mn3ZfK/liT8A3xwaVvRzzuxf09xJTXrAd9v5VQbeWGxwFcW05oJulSFjmJA9Hcmb\n"+
        "DYHJT+sG2mlZDEruCGAzCVubJwGY1aRlcs9AQc1jIm/l8JwH7le2kpk3QoX+gz0w\n"+
        "WwIDAQAB\n"+
        "-----END PUBLIC KEY-----";
[MoipSDK importPublicKey:myPublicKey];

Criando o objeto Credit Card

MPKCreditCard *creditCard = [MPKCreditCard new];
creditCard.number = @"4111111111111111";
creditCard.cvc = @"999";
creditCard.expirationMonth = @"07";
creditCard.expirationYear = @"15";

Criptografando os dados com base no seu MPKCreditCard

NSString * cryptData = [MoipSDK encryptCreditCard:creditCard];

Após fazer a criptografia do cartão de crédito você receberá uma string que será correspondente ao hash do cartão de crédito do seu cliente no Moip, com esse Hash em mãos você poderá trafegá-lo em seu servidor e enviar para o Moip ao criar o seu Pagamento ou Multipagamento(Marketplaces).

Validações

Usando o MoipSDK, você pode realizar varias verificações para checar os dados do cartão de credito.

Número do cartão

MPKCreditCard *creditCard = [MPKCreditCard new];
creditCard.number = @"4111111111111111";

BOOL isValidCreditCard = creditCard.isNumberValid;

Código de segurança

MPKCreditCard *creditCard = [MPKCreditCard new];
creditCard.cvc = @"123";

BOOL isValid = creditCard.isSecurityCodeValid;

Código de segurança

MPKCreditCard *creditCard = [MPKCreditCard new];
creditCard.expirationMonth = @"06";
creditCard.expirationYear = @"2018";

BOOL isValid = creditCard.isExpiryDateValid;

Mobile SDK Android

Nosso SDK Android é utilizado primariamente para a criptografia dos dados do cartão do seu cliente dentro do seu aplicativo, sendo assim toda a comunicação de criação de pedidos e pagamentos deve ser feita em seu servidor. Você pode utilizar nosso SDK tanto no seu Ecommerce quanto em seu Marketplace.

Veja abaixo o tutorial passo-a-passo como integrar o Moip em seu aplicativo usando o SDK para Android.

Iniciando no Android

Para utilizar o SDK do Moip, antes é preciso adicionar as suas dependências. Há um zip com as depêndencias em nosso repositório no Github. Caso utilize o gradle adicione apenas as seguintes linhas.

  compile 'com.madgag.spongycastle:pkix:1.51.0.0'

Chave Pública:

Você deve definir a sua chave pública em seu app para que seja possível fazer a criptografia. Caso ainda não possua sua chave pública clique aqui.

      final String PUBLIC_KEY = "-----BEGIN PUBLIC KEY-----\n"+
        "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoBttaXwRoI1Fbcond5mS\n"+
        "7QOb7X2lykY5hvvDeLJelvFhpeLnS4YDwkrnziM3W00UNH1yiSDU+3JhfHu5G387\n"+
        "O6uN9rIHXvL+TRzkVfa5iIjG+ap2N0/toPzy5ekpgxBicjtyPHEgoU6dRzdszEF4\n"+
        "ItimGk5ACx/lMOvctncS5j3uWBaTPwyn0hshmtDwClf6dEZgQvm/dNaIkxHKV+9j\n"+
        "Mn3ZfK/liT8A3xwaVvRzzuxf09xJTXrAd9v5VQbeWGxwFcW05oJulSFjmJA9Hcmb\n"+
        "DYHJT+sG2mlZDEruCGAzCVubJwGY1aRlcs9AQc1jIm/l8JwH7le2kpk3QoX+gz0w\n"+
        "WwIDAQAB\n"+
        "-----END PUBLIC KEY-----";

Criando o objeto CreditCard

    CreditCard creditCard = new CreditCard();
        creditCard.setCvc("123");
        creditCard.setNumber("4340948565343648");
        creditCard.setExpirationMonth("12");
        creditCard.setExpirationYear("2030");
        creditCard.setPublicKey(PUBLIC_KEY);

Criptografando o Cartão

   try{
        creditCard.encrypt();
    }catch(MoipEncryptionException mee){

    }

Após fazer a criptografia do cartão de crédito você receberá uma string que será correspondente ao hash do cartão de crédito do seu cliente no Moip, com esse Hash em mãos você poderá trafegá-lo em seu servidor e enviar para o Moip ao criar o seu Pagamento ou Multipagamento(Marketplaces).

Validações

O SDK Moip contém diversas validações para checar os dados de cartão.

    MoipValidator.isValidMonth(MONTH);
    MoipValidator.isValidYear(YEAR);
    MoipValidator.isValidCreditCard(CREDIT_CARD_NUMBER);
    MoipValidator.isValidCVC(CVC_NUMBER);

O SDK Moip também contém métodos para verificarem a bandeira do cartão.

    CreditCardBrand brand = MoipValidator.verifyBrand(CREDIT_CARD_NUMBER);

Também é possivel verificar a bandeira do cartão com apenas os 4 primeiros dígitos.

 CreditCardBrand brand = MoipValidator.quicklyBrand(CREDIT_CARD_NUMBER);

Referência completa de APIs

Consulte nossa referência API completa acessando acessando http://dev.moip.com.br/referencia-api/.

Topo