Giter VIP home page Giter VIP logo

spree-emp-plugin's Introduction

emerchantpay Genesis Gateway for Spree

Gem Version Software License

Overview

This is a Payment Module for Spree eCommerce that gives you the ability to process payments through emerchantpay's Payment Gateway - Genesis.

Requirements

  • Spree Core 4.x (Tested up to 4.4.0)
  • Spree Backend 4.x (Tested up to 4.4.0)
  • Spree FrontEnd - Optional (Tested up to 4.4.0)
  • Ruby >= 2.7
  • Ruby on Rails >= 6.1.4
  • GenesisRuby v0.1.6
  • PCI-certified server in order to use emerchantpay Direct

Installation

Add this line to your application's Gemfile:

gem 'spree_emerchantpay_genesis'

And then execute:

bundle

Or install it yourself as:

gem install spree_emerchantpay_genesis

Copy & run migrations

bundle exec rails g spree_emerchantpay_genesis:install

Restart your server

Create Payment Method

  • Sign in to Spree Admin BackEnd
  • Navigate to Configurations -> Payment Methods -> New Payment Method
  • For Provider choose Spree::Gateway::EmerchantpayDirect or Spree:Gateway::EmerchantpayCheckout
  • Fill in Name, Description and Stores
  • Click Create

Usage

Configuration

  • Navigate to the Spree::Gateway::EmerchantpayDirect or Spree:Gateway::EmerchantpayCheckout payment method in the Configurations
  • Fill in Username, Password and Token
  • Fill in hostname used for the generation of the notification webhook. In most cases, the hostname should be the hostname of the Spree backend.
  • Fill in return_success_url and return_failure_url. Those endpoints will be returned to the create_payment response
    • If you add |:ORDER:| pattern in the URLs. The pattern will be replaced with the Spree Order Number

Spree Storefront API V2

  1. Create Cart
curl --request 'POST' \
  --url 'http://127.0.0.1:4000/api/v2/storefront/cart'

Response:

{
  "data":{
    "id":"59",
    "type":"cart",
    "attributes":{
      "number":"R702094375",
      ...
      "currency":"USD",
      "state":"cart",
      "token":"EsDjq1oXEgKI6kuujgfvFw1694531383712",
      ...
    },
    ...
  }
}
  1. Add Items
List Products
curl --request 'GET' \
  --url 'https://demo.spreecommerce.org/api/v2/storefront/products' \
  --header 'Accept: application/vnd.api+json'
curl --request 'POST' \
 --url 'http://localhost:4000/api/v2/storefront/cart/add_item' \
 --header 'Accept: application/vnd.api+json' \
 --header 'X-Spree-Order-Token: EsDjq1oXEgKI6kuujgfvFw1694531383712' \
 --header 'Content-Type: application/vnd.api+json' \
 --data '{
   "variant_id": "130",
   "quantity": "1"
 }'
  1. Add Shipping
List Shipping Rates
curl --request 'GET' \
  --url 'https://demo.spreecommerce.org/api/v2/storefront/checkout/shipping_rates' \
  --header 'Accept: application/vnd.api+json' \
  --header 'X-Spree-Order-Token: EsDjq1oXEgKI6kuujgfvFw1694531383712'
curl --request 'PATCH' \
 --url 'http://localhost:4000/api/v2/storefront/checkout/select_shipping_method' \
 --header 'Accept: application/vnd.api+json' \
 --header 'X-Spree-Order-Token:  EsDjq1oXEgKI6kuujgfvFw1694531383712' \
 --header 'Content-Type: application/vnd.api+json' \
 --data '{
   "shipping_method_id": "1"
 }'
  1. Update Order
