Cliente em Ruby para integração server-side com APIs Moip v2
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples
lib
spec
vcr_cassettes
.gitignore
.rspec
.rubocop.yml
.ruby-gemset
.ruby-version
.travis.yml
CONTRIBUTING.md
Gemfile
Gemfile.lock
Guardfile
LICENSE.txt
PULL_REQUEST_TEMPLATE.md
README.md
Rakefile
changelog.md
moip2.gemspec

README.md

Moip v2 Ruby SDK

O jeito mais simples e rápido de integrar o Moip a sua aplicação Ruby

Build Status Code Climate Test Coverage

Índice

Instalação

Adicione a seguinte linha no seu Gemfile:

gem "moip2"

Configurando a autenticação

Por BasicAuth

auth = Moip2::Auth::Basic.new("TOKEN", "SECRET")

Por OAuth

auth = Moip2::Auth::OAuth.new("TOKEN_OAUTH")

Configurando o ambiente

Após definir o tipo de autenticação, é necessário gerar o client, informando em qual ambiente você quer executar suas ações:

client = Moip2::Client.new(:sandbox/:production, auth)

Após isso, é necessário instanciar um ponto de acesso a partir do qual você utilizará as funções da API:

api = Moip2::Api.new(client)

Você pode customizar o client passando um hash de opções na inicialização. Essas opções serão passadas adiante para o client HTTParty, que aceita as opções descritas na documentação.

Por exemplo, para alterar o timeout das requisições para 5 segundos:

client = Moip2::Client.new(:sandbox/:production, auth, timeout: 5)

Clientes

Criação

customer = api.customer.create({
  ownId: "meu_id_de_cliente",
  fullname: "Jose Silva",
  email: "josedasilva@email.com",
  phone: {
    #...
  },
  birthDate: "1988-12-30",
  taxDocument: {
    #...
  },
  shippingAddress: {
    #...
  },
  fundingInstrument: {
    # Campo opcional. Consulte a documentação da API.
  }
})

Consulta

customer = api.customer.show("CUS-V41BR451L")

Adicionar cartão de crédito

credit_card = api.customer.add_credit_card("CUSTOMER-ID",
    {
      method: "CREDIT_CARD",
      creditCard: {
        expirationMonth: "05",
        expirationYear: "22",
        number: "5555666677778884",
        cvc: "123",
        holder: {
          fullname: "Jose Portador da Silva",
          birthdate: "1988-12-30",
          taxDocument: {
            type: "CPF",
            number: "33333333333",
          },
          phone: {
            countryCode: "55",
            areaCode: "11",
            number: "66778899",
          },
        },
      },
    }
)

Deletar cartão de crédito

Retorna uma Exception do tipo NotFoundError caso não encontre o cartão de crédito para deletar.

api.customer.delete_credit_card!("CREDIT-CARD-ID")

Pedidos

Criação

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",
  }
})

Consulta

Pedido Específico

order = api.order.show("ORD-V41BR451L")

Todos os Pedidos

Sem Filtro
orders = api.order.find_all()
Com Filtros
orders = api.order.find_all(filters: { status: { in: ["PAID", "WAITING"] }, amount: { bt: [500, 1000] } })
Com Paginação
orders = api.order.find_all(limit: 10, offset: 50)
Consulta Valor Específico
orders = api.order.find_all(q: "your_value")

Pagamentos

Criação

Cartão de Crédito

Com Hash
api.payment.create(order.id,
    {
        installment_count: 1,
        funding_instrument: {
            method: "CREDIT_CARD",
            credit_card: {
                hash: "valor do cartão criptografado vindo do JS",
                holder: {
                    fullname: "Jose Portador da Silva",
                    birthdate: "1988-10-10",
                    tax_document: {
                        type: "CPF",
                        number: "22222222222"
                    }
                }
            }
        }
    }
)
Com Dados do Cartão

Esses método requer certificação PCI. Consulte a documentação.

