atpay_ruby 0.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA1:
3
+ metadata.gz: 3d43d93d769df62049e904ef5cdf170c069a8c4e
4
+ data.tar.gz: 6cf5319537ca51a399d9fa256e6feed093e66371
5
+ SHA512:
6
+ metadata.gz: 3c170efc266798354d8be5d8473c2f01a5720e1f310edf4ac4392a1855dcf6c71925f1c24d9ff90522275c8881b5e79cacc54f53b2ac47ee5e39df502a2ee581
7
+ data.tar.gz: e0f838be8ffdff53f81d1687937d22b87bcf7d44066367daab0c81927acdf947fde5f830c455cbff41187a0eb61b32c8032028785b8d60afee927de9d5a53049
data/.gitignore ADDED
@@ -0,0 +1 @@
1
+ *.un~
data/.ruby-version ADDED
@@ -0,0 +1 @@
1
+ 2.0.0-p451
data/Gemfile ADDED
@@ -0,0 +1,2 @@
1
+ source "https://rubygems.org"
2
+ gemspec
data/README.md ADDED
@@ -0,0 +1,277 @@
1
+ # @Pay Ruby Bindings
2
+
3
+ @Pay API bindings for Ruby and a full implementation of @Pay's
4
+ [**Token Protocol**](http://developer.atpay.com/v3/tokens/protocol/) and **Email Button**
5
+ generation system. See the [@Pay Developer Site](http://developer.atpay.com/)
6
+ for additional information.
7
+
8
+ ## Installation
9
+
10
+ `gem install atpay_ruby`
11
+
12
+ If you're using Bundler, you can add `atpay_ruby` to your application's Gemfile.
13
+
14
+ ## Configuration
15
+
16
+ You'll need a **Session** object configured with your API credentials from
17
+ from `https://dashboard.atpay.com/` (API Settings):
18
+
19
+ ```ruby
20
+ require 'atpay'
21
+ ATPAY_SESSION = AtPay::Session.new(partner_id, public_key, private_key)
22
+ ```
23
+
24
+ The **Session** is thread-safe and read-only. You can safely use a single instance from
25
+ a configuration initializer.
26
+
27
+ ## Web Hook Verification
28
+
29
+ Configure **Web Hooks** on the [@Pay Merchant Dashboard](https://dashboard.atpay.com)
30
+ under "API Settings." Use the **Hook** class to parse incoming requests and
31
+ verify the **Hook Request Signature**. Requests with an invalid signature should
32
+ be discarded.
33
+
34
+ `params` is expected to contain the two url-encoded POST variables sent to your
35
+ **Web Hook Endpoint** from @Pay's servers. See the [Web Hook Developer
36
+ Documentation](http://developer.atpay.com/v3/hooks/) for additional information.
37
+
38
+ A sample Rails **Web Hook Endpoint**:
39
+
40
+ ```ruby
41
+ # app/controllers/transactions_controller.rb
42
+ class TransactionsController < ApplicationController
43
+ def create
44
+ hook = AtPay::Hook(ATPAY_SESSION, params)
45
+ render text: hook.details.inspect
46
+ rescue AtPay::InvalidSignatureError
47
+ head 403
48
+ end
49
+ end
50
+
51
+ # config/routes.rb
52
+ resources :transactions, only: [:create]
53
+ ```
54
+
55
+ ## Token Overview
56
+
57
+ A **Token** is a value that contains information about a financial transaction (an invoice
58
+ or a product sales offer, for instance). When a **Token** is sent to
59
+ `transaction@processor.atpay.com` from an address associated with a **Payment Method**,
60
+ it will create a **Transaction**.
61
+
62
+ There are two classes of **Token** @Pay processes - the **Invoice Token**, which should
63
+ be used for sending invoices or transactions applicable to a single
64
+ recipient, and the **Bulk Token**, which is suitable for email marketing lists.
65
+
66
+ An **Email Button** is a link embedded in an email message. When activated, this link
67
+ opens a new outgoing email with a recipient, subject, and message body
68
+ prefilled. By default this email contains one of the two token types. Clicking
69
+ 'Send' delivers the email to @Pay and triggers **Transaction** processing. The sender will
70
+ receive a receipt or further instructions.
71
+
72
+ ## Invoice Tokens
73
+
74
+ An **Invoice** token is ideal for sending invoices or for transactions that are
75
+ only applicable to a single recipient (shopping cart abandonment, specialized
76
+ offers, etc).
77
+
78
+ The following creates a token for a 20 dollar transaction specifically for the
79
+ credit card @Pay has associated with 'test@example.com':
80
+
81
+ ```ruby
82
+ token = AtPay::Token::Invoice.new(session, 20.00, 'test@example.com')
83
+ puts token.to_s
84
+ ```
85
+
86
+ ## Bulk Tokens
87
+
88
+ Most merchants will be fine generating **Bulk Email Buttons** manually on the [@Pay Merchant
89
+ Dashboard](https://dashboard.atpay.com), but for cases where you need to
90
+ automate the generation of these messages, you can create **Bulk Tokens** without
91
+ communicating directly with @Pay's servers.
92
+
93
+ A **Bulk Token** is designed for large mailing lists. You can send the same token
94
+ to any number of recipients. It's ideal for 'deal of the day' type offers, or
95
+ general marketing.
96
+
97
+ To create a **Bulk Token** for a 30 dollar offer:
98
+
99
+ ```ruby
100
+ token = AtPay::Token::Bulk.new(session, 30.00)
101
+ ```
102
+
103
+ If a recipient of this token attempts to purchase the product via email but
104
+ hasn't configured a credit card, they'll receive a message asking them to
105
+ complete their transaction. You should integrate [@PayJS](http://developer.atpay.com/v3/javascript/)
106
+ on that page to enable Customers' two-click email transactions in the future.
107
+
108
+ ## General Token Attributes
109
+
110
+ ### Auth Only
111
+
112
+ A **Token** will trigger a funds authorization and a funds capture
113
+ simultaneously. If you're shipping a physical good, or for some other reason
114
+ want to delay the capture, use the `auth_only!` method to adjust this behavior:
115
+
116
+ ```ruby
117
+ token = AtPay::Token::Invoice.new(session, 20.00, 'test@example.com')
118
+ token.auth_only!
119
+ email(token.to_s)
120
+ ```
121
+
122
+ ### Expiration
123
+
124
+ A **Token** expires in 2 weeks unless otherwise specified. Trying to use the **Token**
125
+ after the expiration results in a polite error message being sent to the sender.
126
+ To adjust the expiration:
127
+
128
+ ```ruby
129
+ token = AtPay::Token::Invoice.new(session, 20.00, 'test@example.com')
130
+ token.expires_in_seconds = 60 * 60 * 24 * 7 # 1 week
131
+ ```
132
+
133
+ ### Signup Page
134
+
135
+ When a new Customer or a Customer with expired or invalid credit card details
136
+ attempts to purchase from an Email, they will be redirected to a Token's **Payment Capture Page**,
137
+ where they can enter new Credit Card details. By default @Pay will host the
138
+ **Payment Capture Page**, but you may wish to direct the Customer to a product page on
139
+ your own site (Enable @Pay Card tokenization on your own page with the
140
+ [@PayJS](http://developer.atpay.com/v3/javascript/)). To specify a custom
141
+ URL:
142
+
143
+ ```ruby
144
+ token = AtPay::Token::Invoice.new(session, 20.00, 'test@example.com')
145
+ token.url = 'https://example.com/invoices/123'
146
+ ```
147
+
148
+ #### Requesting Custom Information on a Hosted Signup Page
149
+
150
+ If you opt to use the **Hosted Payment Capture Page** (by not specifying a URL above), you
151
+ can request further information from your Customer during the purchase on the
152
+ Web. For instance, the following requests an optional Gift Message:
153
+
154
+ ```ruby
155
+ token = AtPay::Token::Bulk.new(session, 20.00)
156
+ token.request_custom_data!('gift_message', required: false)
157
+ ```
158
+
159
+ #### Requesting the URL of a Hosted Signup Page
160
+
161
+ The **Hosted Payment Capture Page** is related directly to a Token. It is
162
+ created when the token is first received at `transaction@processor.atpay.com` or
163
+ when the URL is requested from @Pay prior to the first use. To request the URL, you
164
+ must contact @Pay's server:
165
+
166
+ ```ruby
167
+ token = AtPay::Token::Invoice.new(session, 20.00, 'test@example.com')
168
+ registration = token.register!
169
+
170
+ registration.url
171
+ => "https://example.secured.atpay.com/{token_identifier}"
172
+
173
+ registration.short
174
+ => "atpay://{token_identifier}"
175
+ ```
176
+
177
+ NOTE: For high traffic this solution may be inadequate. Contact @Pay for
178
+ consultation.
179
+
180
+
181
+ #### Item Name
182
+
183
+ You can set an **item name** that will display on the **Hosted Payment Capture Page**.
184
+
185
+ ```ruby
186
+ token = AtPay::Token::Invoice.new(session, 20.00, 'test@example.com')
187
+ token.name = "A Cool Offer"
188
+ email(token.to_s, receipient_address)
189
+ ```
190
+
191
+ #### Item Details
192
+
193
+ You can set an **item details** that will display on the **Hosted Payment Capture Page**.
194
+
195
+
196
+ ```ruby
197
+ token = AtPay::Token::Invoice.new(session, 20.00, 'test@example.com')
198
+ token.set_item_details = "Lorem Ipsum ..."
199
+ email(token.to_s, receipient_address)
200
+ ```
201
+
202
+
203
+ #### Address Collection
204
+
205
+ Request the **Hosted Payment Capture Page** collect any combination
206
+ of shipping or billing address with `requires_shipping_address=` and
207
+ `requires_billing_address=`:
208
+
209
+ ```
210
+ token = AtPay::Token::Invoice.new(session, 20.00, 'test@example.com')
211
+ token.requires_shipping_address = true
212
+ token.requires_billing_address = true
213
+ email(token.to_s, receipient_address)
214
+ ```
215
+
216
+ ### Set Item Quantity
217
+
218
+ If you are using @Pay's webhook for inventory control, you can specify an initial quantity for the offer you are creating.
219
+
220
+ ```ruby
221
+ token = AtPay::Token::Invoice.new(session, 20.00, 'test@example.com')
222
+ token.set_item_quantity = 3
223
+ email(token.to_s, receipient_address)
224
+ ```
225
+
226
+
227
+ ### Fulfillment Time
228
+
229
+ **Transaction Details** from @Pay may include an **Estimated Fulfillment Time**.
230
+ @Pay expects **Auth Only** transactions when fulfillment is required.
231
+ A Transaction should be Captured only when fulfillment is completed.
232
+
233
+ ```ruby
234
+ token = AtPay::Token::Invoice.new(session, 20.00, 'test@example.com')
235
+ token.estimated_fulfillment_days = 3
236
+ email(token.to_s, receipient_address)
237
+ ```
238
+
239
+ ### Custom User Data
240
+
241
+ **Custom User Data** is a token attribute that contains any string that you wish to get back in @Pay’s
242
+ response on processing the token. It has a limit of 2500 characters.
243
+
244
+ ```ruby
245
+ token = AtPay::Token::Invoice.new(session, 20.00, 'test@example.com')
246
+ token.custom_user_data = 'some-value'
247
+ email(token.to_s, receipient_address)
248
+ ```
249
+
250
+
251
+ ## Button Generation
252
+
253
+ To create a friendly button that wraps your token:
254
+
255
+ ```ruby
256
+ token = AtPay::Token::Invoice.new(session, 20.00, 'test@example.com')
257
+ button = AtPay::Button.new(token.to_s, 20.00, 'My Company', wrap: true).render
258
+ email(button, recipient_address)
259
+ ```
260
+
261
+ Default options are [AtPay::Button::OPTIONS](lib/atpay/button.rb).
262
+
263
+ ## Command Line Usage
264
+
265
+ The `atpay` utility generates **Invoice Tokens**, **Bulk Tokens**, and **Email Buttons**
266
+ that you can embed in outgoing email. Run `atpay help` for more details.
267
+
268
+ ```bash
269
+ $ atpay token invoice --partner_id=X --private_key=X --amount=20.55 --target=test@example.com --user-data=sku-123
270
+ => @...@
271
+
272
+ $ atpay token bulk --partner_id=X --private-key=X --amount=20.55 --url="http://example.com/product"
273
+ => @...@
274
+
275
+ $ atpay token invoice --partner_id=X --private_key=X --amount=20.55 --target=test@example.com --user-data=sku-123 | atpay button generic --amount=20.55 --merchant="Mom's"
276
+ => <p>...</p>
277
+ ```
@@ -0,0 +1,72 @@
1
+ <!— begin @Pay button —>
2
+
3
+ <style>
4
+ .ExternalClass table.reg_mailto {display:none; display: none !important;}
5
+
6
+ .ExternalClass table.out_mailto {display: table; display: table !important; font-size: 18px !important; width: auto !important; height: auto !important;}
7
+ .ExternalClass table.out_mailto {font-family: Tahoma; color: #ffffff; background-color:{{background_color}};}
8
+
9
+ .ExternalClass table.out_mailto td.dollar{vertical-align:top !important; padding-right:0px !important; font-size:24px !important; padding-top:15px !important; text-align:right !important; padding-bottom:10px !important; padding-left:10px;}
10
+
11
+ .ExternalClass table.out_mailto td.cents{vertical-align:top !important; font-size:12px !important; padding-left:1px !important; padding-right:10px !important; padding-bottom:0px !important; padding-top:15px !important; text-align:left !important; text-decoration:underline !important;}
12
+
13
+ .ExternalClass table.out_mailto td img {display: block !important; height: 32px !important; width: 39px !important;}
14
+
15
+ .ExternalClass table.out_mailto td.cart{width:45px !important; padding-left:10px !important; height:39px !important; text-align:right}
16
+
17
+ .ExternalClass table.out_mailto a {display: inline !important; border: 0 !important; width:auto !important; text-decoration:none !important; color:{{foreground_color}} !important; line-height:auto !important;}
18
+ </style>
19
+
20
+ <center>
21
+ {% if analytic_url %}
22
+ <img src="{{analytic_url}}" width="1" height="1" />
23
+ {% endif %}
24
+
25
+ <table class="reg_mailto" border='0' cellpadding='0' cellspacing='0' style='font-family: Tahoma; margin: 0 auto !important; background-color:{{background_color}};'>
26
+ <tr>
27
+ {% if image %}
28
+ <td style="padding-left:10px; padding-right:0px; padding-top:14px; padding-bottom:10px;text-align:right;">
29
+ <a class="reg_mailto" href="{{url}}" target="_blank" style="border-width: 0px;">
30
+ <img src="{{image}}" style="display:block; border-width: 0px;" />
31
+ </a>
32
+ </td>
33
+ {% endif %}
34
+ <td style="vertical-align:top; padding-left:10px; padding-right:0px; font-size:24px; padding-top:15px; text-align:right; padding-bottom:10px;" valign="top">
35
+ <a class="reg_mailto" href="{{url}}" style="display: inline; width:auto; border-width: 0px; line-height:auto; text-decoration:none; color: {{foreground_color}};" target="_blank">
36
+ {{dollar}}
37
+
38
+ </a>
39
+ </td>
40
+
41
+ <td class="cents" style="vertical-align:top; font-size:12px; padding-left:1px; padding-right:10px; padding-bottom:0px; padding-top:15px; text-align:left; text-decoration:none;" valign="top">
42
+ <a class="reg_mailto" href="{{url}}" style="display: inline; border: 0 !important; width:auto; text-decoration:none !important; color:{{foreground_color}}; line-height:auto;" valign="top" target="_blank">{{cents}}</a>
43
+ </td>
44
+
45
+ </tr>
46
+ </table>
47
+
48
+ <table class='out_mailto' border='0' cellpadding='0' cellspacing='0' style='width:0; height:0; padding:0; margin:0; font-size:0;'>
49
+ <tr>
50
+ {% if image %}
51
+ <td class='cart'>
52
+ <a href='{{outlook_url}}' style='display:none; border-width: 0px;' target="_blank">
53
+ <img src='{{image}}' style='margin: 0px; width:0px; height:0px; border-width: 0px;'>
54
+ </a>
55
+ </td>
56
+ {% endif %}
57
+ <td class='dollar' style='width:0; height:0; padding:0; margin:0; font-size:0;' valign='top'>
58
+ <a href='{{outlook_url}}' style='display:none; border-width: 0px;' target="_blank">
59
+ {{dollar}}
60
+ </a>
61
+ </td>
62
+ <td class='cents' style='width:0; height:0; padding:0; margin:0; font-size:0;' valign='top'>
63
+ <a href='{{outlook_url}}' style='display:none; border-width: 0px;' target="_blank">
64
+ {{cents}}
65
+ </a>
66
+ </td>
67
+ </tr>
68
+ </table>
69
+ </center>
70
+
71
+
72
+ <!— end @Pay button —>
@@ -0,0 +1,8 @@
1
+
2
+ Send this email order form to confirm your purchase of {{amount}}. If we need more info we will let you know. Thanks!
3
+
4
+
5
+
6
+ ---
7
+
8
+ This code secures and validates your transaction:
@@ -0,0 +1,130 @@
1
+ <!— begin @Pay button —>
2
+ <!-- regular template with wrap -->
3
+
4
+ <style type="text/css">
5
+
6
+ .ExternalClass table.reg_mailto {display:none; display: none !important;}
7
+
8
+ .ExternalClass table.out_mailto {display: table; display: table !important; font-size: 18px !important; width: auto !important; height: auto !important;}
9
+ .ExternalClass table.out_mailto {font-family: Tahoma; color: #ffffff; background-color: {{background_color}};}
10
+
11
+ .ExternalClass table.out_mailto td.dollar{vertical-align:top !important; padding-right:0px !important; font-size:24px !important; padding-top:15px !important; text-align:right !important; padding-bottom:10px !important; padding-left:10px;}
12
+
13
+ .ExternalClass table.out_mailto td.cents{vertical-align:top !important; font-size:12px !important; padding-left:1px !important; padding-right:10px !important; padding-bottom:0px !important; padding-top:15px !important; text-align:left !important; text-decoration:underline !important;}
14
+
15
+ .ExternalClass table.out_mailto td img {display: block !important; height: 32px !important; width: 39px !important;}
16
+
17
+ .ExternalClass table.out_mailto td.cart{width:45px !important; padding-left:10px !important; height:39px !important; text-align:right}
18
+
19
+ .ExternalClass table.out_mailto a {display: inline !important; border: 0 !important; width:auto !important; text-decoration:none !important; color:{{foreground_color}} !important; line-height:auto !important;}
20
+ </style>
21
+
22
+ <center>
23
+ <table cellpadding='0' cellspacing='0' style='margin: 0px auto 20px !important;'>
24
+ <tr>
25
+ <td>
26
+ <table style='border-collapse:separate !important; width:200px;margin: auto; margin-bottom:5px; font-family: Lato; padding-bottom:10px; position:relative; padding-left:5px; padding-right:10px; margin-bottom:0px; margin-top:5px; padding:10px;padding-top:0; border-left: 1px solid #e4e2e2; border-top: 1px solid #e4e2e2; border-right: 1px solid #e4e2e2; '>
27
+ <tr>
28
+ <td colspan='3'>
29
+ <p style='margin-bottom:0px; color: #515050; font-size:12px; margin-top:2px; text-align:center;'>
30
+ {{wrap_text}}
31
+ </p>
32
+ </td>
33
+ </tr>
34
+ <tr>
35
+ <td style="padding-top:10px; padding-bottom:10px;">
36
+ <!-- BUTTON CODE -->
37
+
38
+ <center>
39
+ {% if analytic_url %}
40
+ <img src="{{analytic_url}}" width="1" height="1" />
41
+ {% endif %}
42
+
43
+ <table class="reg_mailto" border='0' cellpadding='0' cellspacing='0' style='margin:0px auto !important; font-family: Tahoma; background-color:{{background_color}};'>
44
+ <tr>
45
+ {% if image %}
46
+ <td style="padding-left:10px; padding-right:0px; padding-top:14px; padding-bottom:10px;text-align:right;">
47
+ <a class="reg_mailto" href="{{url}}" target="_blank" style="border-width: 0px;">
48
+ <img src="{{image}}" style="display:block; border-width: 0px;" />
49
+ </a>
50
+ </td>
51
+ {% endif %}
52
+ <td style="vertical-align:top; padding-left:10px; padding-right:0px; font-size:24px; padding-top:15px; text-align:right; padding-bottom:10px;" valign="top">
53
+ <a class="reg_mailto" href="{{url}}" style="display: inline; width:auto; border: 0px !important; line-height:auto; text-decoration: none; color: {{foreground_color}};" target="_blank">
54
+ {{dollar}}
55
+
56
+ </a>
57
+ </td>
58
+
59
+ <td class="cents" style="vertical-align:top; font-size:12px; padding-left:1px; padding-right:10px; padding-bottom:0px; padding-top:15px; text-align:left; text-decoration:none;" valign="top">
60
+ <a class="reg_mailto" href="{{url}}" style="display: inline; border: 0px !important; width:auto; text-decoration:none; color:{{foreground_color}}; line-height:auto;" valign="top" target="_blank">{{cents}}</a>
61
+ </td>
62
+
63
+ </tr>
64
+ </table>
65
+
66
+ <table class='out_mailto' border='0' cellpadding='0' cellspacing='0' style='display:none; width:0; height:0; padding:0; margin:0; font-size:0;'>
67
+ <tr>
68
+ {% if image %}
69
+ <td class='cart'>
70
+ <a href='{{outlook_url}}' style='display:none; border-width: 0px;' target="_blank">
71
+ <img src='{{image}}' style='margin: 0px; width:0px; height:0px; border-width: 0px;'>
72
+ </a>
73
+ </td>
74
+ {% endif %}
75
+ <td class='dollar' style='width:0; height:0; padding:0; margin:0; font-size:0;' valign='top'>
76
+ <a href='{{outlook_url}}' style='display:none; border: 0 !important;' target="_blank">
77
+ {{dollar}}
78
+ </a>
79
+ </td>
80
+ <td class='cents' style='width:0; height:0; padding:0; margin:0; font-size:0;' valign='top'>
81
+ <a href='{{outlook_url}}' style='display:none; border: 0 !important;' target="_blank">
82
+ {{cents}}
83
+ </a>
84
+ </td>
85
+ </tr>
86
+ </table>
87
+ </center>
88
+
89
+ <!-- END BUTTON CODE -->
90
+
91
+ </td>
92
+ </tr>
93
+ </table>
94
+ </td>
95
+ </tr>
96
+ <tr>
97
+ <td>
98
+ <table cellpadding='0' cellspacing='0' style='width:100%;' width='100%'>
99
+ <tr>
100
+ <td valign='top'>
101
+ <table cellpadding='0' cellspacing='0' height='10' style='font-size: 1px; line-height: 1px; border-left: 1px #e4e2e2 solid; border-bottom: 1px #e4e2e2 solid; height:10px; width: 100%;'>
102
+ <tr>
103
+ <td>
104
+ &nbsp;
105
+ </td>
106
+ </tr>
107
+ </table>
108
+ </td>
109
+ <td width='155'>
110
+ <center>
111
+ <img src='https://atpay.com/wp-content/uploads/2013/05/email_chout_tag.png'>
112
+ </center>
113
+ </td>
114
+ <td valign='top' width='20'>
115
+ <table cellpadding='0' cellspacing='0' height='10' style='font-size: 1px; line-height: 1px; border-right: 1px #e4e2e2 solid; border-bottom: 1px #e4e2e2 solid; height:10px; width: 100%;'>
116
+ <tr>
117
+ <td>
118
+ &nbsp;
119
+ </td>
120
+ </tr>
121
+ </table>
122
+ </td>
123
+ </tr>
124
+ </table>
125
+ </td>
126
+ </tr>
127
+ </table>
128
+ </center>
129
+
130
+ <!— end @Pay button —>