curl --request 'PATCH' \
  --header 'Accept: application/vnd.api+json' \
  --header 'X-Spree-Order-Token: EsDjq1oXEgKI6kuujgfvFw1694531383712' \
  --header 'Content-Type: application/vnd.api+json' \
  --url 'http://localhost:4000/api/v2/storefront/checkout' \
  --data '{
  "order": {
    "email": "[email protected]",
    "bill_address_attributes": {
      "firstname": "John",
      "lastname": "Smith",
      "address1": "1 Area",
      "city": "Louisville",
      "phone": "01234567891",
      "zipcode": "40202",
      "country_iso": "US",
      "state_id": 500
    },
    "ship_address_attributes": {
      "firstname": "John",
      "lastname": "Smith",
      "address1": "1 Area",
      "city": "Louisville",
      "phone": "01234567891",
      "zipcode": "40202",
      "country_iso": "US",
      "state_id": 500
    },
    "payments_attributes":[
      {
        "payment_method_id":"5"
      }
    ]
  },
  "payment_source": {
    "5": {
      "name": "John Smith",
      "number": "4200000000000000",
      "month": 1,
      "year": 2040,
      "verification_value": "123",
      "cc_type": "visa"
    }
  }
}'

Create Payment

Create Direct Payment

CAUTION Create Payment endpoint will Complete the order! Call this endpoint in order to finish the order!

Accept Header, Java Enabled, Language, Color Depth, Screen height, Screen Width, Time Zone Offset, User Agent parameters must be retrieved from the customer browser. More info here.

curl --request 'POST' \
  --header 'Accept: application/vnd.api+json' \
  --header 'X-Spree-Order-Token: EsDjq1oXEgKI6kuujgfvFw1694531383712' \
  --header 'Content-Type: application/vnd.api+json' \
  --url 'http://localhost:4000/api/v2/storefront/checkout/create_payment' \
  --data '{
  "payment_method_id": "5",
  "source_attributes": {
    "name": "John Smith",
    "number": "4200000000000000",
    "month": 1,
    "year": 2040,
    "verification_value": "123",
    "cc_type": "visa",
    "accept_header": "*/*",
    "java_enabled": "true",
    "language": "en-GB",
    "color_depth": "32",
    "screen_height": "400",
    "screen_width": "400",
    "time_zone_offset": "+0",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36"
  }
}'

CAUTION If a redirect URL exists in the response object you MUST redirect the customer for payment completion. Check Response.

Create Checkout Payment

The Checkout Gateway doesn't require source_attributes by default (see p.4 Update Order). Upon Order Update or Payment Create the only required parameter is payment_method_id.

In some cases, the Gateway Web Payment Form may require Custom Attributes. Those attributes can be passed to the gateway via api/v2/storefront/checkout/create_payment. public_metadata contains a list with custom attributes where the key is the transaction type chosen on the payment method configuration inside the administration backend.

curl --request 'POST' \
  --header 'Accept: application/vnd.api+json' \
  --header 'X-Spree-Order-Token: EsDjq1oXEgKI6kuujgfvFw1694531383712' \
  --header 'Content-Type: application/vnd.api+json' \
  --url 'http://localhost:4000/api/v2/storefront/checkout/create_payment' \
  --data '{
  "payment_method_id": "8",
  "source_attributes": {
    "consumer_id":"123456",
    "consumer_email": "[email protected]",
    "public_metadata": {
      "sale3d": { "bin": "401200", "tail": "0085"},
      "trustly_sale": {"return_success_url_target": "top"}
    }
  }
}'

Full list with the available Custom Attributes for every Transaction Type can be found here.

The payment can be finished and a request to the Gateway will be sent with one of the Order Next or Complete endpoints.

  • Order complete:
curl --request 'PATCH' \
  --header 'Accept: application/vnd.api+json' \
  --header 'X-Spree-Order-Token: EsDjq1oXEgKI6kuujgfvFw1694531383712' \
  --header 'Content-Type: application/vnd.api+json' \
  --url 'http://localhost:4000/api/v2/storefront/checkout/complete'

In the JSON Response document you will find a redirect_url where the customer must be redirected for completing the payment. Check Response.

Response:

Create Payment response will contain emerchantpay_payment object. It will contain the current status of the payment. Redirect URL will give you the next step.

