cieloz 0.0.7 → 0.0.8
Sign up to get free protection for your applications and to get access to all the features.
- data/README.md +258 -35
- data/lib/cieloz/requisicao_transacao/dados_portador.rb +1 -1
- data/lib/cieloz/version.rb +1 -1
- data/test/unit/validations_test.rb +6 -1
- metadata +2 -2
data/README.md
CHANGED
@@ -1,9 +1,261 @@
|
|
1
1
|
[<img src="https://secure.travis-ci.org/fabiolnm/cieloz.png"/>](http://travis-ci.org/fabiolnm/cieloz)
|
2
|
+
[<img src="https://codeclimate.com/github/fabiolnm/cieloz.png"/>](https://codeclimate.com/github/fabiolnm/cieloz)
|
2
3
|
|
3
4
|
# Cieloz
|
4
5
|
|
5
6
|
A utility gem for SpreeCielo Gateway gem.
|
6
7
|
|
8
|
+
## Installation
|
9
|
+
|
10
|
+
Add this line to your application's Gemfile:
|
11
|
+
|
12
|
+
gem 'cieloz'
|
13
|
+
|
14
|
+
And then execute:
|
15
|
+
|
16
|
+
$ bundle
|
17
|
+
|
18
|
+
Or install it yourself as:
|
19
|
+
|
20
|
+
$ gem install cieloz
|
21
|
+
|
22
|
+
# Usage
|
23
|
+
|
24
|
+
This is a quick start guide to Cieloz API.
|
25
|
+
If you want to learn deeply about Cielo Gateway, read the Getting Started section.
|
26
|
+
|
27
|
+
## Low Level API: Requisicao objects
|
28
|
+
|
29
|
+
Provides a one-to-one ruby implementation for Cielo specification.
|
30
|
+
It's much more verbose than the High Level API, but provide a fine grained relation with Cielo WS API.
|
31
|
+
The High Level API is just a wrapper with convenient methods to handle with the Low Level API.
|
32
|
+
A developer must instantiates one of the available operations:
|
33
|
+
|
34
|
+
* RequisicaoTransacao
|
35
|
+
* RequisicaoConsulta
|
36
|
+
* RequisicaoCaptura
|
37
|
+
* RequisicaoCancelamento
|
38
|
+
|
39
|
+
Then populate them with appropriate data. This gem validates these request objects according to
|
40
|
+
Cielo Specifications present at Developer Guide (pages 10, 11, 26, 28 and 30), so it makes error
|
41
|
+
handling easier ans faster, before the request is sent to Cielo Web Service.
|
42
|
+
|
43
|
+
If the operation is valid, this gem serializes them as XML and submits to Cielo, parsing the
|
44
|
+
response as a Transaction (Transacao) or Error (Erro) objects. Both keeps the original XML response
|
45
|
+
as a xml attribute, so it can be logged.
|
46
|
+
|
47
|
+
### Authorization
|
48
|
+
|
49
|
+
dados_ec = Cieloz::Configuracao.credenciais
|
50
|
+
|
51
|
+
pedido = Cieloz::RequisicaoTransacao::DadosPedido.new numero: 123, valor: 5000, moeda: 986,
|
52
|
+
data_hora: now, descricao: "teste", idioma: "PT", soft_descriptor: "13letterstest"
|
53
|
+
|
54
|
+
pagamento = Cieloz::RequisicaoTransacao::FormaPagamento.new.credito "visa"
|
55
|
+
|
56
|
+
transacao = Cieloz::RequisicaoTransacao.new dados_ec: dados_ec,
|
57
|
+
dados_pedido: pedido,
|
58
|
+
forma_pagamento: pagamento,
|
59
|
+
url_retorno: your_callback_url
|
60
|
+
|
61
|
+
response = transacao.autorizacao_direta.submit
|
62
|
+
|
63
|
+
response.success? # returned Transacao (with status and id for the created Cielo transaction) or Error object?
|
64
|
+
|
65
|
+
### Verify
|
66
|
+
|
67
|
+
consulta = Cieloz::RequisicaoConsulta.new tid: transacao.tid, dados_ec: ec
|
68
|
+
resposta = consulta.submit
|
69
|
+
resposta.autorizada?
|
70
|
+
|
71
|
+
### Capture
|
72
|
+
|
73
|
+
captura = Cieloz::RequisicaoCaptura.new tid: transacao.tid, dados_ec: ec
|
74
|
+
resposta = captura.submit
|
75
|
+
resposta.capturada?
|
76
|
+
|
77
|
+
### Partial Capture
|
78
|
+
|
79
|
+
value = 1000 # a value less than the authorized
|
80
|
+
captura = Cieloz::RequisicaoCaptura.new tid: transacao.tid, dados_ec: ec, valor: value
|
81
|
+
resposta = captura.submit
|
82
|
+
resposta.capturada?
|
83
|
+
|
84
|
+
### Cancel
|
85
|
+
|
86
|
+
cancelar = Cieloz::RequisicaoCancelamento.new tid: transacao.tid, dados_ec: ec
|
87
|
+
resposta = cancelar.submit
|
88
|
+
resposta.cancelada?
|
89
|
+
|
90
|
+
### Partial Cancel
|
91
|
+
|
92
|
+
value = 1000 # a value less than the authorized
|
93
|
+
cancelar = Cieloz::RequisicaoCancelamento.new tid: transacao.tid, dados_ec: ec, valor: value
|
94
|
+
resposta = cancelar.submit
|
95
|
+
resposta.cancelada?
|
96
|
+
|
97
|
+
## High Level API: Cieloz::Buider
|
98
|
+
|
99
|
+
The easiest way to use this gem is through the high level API provided by Cieloz::Builder.
|
100
|
+
It provides convenient methods to build the respective Cieloz request objects from your domain model object.
|
101
|
+
|
102
|
+
### Cieloz.transacao - builds a RequisicaoTransacao object for Payment Authorization
|
103
|
+
|
104
|
+
pd = Cieloz.pedido order
|
105
|
+
pg = Cieloz.pagamento payment, operacao: :op, parcelas: :installments
|
106
|
+
tx = Cieloz.transacao nil, dados_pedido: pd, forma_pagamento: pg
|
107
|
+
|
108
|
+
### Cieloz.consulta - builds RequisicaoConsulta
|
109
|
+
|
110
|
+
consulta = Cieloz.consulta payment
|
111
|
+
|
112
|
+
### Cieloz.captura - builds RequisicaoCaptura
|
113
|
+
|
114
|
+
captura = Cieloz.captura payment # total capture
|
115
|
+
|
116
|
+
or
|
117
|
+
|
118
|
+
captura = Cieloz.captura payment, value: partial_value
|
119
|
+
|
120
|
+
|
121
|
+
### Cieloz.cancelamento - builds RequisicaoCancelamento
|
122
|
+
|
123
|
+
cancelamento = Cieloz.cancelamento payment # total cancel
|
124
|
+
|
125
|
+
or
|
126
|
+
|
127
|
+
cancelamento = Cieloz.cancelamento payment, value: partial_cancel
|
128
|
+
|
129
|
+
### Domain Model Mapping Startegies
|
130
|
+
|
131
|
+
High Level API uses three different strategies to extract the attribute values required to build Cielo object attribute
|
132
|
+
values to be serialized in XML format and sent to Cielo Web Service (see Domain Model Mapping Strategies below).
|
133
|
+
|
134
|
+
When an attribute cannot be resolved from one mapping strategy, Cieloz::Builder retrieves the default values configured
|
135
|
+
at Cieloz::Configuracao class:
|
136
|
+
|
137
|
+
@@mode = :cielo
|
138
|
+
@@moeda = 986 # ISO 4217 - Manual Cielo, p 11
|
139
|
+
@@idioma = "PT"
|
140
|
+
@@max_parcelas = 3
|
141
|
+
@@max_adm_parcelas = 10
|
142
|
+
@@captura_automatica = false
|
143
|
+
|
144
|
+
#### Default Naming Mappings
|
145
|
+
|
146
|
+
When your domain object attribute names are the same as the Cielo Web Service expect.
|
147
|
+
|
148
|
+
order.numero = "R123456"
|
149
|
+
order.valor = 12345
|
150
|
+
|
151
|
+
# creates Cieloz::RequisicaoTransacao::DadosPedido extracting order attributes
|
152
|
+
# that has the same names as DadosPedido attributes
|
153
|
+
pedido = Cieloz.pedido order
|
154
|
+
|
155
|
+
p pedido.numero
|
156
|
+
$ R123456
|
157
|
+
|
158
|
+
p pedido.valor
|
159
|
+
$ 12345
|
160
|
+
|
161
|
+
#### Domain Model Mappings
|
162
|
+
|
163
|
+
When you should provide a mapping between your domain model attributes and Cielo Web Service attributes.
|
164
|
+
|
165
|
+
order.number = "R123456"
|
166
|
+
order.value = 12345
|
167
|
+
|
168
|
+
# maps order.number to DadosPedido#numero
|
169
|
+
# and order.value to DadosPedido#valor
|
170
|
+
pedido = Cieloz.pedido order, numero: :number, valor: :value
|
171
|
+
|
172
|
+
p pedido.numero
|
173
|
+
$ R123456
|
174
|
+
|
175
|
+
p pedido.valor
|
176
|
+
$ 12345
|
177
|
+
|
178
|
+
#### Explicit Values
|
179
|
+
|
180
|
+
When you provide values.
|
181
|
+
|
182
|
+
pedido = Cieloz.pedido nil, numero: "R123456", valor: 12345
|
183
|
+
|
184
|
+
p pedido.numero
|
185
|
+
$ R123456
|
186
|
+
|
187
|
+
p pedido.valor
|
188
|
+
$ 12345
|
189
|
+
|
190
|
+
#### The strategies can be used together!
|
191
|
+
|
192
|
+
order.descricao = "Hello Cielo!"
|
193
|
+
pedido = Cieloz.pedido source, numero: number, valor: 12345
|
194
|
+
|
195
|
+
p pedido.numero
|
196
|
+
$ R123456
|
197
|
+
|
198
|
+
p pedido.valor
|
199
|
+
$ 12345
|
200
|
+
|
201
|
+
p pedido.descricao
|
202
|
+
$ Hello Cielo!
|
203
|
+
|
204
|
+
## Configuration
|
205
|
+
|
206
|
+
Your application can configure Cieloz::Configuracao default values.
|
207
|
+
In a Rails application, it can be done in a config/initializers/cieloz.rb file.
|
208
|
+
|
209
|
+
If you don't provide ```credenciais```, all operations will be requested against Cielo Homologation Environment.
|
210
|
+
|
211
|
+
When you go to production, you MUST configure ```credenciais``` with your Cielo ```numero``` and ```chave```.
|
212
|
+
|
213
|
+
YourApp::Application.class_eval do
|
214
|
+
# Runs in after initialize block to be able to access url helpers
|
215
|
+
config.after_initialize do
|
216
|
+
# must reload routes to initialize routes.url_helpers
|
217
|
+
reload_routes!
|
218
|
+
|
219
|
+
# These are Global Default Settings, and can be overriden at Bulder / Requisicao method levels
|
220
|
+
Cieloz::Configuracao.tap { |c|
|
221
|
+
# 13 letters descriptor to be printed on the buyer's credit card billing
|
222
|
+
c.soft_descriptor = "Your App name"
|
223
|
+
|
224
|
+
# Callback url: in Cielo Mode this is the location to where Cielo redirects a transaction
|
225
|
+
# after the user types this Credit card data.
|
226
|
+
#
|
227
|
+
# NOTICE: In order to *_url methods to work, it's required to set
|
228
|
+
# in config/application.rb or in one of config/environment initializers:
|
229
|
+
#
|
230
|
+
# [Rails.application.]routes.default_url_options = { host: "HOSTNAME[:PORT]" }
|
231
|
+
#
|
232
|
+
c.url_retorno = routes.url_helpers.root_url
|
233
|
+
|
234
|
+
# Credit card data is asked to the user in a page hosted by Cielo. This is the default mode
|
235
|
+
# c.cielo_mode!
|
236
|
+
|
237
|
+
# Your application must provide a view asking credit card data, and provide additional security,
|
238
|
+
# in conformance with PCI Standards: http://www.cielo.com.br/portal/cielo/solucoes-de-tecnologia/o-que-e-ais.html
|
239
|
+
# c.store_mode!
|
240
|
+
|
241
|
+
# default to Cieloz::Homologacao::Credenciais::LOJA if store_mode? and ::CIELO if cielo_mode?
|
242
|
+
# c.credenciais = { numero: "", chave: "" }
|
243
|
+
|
244
|
+
# c.moeda = 986 # ISO 4217 - Manual Cielo, p 11
|
245
|
+
# c.idioma = "PT" # EN and ES available - language to Cielo use in this pages
|
246
|
+
|
247
|
+
# http://www.cielo.com.br/portal/cielo/produtos/cielo/parcelado-loja.html
|
248
|
+
# c.max_parcelas = 3 # no additional interest rates
|
249
|
+
|
250
|
+
# http://www.cielo.com.br/portal/cielo/produtos/cielo/parcelado-administradora.html
|
251
|
+
# c.max_adm_parcelas = 10 # available with Cielo interest rate
|
252
|
+
|
253
|
+
# if true, payments are automatically captured by authorization request
|
254
|
+
# c.captura_automatica = false
|
255
|
+
}
|
256
|
+
end
|
257
|
+
end
|
258
|
+
|
7
259
|
## Getting Started
|
8
260
|
|
9
261
|
This is a step-by-step guide to enable Cielo Gateway as a payment method to your e-commerce store.
|
@@ -108,6 +360,8 @@ if supported by the selected credit card (Verified by Visa or MasterCard Secure
|
|
108
360
|
After authentication/authorization flow, if the user has available credit, the
|
109
361
|
transaction assumes Status 4 - AUTHORIZED (Autorizada).
|
110
362
|
|
363
|
+
#### RequisicaoCaptura
|
364
|
+
|
111
365
|
When the transaction is at AUTHORIZED state, the Store Owner must capture this payment in the
|
112
366
|
next five days. This can be done with a CaptureRequest (RequisicaoCaptura)
|
113
367
|
|
@@ -116,6 +370,8 @@ After capture, the transaction assumes Status 6 - CAPTURED (Capturada).
|
|
116
370
|
|
117
371
|
* Manual Capture can be useful for fraud prevention, but it requires aditional Admin efforts.
|
118
372
|
|
373
|
+
#### RequisicaoCancelamento
|
374
|
+
|
119
375
|
In the 90 days that follows the Authorization or Capture, the transaction can be fully or
|
120
376
|
partially cancelled, assuming state 9 - CANCELLED (Cancelada). This can be done with a
|
121
377
|
CancelRequest (RequisicaoCancelamento).
|
@@ -123,44 +379,11 @@ CancelRequest (RequisicaoCancelamento).
|
|
123
379
|
* At any time, a pending request can be expired at Cielo Gateway, that puts the transaction in CANCELLED state.
|
124
380
|
* Each state has its own expire time, see the Developer Guide for detailed information.
|
125
381
|
|
382
|
+
#### RequisicaoConsulta
|
383
|
+
|
126
384
|
At any time, a QueryRequest (RequisicaoConsulta) can be made for a specific transaction
|
127
385
|
(identified by its TID) to query about the state of the transaction.
|
128
386
|
|
129
|
-
### What is this gem about?
|
130
|
-
|
131
|
-
This gem provides a Ruby integration solution that consumes Cielo Web Services.
|
132
|
-
|
133
|
-
A developer just instantiates one of the available operations:
|
134
|
-
|
135
|
-
* RequisicaoTransacao
|
136
|
-
* RequisicaoConsulta
|
137
|
-
* RequisicaoCaptura
|
138
|
-
* RequisicaoCancelamento
|
139
|
-
|
140
|
-
Then populates them with appropriate data. This gem validates these request objects according to
|
141
|
-
Cielo Specifications present at Developer Guide (pages 10, 11, 26, 28 and 30), so it makes error
|
142
|
-
handling easier, before the request is sent to Cielo Web Service.
|
143
|
-
|
144
|
-
If the operation is valid, this gem serializes them as XML and submits to Cielo, parsing the
|
145
|
-
response as a Transaction (Transacao) or Error (Erro) objects. Both keeps the original XML response
|
146
|
-
as a xml attribute, so it can be logged.
|
147
|
-
|
148
|
-
## Installation
|
149
|
-
|
150
|
-
Add this line to your application's Gemfile:
|
151
|
-
|
152
|
-
gem 'cieloz'
|
153
|
-
|
154
|
-
And then execute:
|
155
|
-
|
156
|
-
$ bundle
|
157
|
-
|
158
|
-
Or install it yourself as:
|
159
|
-
|
160
|
-
$ gem install cieloz
|
161
|
-
|
162
|
-
## Usage
|
163
|
-
|
164
387
|
## Contributing
|
165
388
|
|
166
389
|
1. Fork it
|
data/lib/cieloz/version.rb
CHANGED
@@ -8,6 +8,12 @@ describe Cieloz::Requisicao::DadosEc do
|
|
8
8
|
end
|
9
9
|
|
10
10
|
describe Cieloz::RequisicaoTransacao::DadosPortador do
|
11
|
+
let(:_) { subject.class }
|
12
|
+
|
13
|
+
it "must not override codigo_seguranca if it's given for initializer" do
|
14
|
+
_.new(codigo_seguranca: "123").codigo_seguranca.wont_be_nil
|
15
|
+
end
|
16
|
+
|
11
17
|
it { must ensure_length_of(:nome_portador).is_at_most(50) }
|
12
18
|
|
13
19
|
it { must validate_presence_of :numero }
|
@@ -36,7 +42,6 @@ describe Cieloz::RequisicaoTransacao::DadosPortador do
|
|
36
42
|
end
|
37
43
|
|
38
44
|
describe "indicador and codigo_seguranca validation" do
|
39
|
-
let(:_) { subject.class }
|
40
45
|
let(:code) { 123 }
|
41
46
|
|
42
47
|
before do
|
metadata
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: cieloz
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.0.
|
4
|
+
version: 0.0.8
|
5
5
|
prerelease:
|
6
6
|
platform: ruby
|
7
7
|
authors:
|
@@ -9,7 +9,7 @@ authors:
|
|
9
9
|
autorequire:
|
10
10
|
bindir: bin
|
11
11
|
cert_chain: []
|
12
|
-
date: 2013-
|
12
|
+
date: 2013-03-18 00:00:00.000000000 Z
|
13
13
|
dependencies:
|
14
14
|
- !ruby/object:Gem::Dependency
|
15
15
|
name: nokogiri
|