gerencianet 0.0.1 → 0.0.2

data/docs/charge-detailing.md

@@ -0,0 +1,42 @@
+## Detailing charges
+
+It's very simple to get details from a charge. You just need the id:
+
+```ruby
+params = {
+  id: 1000
+}
+
+gerencianet = Gerencianet.new(options)
+gerencianet.detail_charge(params: params)
+```
+
+As response, you will receive all the information about the charge (including if it belongs to a subscription or carnet):
+
+```ruby
+{
+  "code": 200,
+  "data": {
+    "charge_id": 233,
+    "subscription_id": 12,
+    "total": 2000,
+    "status": "new",
+    "custom_id": null,
+    "created_at": "2015-05-14",
+    "notification_url": "http://yourdomain.com",
+    "items": [
+      {
+        "name": "Product 1",
+        "value": 1000,
+        "amount": 2
+      }
+    ],
+    "history": [
+      {
+        "status": "new",
+        "created_at": "2015-05-14 15:39:14"
+      }
+    ]
+  }
+}
+```

data/docs/charge-payment.md

@@ -0,0 +1,145 @@
+## Paying charges
+
+There are two ways of giving sequence to a charge. You can generate a banking billet so it is payable until its due date, or can use the customer's credit card to submit the payment.
+
+### 1. Banking billets
+
+Setting banking billet as a charge's payment method is simple. You have to use `banking_billet` as the payment method and inform the `charge_id`.
+
+```ruby
+require "gerencianet"
+require "date"
+
+tomorrow = Date.today + 1
+
+params = {
+  id: 2365
+}
+
+body = {
+  payment: {
+    banking_billet: {
+      expire_at: tomorrow.strftime,
+      customer: {
+        name: "Gorbadoc Oldbuck",
+        email: "oldbuck@gerencianet.com.br",
+        cpf: "04267484171",
+        birth: "1977-01-15",
+        phone_number: "5144916523"
+      }
+    }
+  }
+}
+
+gerencianet = Gerencianet.new(options)
+gerencianet.pay_charge(params: params, body: body)
+```
+
+If you don't set the `expire_at` attribute, the date will be the current day + 3.
+
+You'll receive the payment info in the callback, such as the barcode and the billet link:
+
+```ruby
+{
+  "code": 200,
+  "data": {
+    "charge_id": 242,
+    "total": 1150,
+    "payment": "banking_billet",
+    "barcode": "00190.00009 01523.894002 00059.161182 9 64350000001150",
+    "link": "https://visualizacao.gerencianet.com.br/emissao/28333_2139_RRABRA7/A4XB-28333-59161-BRANAE4",
+    "expire_at": "2015-05-21"
+  }
+}
+```
+
+If you want the banking billet to have extra instructions, it's possible to send a maximum of 4 different instructions with a maximum of 90 caracters, just as follows:
+
+```ruby
+var body = {
+  payment: {
+    banking_billet: {
+      expire_at: tomorrow.strftime,
+      customer: {
+        name: "Gorbadoc Oldbuck",
+        email: "oldbuck@gerencianet.com.br",
+        cpf: "04267484171",
+        birth: "1977-01-15",
+        phone_number: "5144916523"
+      },
+      instructions: [
+        "Pay only with money",
+        "Do not pay with gold"
+      ]
+    }
+  }
+}
+```
+
+### 2. Credit card
+
+The most common payment method is to use a credit card in order to make things happen faster. Paying a charge with a credit card in Gerencianet is as simples as generating a banking billet, as seen above.
+
+The difference here is that we need to provide some extra information, as a `billing_address` and a `payment_token`. The former is used to make an anti-fraud analyze before accepting/appoving the payment, the latter identifies a credit card at Gerencianet, so that you don't need to bother about keeping track of credit card numbers. The `installments` attribute is self-explanatory.
+
+We'll talk about getting payment tokens later. For now, let's take a look at the snipet that does the work we're aiming for:
+
+```ruby
+body = {
+  payment: {
+    credit_card: {
+      installments: 1,
+      payment_token: "5739b06925244dd1ab8e0afa62389d5fb4ea2945",
+      billing_address: {
+        street: "Av. JK",
+        number: 909,
+        neighborhood: "Bauxita",
+        zipcode: "35400000",
+        city: "Ouro Preto",
+        state: "MG"
+      },
+      customer: {
+        name: "Gorbadoc Oldbuck",
+        email: "oldbuck@gerencianet.com.br",
+        cpf: "04267484171",
+        birth: "1977-01-15",
+        phone_number: "5144916523"
+      }
+    }
+  }
+}
+
+params = {
+  id: 2366
+}
+
+gerencianet = Gerencianet.new(options)
+gerencianet.pay_charge(params: params, body: body)
+```
+
+If everything went well, the response will come with the total value, installments number and the value of each installment:
+
+```ruby
+{
+  "code": 200,
+  "data": {
+    "charge_id": 223,
+    "total": 1150,
+    "payment": "credit_card",
+    "installments": 1,
+    "installment_value": 1150
+  }
+}
+```
+
+##### Payment tokens
+
+A `payment_token` represents a credit card number at Gerencianet.
+
+For testing purposes, you can go to your application playground in your Gerencianet's account. At the payment endpoint you'll see a button that generates one token for you. This payment token will point to a random test credit card number.
+
+When in production, it will depend if your project is a web app or a mobile app.
+
+For web apps you should follow this [guide](https://api.gerencianet.com.br/checkout/card). It basically consists of copying/pasting a script tag in your checkout page.
+
+For mobile apps you should use this [SDK for Android](https://github.com/gerencianet/gn-api-sdk-android) or this [SDK for iOS](https://github.com/gerencianet/gn-api-sdk-ios).

data/docs/charge-update.md

@@ -0,0 +1,52 @@
+## Updating charges
+
+### Changing the metadata
+
+You can update the `custom_id` or the `notification_url` of a charge:
+
+```ruby
+params = {
+  id: 1008
+}
+
+body = {
+  notification_url: "http://yourdomain.com",
+  custom_id: "my_new_id"
+}
+
+gerencianet = Gerencianet.new(options)
+gerencianet.update_charge_metadata(params: params, body: body)
+```
+
+If everything goes well, the return will be:
+
+```ruby
+{
+  "code": 200
+}
+```
+
+### Updating the expiration date of a billet
+
+Only charges with status `waiting` or `unpaid` and with payment method `banking_billet` can have the `expire_at` changed:
+
+```ruby
+params = {
+  id: 1008
+}
+
+body = {
+  expire_at: "2020-12-12"
+}
+
+gerencianet = Gerencianet.new(options)
+gerencianet.update_billet(params: params, body: body)
+```
+
+If everything goes well, the return will be:
+
+```ruby
+{
+  "code": 200
+}
+```

data/docs/charge-with-marketplace.md

@@ -0,0 +1,54 @@
+## Creating charges with marketplace
+
+What if your web store contains products from many different sellers from many different segments? The user can complete a single purchase with products from more than one seller, right? Here enters marketplace.
+
+With some extra attributes, you can tell Gerencianet to pass on a percentage amount of the purchase total value to someone else.
+
+Create the input data:
+
+```ruby
+body = {
+  items: [{
+    name: "Product A",
+    value: 1000,
+    amount: 1,
+    marketplace: {
+        repasses: [{
+          payee_code: "GEZTAMJYHA3DAMBQGAYDAMRYGMZTGM",
+          percentage: 2500
+        },{
+          payee_code: "AKSLJI3DAMBQGSKLJDYDAMRTGOPWKS",
+          percentage: 2500
+        }]
+      }
+  }],
+  metadata: {
+    notification_url: "http://yourdomain.com"
+  }
+}
+```
+
+Create the charge:
+
+```ruby
+gerencianet.create_charge(body: body)
+```
+
+The attribute `payee_code` identifies a Gerencianet account, just like in [creating charges with shippings](https://github.com/gerencianet/gn-api-sdk-node/tree/master/docs/charge-with-shippings.md). In order to get someone else's `payee_code` you need to ask the account owner. There is no other way. To visualize yours, log in your Gerencianet account and search for *Identificador de Conta* under *Dados Cadastrais*.
+
+In the example above, there are two repasses, both of 25%, but each one for a different account, whereas the `payee_code` differs. The integrator account will receive, at the end, 50% of the total value. Disregarding the rates, the integrator account would receive R$5,00. The other two accounts would receive R$ 2,50 each.
+
+The response is the sames as usual:
+
+```ruby
+{
+  "code": 200,
+  "data": {
+    "charge_id": 254,
+    "total": 10000,
+    "status": "new",
+    "custom_id": null,
+    "created_at": "2015-05-18"
+  }
+}
+```

data/docs/charges.md

@@ -0,0 +1,94 @@
+## Creating charges
+
+Charges have one or more items. That's it.
+
+```ruby
+body = {
+  items: [{
+    name: "Product 1",
+    value: 1000,
+    amount: 2
+  }]
+}
+```
+
+
+### Adding shipping costs to a charge **(optional)**:
+
+In order to be the most agnostic as possible about how the user handles shippings, the API just receives an array with the values. You can add as many as you want. Sometimes you'll want a shipping cost to be received by another person/account. In this case, you must provide the `payee_code`. The *Additional Shipping* in the example below will be passed on to the referenced account after the payment.
+
+```ruby
+body = {
+  items: [{
+    name: "Product A",
+    value: 1000,
+    amount: 2
+  }],
+  shippings: [{
+    name: "Default Shipping",
+    value: 100
+  }, {
+    name: "Additional Shipping",
+    value: 120,
+    payee_code: "GEZTAMJYHA3DAMBQGAYDAMRYGMZTGMBRGI"
+  }]
+}
+```
+
+### Charge `metadata` attribute:
+
+```ruby
+body = {
+  items: [{
+    name: "Product A",
+    value: 1000,
+    amount: 2
+  }],
+  metadata: {
+    custom_id: "my_id",
+    notification_url: "http://yourdomain.com"
+  }
+}
+```
+
+The `notification_url` property will be used for sending notifications once things happen with charges statuses, as when it's payment was approved, for example. More about notifications [here](https://github.com/gerencianet/gn-api-sdk-node/tree/master/docs/notifications.md). The `custom_id` property can be used to set your own reference to the charge.
+
+## Post office service:
+
+If you want the charge to arrive at your house or at your client's house, you can count on Gerencianet's post office service. Just send an extra attribute:
+
+```ruby
+body = {
+  items: [{
+    name: "Product A",
+    value: 1000,
+    amount: 2
+  }],
+  post_office_service: {
+    send_to: "customer"
+  }
+}
+```
+
+If `send_to` is set to *customer*, the charge arrives at you customer's. If it is set to *seller*, just wait for it to arrive at your place. It's awesome!
+
+### Finally, create the charge:
+
+```ruby
+gerencianet.create_charge(body: body)
+```
+
+Check out the response:
+
+```ruby
+{
+  "code": 200,
+  "data": {
+    "charge_id": 1253,
+    "total": 2000,
+    "status": "new",
+    "custom_id": null,
+    "created_at": "2015-05-18 14:56:39"
+  }
+}
+```

data/docs/examples/.gitignore

@@ -0,0 +1 @@
+node_modules/

data/docs/examples/all_in_one.rb

@@ -0,0 +1,57 @@
+require "gerencianet"
+require_relative "./credentials"
+
+options = {
+  client_id: CREDENTIALS::CLIENT_ID,
+  client_secret: CREDENTIALS::CLIENT_SECRET,
+  sandbox: true
+}
+
+charge = {
+  items: [{
+    name: "Product 1",
+    value: 1000,
+    amount: 2
+  }],
+  shippings: [{
+    name: "Default Shipping Cost",
+    value: 100
+  }, {
+    name: "Adicional Shipping Cost",
+    value: 150
+  }]
+}
+
+payment = {
+  payment: {
+    credit_card: {
+      installments: 1,
+      payment_token: "88faabaa35f9d9ff29c315e03255c5644554a771",
+      billing_address: {
+        street: "Av. JK",
+        number: 909,
+        neighborhood: "Bauxita",
+        zipcode: "35400000",
+        city: "Ouro Preto",
+        state: "MG"
+      },
+      customer: {
+        name: "Gorbadoc Oldbuck",
+        email: "oldbuck@gerencianet.com.br",
+        cpf: "04267484171",
+        birth: "1977-01-15",
+        phone_number: "5144916523"
+      }
+    }
+  }
+}
+
+gerencianet = Gerencianet.new(options)
+
+charge = gerencianet.create_charge(body: charge)
+
+params = {
+  id: charge["data"]["charge_id"]
+}
+
+puts gerencianet.pay_charge(params: params, body: payment)