api.payment.create(order.id,
    {
        installment_count: 1,
        funding_instrument: {
            method: "CREDIT_CARD",
            credit_card: {
                expiration_month: 04,
                expiration_year: 18,
                number: "4002892240028922",
                cvc: "123",
                holder: {
                    # ...
                }
            }
        }
    }
)

Com Boleto

api.payment.create(order.id,
    {
      # ...
        funding_instrument: {
            method: "BOLETO",
            boleto: {
                expiration_date: "2017-09-30",
                instruction_lines: {
                    first: "Primeira linha do boleto",
                    second: "Segunda linha do boleto",
                    third: "Terceira linha do boleto"
                  },
                logo_uri: "https://sualoja.com.br/logo.jpg"
            }
        }
    }
)

Consulta

pagamento = api.payment.show("PAY-CRUP19YU2VE1")

Capturar pagamento pré-autorizado

api.payment.capture("PAY-KT5OSI01X8QU")

Cancelar pagamento pré-autorizado

api.payment.void("PAY-IXNGCU456GG4")

Reembolsos

Criação

Valor Total

reembolso = api.refund.create("ORD-V41BR451L")

Valor Parcial

reembolso = api.refund.create("ORD-V41BR451L", amount: 2000)

Consulta

reembolso = api.refund.show("REF-V41BR451L")

Multipedidos

Criação

multi = api.multi_order.create(
  {
    ownId: "meu_multiorder_id",
    orders: [
      {
        # Objeto Order 1
      },
      {
        # Objeto Order 2
      }
    ]
  }
)

Consulta

multi = api.multi_order.show("MOR-V41BR451L")

Nota

  1. Essa função depende de permissões das contas associadas ao recebimento. Consulte a documentação.
  2. Para reembolsos de multipedidos, é necessario reembolsar os pedidos individualmente. Consulte a documentação.

Multipagamentos

Criação

multi_pag = api.multi_payment.create("MOR-V41BR451L",
  {
    installmentCount: 1,
    fundingInstrument: {
      # ...
    }
  }
)

Consulta

multi_pag = api.multi_payment.show("MPY-V41BR451L")

Capturar multipagamento pré-autorizado

multi = api.multi_payment.capture("MPY-V41BR451L")

Cancelar multipagamento pré-autorizado

multi = api.multi_payment.void("MPY-V41BR451L")

Conta Moip

Criação

account = api.accounts.create(
  {
    email: {
      address: "dev.moip@labs.moip.com.br",
    },
    person: {
      name: "Joaquim José",
      lastName: "Silva Silva",
      taxDocument: {
        type: "CPF",
        number: "572.619.050-54",
      },
      identityDocument: {
        type: "RG",
        number: "35.868.057-8",
        issuer: "SSP",
        issueDate: "2000-12-12",
      },
      birthDate: "1990-01-01",
      phone: {
        countryCode: "55",
        areaCode: "11",
        number: "965213244",
      },
      address: {
        street: "Av. Brigadeiro Faria Lima",
        streetNumber: "2927",
        district: "Itaim",
        zipCode: "01234-000",
        city: "S\u00E3o Paulo",
        state: "SP",
        country: "BRA",
      },
    },
    type: "MERCHANT"
  }
)

Consulta

account = api.accounts.show("MPA-12312312312")

Verifica se usuário já possui Conta Moip

api.accounts.exists?({tax_document: "123.456.789.10"})

ou

api.accounts.exists?({email: "dev.moip@labs.moip.com.br"})

Conta bancária

Criação

bank_account = api.bank_accounts.create("MPA-14C9EE706C55",
      bank_number: "237",
      agency_number: "12345",
      agency_check_number: "0",
      account_number: "12345678",
      account_check_number: "7",
      type: "CHECKING",
      holder: {
        tax_document: {
          type: "CPF",
          number: "164.664.426-32",
        },
        fullname: "Sales Machine da Silva",
      })

Consulta

api.bank_accounts.show("BKA-DWTSK16UQI9N")

Listagem

api.bank_accounts.find_all("MPA-14C9EE706C55")