States:

  • error or declined - redirect URL will be the Failure URL filled in plugin settings
  • approved - redirect URL will be the Success URL filled in the plugin settings
  • pending_async - redirect URL will be the 3DSecure Method Continue endpoint for the next step of the payment
  • new - redirect URL will be the Web Payment Form URL where the customer must finish the payment
{
  "data": {
    "id": "XXX",
    "type": "cart",
    "attributes": {...},
    "relationships": {...},
    "emerchantpay_payment": {
      "state": "pending_async",
      "redirect_url": "<customer-redirect-url>"
    }
  }
}

Reference Actions

CAUTION the following transaction actions must be executed via Spree Admin backend:

  • Capture
  • Refund
  • Void

Supported Transactions

  • emerchantpay Direct Payment Method

    • Authorize
    • Authorize (3D-Secure)
    • Sale
    • Sale (3D-Secure)
  • emerchantpay Checkout Payment Method

    • Apple Pay
    • Argencard
    • Aura
    • Authorize
    • Authorize (3D-Secure)
    • Baloto
    • Bancomer
    • Bancontact
    • Banco de Occidente
    • Banco do Brasil
    • BitPay
    • Boleto
    • Bradesco
    • Cabal
    • CashU
    • Cencosud
    • Davivienda
    • Efecty
    • Elo
    • eps
    • eZeeWallet
    • Fashioncheque
    • GiroPay
    • Google Pay
    • iDeal
    • iDebit
    • InstaDebit
    • Intersolve
    • Itau
    • Klarna
    • Multibanco
    • MyBank
    • Naranja
    • Nativa
    • Neosurf
    • Neteller
    • Online Banking
    • OXXO
    • P24
    • Pago Facil
    • PayPal
    • PaySafeCard
    • PayU
    • Pix
    • POLi
    • Post Finance
    • PPRO
    • PSE
    • RapiPago
    • Redpagos
    • SafetyPay
    • Sale
    • Sale (3D-Secure)
    • Santander
    • Sepa Direct Debit
    • SOFORT
    • Tarjeta Shopping
    • TCS
    • Trustly
    • TrustPay
    • UPI
    • WebMoney
    • WebPay
    • WeChat

Note: If you have trouble with your credentials or terminal configuration, get in touch with our support team

Development

Running Specs

rake test

Running Linters

rake styles

Appraisals

Spree 4.4

bundle exec appraisal spree-4.4 rake test

Spree Master

bundle exec appraisal spree-master rake test

Configure

bundle exec appraisal install

Build Demo store

Requires Docker Engine

  1. Clone the project
  2. Create .env file in the project rood based on the .env.example
    • Set RAILS_ENV=production
  3. Execute inside project root:
    docker compose up
  4. Setup Web Server with reverse proxy configuration

Setup plugin for development

  1. Clone the project
  2. Create .env file based on the .env.example
    • Set RAILS_ENV=development
    • Set PLUGIN_SOURCE=/<local path to the plugin source>
  3. Execute inside project root:
    docker compose -f compose.yaml -f development-compose.yaml up -d
    • Optional you can set project name with the -p flag
    • You can attach to the container and debug with pry (docker attach <container>). Requires config.web_console.whitelisted_ips = '<host_ip>' inside the container (/mnt/spree/config/environments/development.rb)
    • If you expose the localhost (ex. ngrok) requires config.hosts.clear inside the container (/mnt/spree/config/environments/development.rb)

License

The gem is available as open source under the terms of the MIT License.

spree-emp-plugin's People

Contributors

dyd avatar emilpetkov avatar

Stargazers

Damian Legawiec avatar  avatar

Watchers

 avatar Chiranjib Roy avatar Dobromir Peev avatar Hristo Tanchev avatar PepaS avatar Йордан Пулов avatar Alex Salazar avatar  avatar Nikola Nikolov avatar Diganta Mandal avatar  avatar  avatar Plamen Petrov avatar  avatar Petyo avatar  avatar Ventsislav Dimitrov avatar  avatar

Forkers

damianlegawiec

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.