Adicione ao Gemfile da sua aplicação a seguinte linha:
gem "maxipago", :git => "git://github.com/bonera/maxipago.git"
rails generate maxipago:install
Usamos o maxipago.net (Maxipago) para relizar transações financeiras dentro do aplicativo da Liga das Torcidas.
A construção da biblioteca foi realizada em cima do manual da *API V1.3* e da API de transação V3.1.1.15. O histórico das revisões pode ser visto no manual.
Para baixar o manual: www.maxipago.com/docs/maxiPago_API_Ultima.pdf
Para o ambiente de testes usamos as URLs fornecidas pelo Maxipago:
-
URL_TEST_TRANSACTION = “https//testapi.maxipago.net/UniversalAPI/postXML”
-
URL_TEST_API = “testapi.maxipago.net/UniversalAPI/postAPI”
-
URL_TEST_RAPI = “testapi.maxipago.net/ReportsAPI/servlet/ReportsAPI”
Cartões de teste:
-
American Express 378282246310005
-
American Express 371449635398431
-
MasterCard 5555555555554444
-
MasterCard 5105105105105100
-
Visa 4111111111111111
-
Visa 4012888888881881
-
No ambiente de testes nenhuma transação será de fato realizada.
O campo CVV pode ser preenchido com qualquer número entre *“3”* e *“4”* dígitos e a data de vencimento precisa ser válida. No futuro. Um cartão de teste já está adicionado ao arquivo de configuração da biblioteca. Veja mais detalhes sobre o uso nas seções posteriores.
Para realizar uma acão usando a bibioteca maxipago é preciso incluir as credenciais do estabelecimento. Qualquer requisição a API do Maxipago precisa ser autenticada.
O local para incluir essas credenciais bem como dados de teste ficam localizado em:
config/initializers/maxipago_config.rb
Aqui segue um exemplo do seu conteudo:
# API Request Config MP_APIKEY="" MP_ID="" MP_URL_TRANSACTION = "https://api.maxipago.net/UniversalAPI/postXML" MP_URL_API = "https://api.maxipago.net/UniversalAPI/postAPI" MP_URL_RAPI = "https://api.maxipago.net/ReportsAPI/servlet/ReportsAPI" MP_APIVERSION="3.1.1.15" # Test Card Example VISA_CARD = "4111111111111111" EXP_YEAR = "2020" CVV = "999" ECOMMIND = "eci" # Test Urls URL_TEST_TRANSACTION = "https//testapi.maxipago.net/UniversalAPI/postXML" URL_TEST_API = "https://testapi.maxipago.net/UniversalAPI/postAPI" URL_TEST_RAPI = "https://testapi.maxipago.net/ReportsAPI/servlet/ReportsAPI"
Uma outra maneira de passar essas credenciais é no próprio objeto Maxipago.
mp = Maxipago::Client.new(MP_ID, MP_APIKEY, MP_APIVERSION) => #<Maxipago::Client:0x007fc5a4ebf340 @maxid="12345", @apikey="xxxxxxxxxxxxxxxxxx", @apiversion="3.1.1.15">
Dentro do Rails a biblioteca busca pelos valores setados no arquivo de configuração, caso não exista você ainda sim poderá passar na inicialização do objeto.
A forma como é passada as credenciais no xml:
<verification>
<merchantId>#{MP_ID}</merchantId>
<merchantKey>#{MP_APIKEY}</merchantKey>
</verification>
Qualquer xml segue esse padrão de post. Sem esse padrão não existe autenticação.
A biblioteca está divida em 3 classes principais dentro do módulo Maxipago:
-
client
-
request
-
builder
Client é a classe principal, todos os comandos são executados no objeto do tipo client.
Client -> Request -> Builder Client <- Request <- Builder
O Builder monta o xml necessário para o post que será enviado para a api. O request é montado pela classe Request que é chamada pela classe Client. Basta usar o Client para enviar comandos e obter a resposta do post.
O client executa comandos na api do Maxipago. Para isso é necessário escolher antes a api que será usada. Existem 3 tipos:
-
Transações (transaction)
-
Cadastro (api)
-
Consulta ou Relatórios (rapi)
Primeiro fornecemos id, key e versão da api:
mp = Maxipago::Client.new(MP_ID, MP_APIKEY, MP_APIVERSION)
Depois escolhemos o tipo de api que queremos usar:
mp.use("api")
Em seguida enviamos o comando a ser executado e os parâmetros aceitos pelo comando:
mp.command(command: "", params)
Por último pegamos a resposta do request:
mp.response
Esse é o workflow básico para se executar um comando nas apis do Maxipago.
*Autorização*
A Autorização verifica se o cartão de crédito usado é válido (número, CVV e data de vali dade), se o Portador possui limite suficiente para a compra e se a transação passou n a verificação de fraude do Banco e da Adquirente. Esta é a fase mais importante da transação, pois a autorização bloqueia o valo r do pedido no cartão do cliente e garante o pagamento para o Estabelecimento, “reservando” aquele valor. Contudo, a autorização sozinha não efetiva a transaçã o – ela depois precisa ser capturada.
mp.user("transaction") mp.command( command: "authorization", processor_id: "1", reference_num: "123456", number: "4111111111111111", exp_month: "12", exp_year: "2020", cvv_number: "999", charge_total: "100.00", number_of_installments: "2", charge_interest: "N" )
Padrão da resposta:
mp.response[:body] "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<transaction-response>\n<authCode>123456</authCode>\n<orderID>0AF9063D:013656424703:F6B0:01DDA560</orderID>\n<referenceNum>123456789</referenceNum>\n<transactionID>6060940</transactionID>\n<transactionTimestamp>1332887045</transactionTimestamp>\n<responseCode>0</responseCode>\n<responseMessage>AUTHORIZED</responseMessage>\n<avsResponseCode>YYY</avsResponseCode>\n<cvvResponseCode>M</cvvResponseCode>\n<processorCode>A</processorCode>\n<processorMessage>APPROVED</processorMessage>\n<errorMessage/>\n</transaction-response>\n"
Copyright 2012 Bonera Software e Participações S/A.
Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.