Atualizar conta bancaria

api.bank_accounts.update("BKA-DWTSK16UQI9N",
      bank_number: "237",
      agency_number: "12345",
      agency_check_number: "0",
      account_number: "87654323",
      account_check_number: "7",
      type: "CHECKING",
      holder: {
        tax_document: {
          type: "CPF",
          number: "164.664.426-32",
        },
        fullname: "Sales Machine da Silva",
      })

Deletar conta bancaria

Retorna uma Exception do tipo NotFoundError caso não encontre a conta bancária para deletar

  api.bank_accounts.delete("BKA-DWTSK16UQI9N")

Transferência

Criação

Conta Bancária

transfer = api.transfer.create(
  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",
        },
      },
    },
  },
)

Conta Moip

transfer = api.transfer.create(
  amount: 500,
  transferInstrument: {
    method: "MOIP_ACCOUNT",
    moipAccount: {
      id: "MPA-B0D880F21EF1",
    },
  },
)

Consulta

transfer = api.transfer.show("TRA-28HRLYNLMUFH")

Listagem

transfers = api.transfer.find_all()

Reversão

transfer = api.transfer.reverse("TRA-B0W5FD5FCADG")

Custódia

Pagamento com custódia

payment = api.payment.create(order.id,
    {
        installment_count: 1,
        escrow: {
          description: 'Custódia de pagamento'
        },
        funding_instrument: {
            method: "CREDIT_CARD",
            credit_card: {
                expiration_month: 04,
                expiration_year: 18,
                number: "4002892240028922",
                cvc: "123",
                holder: {
                    # ...
                }
            }
        }
    }
)

Liberação de custódia

escrow = api.payment.release("ECW-JO3U4WIXD0CK")

OAuth (Moip Connect)

Solicitar permissões de acesso ao usuário

api.connect.authorize_url("APP-ID","http://localhost/moip/callback","RECEIVE_FUNDS,REFUND")

Gerar token OAuth

api.connect.authorize(
  client_id: "APP-YRYCCJ5P603B",
  client_secret: "363cdf8ab70a4c5aa08017564c08efbe",
  code: "4efde1f89d9acc3b12124ccfded146518465e423",
  redirect_uri: "http://localhost/moip/callback",
  grant_type: "authorization_code"
)

Atualizar token OAuth

api.connect.authorize(
  refresh_token: "1d5dc51e71674683b4ed79cd7a988fa1_v2",
  grant_type: "refresh_token"
)

Obter Chave Pública

keys = api.keys.show

Preferências de notificação

Criação

api.notifications.create(
  events: ["ORDER.*", "PAYMENT.AUTHORIZED", "PAYMENT.CANCELLED"],
  target: "http://requestb.in/1dhjesw1",
  media: "WEBHOOK"
)

Consulta

api.notifications.show("NOTIFICATION-ID")

Exclusão

Caso o notification não seja encontrado uma exceção do tipo NotFoundError será lançada, veja como tratar aqui.

api.notifications.delete("NOTIFICATION-ID")

Listagem

api.notifications.find_all

Webhooks

Consulta

Todos Webhooks
webhooks = api.webhooks.find_all
Com Paginação
webhooks = api.webhooks.find_all(limit: 10, offset: 50)
Consulta Evento
webhooks = api.webhooks.find_all(event: "PAYMENT.WAITING")
Consulta Valor Específico
webhooks = api.webhooks.find_all(resource_id: "PAY-REJJ9F12MF7R")

Saldo Moip

Consulta

api.balances.show()

Show all entries

  api.entries.find_all

Show one entry

  api.entries.show(entry_id)

Tratamento de Exceções

Caso algum recurso não seja encontrado uma exceção do tipo NotFoundError será lançada.

begin
  api.payment.create(
    # ...
  )
rescue NotFoundError => e
  puts e.message
end

Documentação

Documentação oficial

Licença

The MIT License

Comunidade Slack Slack

Tem dúvidas? Fale com a gente no Slack!