SEOshop Documentation

Create a payment service integration

You can now easily integrate your payment service with all Lightspeed eCom checkouts through a single unified endpoint. During the checkout process, we will call your API to fetch the available methods. No custom javascript or css is required.

See the example below, where a sample payment method SEOcoin is available in the checkout.

It is recommended that you inform the merchant about the use of personal data. The privacy policy should reflect the use of personal data.

Payment methods

Introduction

You'll start off by creating an ExternalService through the API. An External Service can either be a payment or a shipping integration. Send a POST request to the /external_services endpoint with the details of your service. Please note that the urlEndpoint will be the url that we'll make requests to, and this must be over HTTPS.

Some general tips:

  1. You can fetch all your current external_services after creation;
  2. If your service already exist, you can make a PUT call to change the current external service;
  3. You can delete current external services with a DELETE call: Webshop::instance()->external_services->delete(ID)

Now start a new checkout and go to the payment methods step. Notice that we call your {urlEndpoint}/payment_methods to fetch the available methods. See the Fetching payment methods chapter.

Arguments

NameValue
type

The type of external service, for example a payment service integration.

{"type": "shipment|payment"}
name

The name of the service. This will be shown to customers in the checkout process.

{"name": "SEOshop Payments"}
urlEndpoint

The url to your endpoint that we'll send requests to. For example we'll send a POST request to {urlEndpoint}/payment_methods. Please note that HTTPS is required.

{"urlEndpoint": "https://api.yourdomain.com/"}
isActive

Enable or disable the external service
(format: boolean)

{"isActive": "true|false"}
rateEstimate

Specify whether we may call your endpoint to fetch the shipping rates in the cart. Some webshops offer the possibility to fetch the shipping rates in the cart. Please note that for this request only the zipcode + country of the customer is available.

{"rateEstimate": "true|false"}
DefinitionPOST /external_services.json
Create a new externalService
Example Request
POST /external_services.json
{
	"externalService": {
		"type": "payment",
		"name": "SEOshop Payments",
		"urlEndpoint": "https://api.yourdomain.com/",
		"isActive": true
	}
}
Example Response
HTTP/1.1 201 Created
{
  "externalService": {
    "id": 1,
    "type": "payment",
    "name": "SEOshop Payments",
    "urlEndpoint": "https://api.yourdomain.com/",
    "isActive": true,
    "createdAt": "2015-05-13T10:45:29+02:00",
    "updatedAt": "2015-05-13T10:45:29+02:00"
  }
}

Fetching payment methods

We will call your endpoint url with a method name like shown below. This is a POST request with a payload that contains the most relevant information from the checkout process. The payload is always in a JSON format. In your response you return the available payment methods with their associated name and icon.

Arguments

NameValue
checkout_id

The unique identifier for the checkout process

{"checkout_id":1}
customer

Customer object

{
    "customer": {
        "gender": "male|female",
        "birthdate": "Y-m-d",
        "phone": "+31 (0) 20 820 23 91",
        "mobile": "0612345678",
        "national_id": "",
        "email": "info@seoshop.com",
        "password": "",
        "firstname": "Ruud",
        "middlename": "",
        "lastname": "Stelder",
        "type": "private|company",
        "company": "SEOshop Group Bv",
        "vatnumber": "NL10294830B01",
        "cocnumber": "1234567890",
        "sameaddress": true
    }
}
billing_address

Billing address object

{
    "billing_address": {
        "name": "Ruud Stelder",
        "address1": "Keizersgracht",
        "address2": "",
        "number": "313",
        "extension": "",
        "zipcode": "1016 EE",
        "city": "Amsterdam",
        "region": "Noord-Holland",
        "country": "nl"
    }
}
shipping_address

Shipping address object

{
    "shipping_address": {
        "name": "Ruud Stelder",
        "company": "SEOshop Group Bv",
        "address1": "Keizersgracht",
        "address2": "",
        "number": "313",
        "extension": "",
        "zipcode": "1016 EE",
        "city": "Amsterdam",
        "region": "Noord-Holland",
        "country": "nl"
    }
}
quote

Quote information like prices, taxes, and products

{
    "quote": {
        "id": 1,
        "price_incl": 65.84,
        "price_excl": 54.41,
        "additional_cost": true,
        "totals": {
            "sub_total": 54.41,
            "taxes": [
                {
                    "percentage": 0.21,
                    "amount": 11.7772
                }
            ],
            "grand_total": 65.84
        },
        "vat_shifted": false,
        "weight": 220,
        "volume": 400,
        "colli": 4,
        "products": [

        ],
        "created_at": "2015-04-15T12:06:17+02:00",
        "updated_at": "2015-04-15T12:07:11+02:00",
        "additional_cost_price_incl": 2,
        "additional_cost_price_excl": 1.6528
    }
}
DefinitionPOST {your_endpoint}/payment_methods
Create a new paymentService
Example Request
POST {your_endpoint}/payment_methods
{
	"rate_estimate": false,
	"shop": {
		"id": 1,
		"language": "nl",
		"currency": "eur"
	},
	"customer": {
		"firstname": "Menno",
		"middlename": "",
		"lastname": "Wolvers",
		"phone": "",
		"mobile": "",
		"type": "private",
		"company": false
	},
	"billing_address": {
		"name": "Menno Wolvers",
		"company": false,
		"address1": "Keizersgracht",
		"address2": "",
		"number": 313,
		"extension": "",
		"zipcode": "1016 EE",
		"city": "Amsterdam",
		"region": "",
		"country": "nl"
	},
	"shipping_address": {
		"name": "Menno Wolvers",
		"company": null,
		"address1": "Keizersgracht",
		"address2": "",
		"number": 313,
		"extension": "",
		"zipcode": "1016 EE",
		"city": "Amsterdam",
		"region": "",
		"country": "nl"
	},
	"quote": {
		"id": 1486,
		"price_incl": 55.43,
		"price_excl": 45.81,
		"vat_shifted": false,
		"weight": 165,
		"volume": 300,
		"colli": 3,
		"products": [{
			"product_id": 10546,
			"variant_id": 17706,
			"title": "Lamswollen sjaal",
			"fulltitle": "Lamswollen sjaal",
			"variant": "",
			"price_incl": 49.38,
			"price_excl": 40.81,
			"tax_rate": 0.21,
			"quantity": 3,
			"article_code": "",
			"ean": "",
			"sku": "AC0002",
			"size_x": 10,
			"size_y": 10,
			"size_z": 10,
			"weight": 55,
			"volume": 100,
			"colli": 1
		}]
	}
}
Example Response
HTTP/1.1 201 Created
{
  "payment_methods": [
    {
      "id": 1,
      "title": "Mastercard",
      "price_incl":6.05,
      "price_excl": 5.00,
      "tax_rate": 0.21,
      "icon": "mastercard"
    },
    {
      "id": 2,
      "title": "Visa",
      "price_incl":6.05,
      "price_excl": 5.00,
      "tax_rate": 0.21,
      "icon": "visa"
    },
    {
      "id": 3,
      "title": "Pay after delivery",
      "price_incl":6.05,
      "price_excl": 5.00,
      "tax_rate": 0.21,
      "icon": "https://yourdomain.com/icon-pay-after-delivery.png"
    }
  ]
}

Payment method object

Below you'll find all the available properties with which you can define a payment method.

Example object
{
  "id": 1,
  "title": "Mastercard",
  "price_incl":6.05,
  "price_excl": 5.00,
  "tax_rate": 0.21,
  "icon": "mastercard",
  "post_payment": false,
  "invoice_external": false,
  "data": {
    "uuid": "12345",
    "device": "Apple Watch"
  }
}

Properties

NameValue
id

A unique identifier for this payment method

{"id":1}
title

The name of the payment method that is shown to the customer

{"title": "Mastercard"}
price_incl

The price for this payment method including VAT, that will be added onto the total order value
(format: float)

{"price_incl":6.05}
price_excl

The price for this payment method excluding VAT, that will be added onto the total order value
(format: float)

{"price_excl":5}
tax_rate

The tax rate for this payment method, in precentages
(format: float)

{"tax_rate":0.21}
icon

The icon that is shown for this payment method, this could either be one of our supported icons or a HTTPS url to your unique icon (size is 50x32 in px)

{"icon": "mastercard"}
post_payment

Specifies whether the payment will be made after the package has been received by the customer
(format: boolean)

{"post_payment": "false|true"}
invoice_external

Specifies whether the invoicing of the customer will not go through SEOshop, we will not create an invoice if set to true
(format: boolean)

{"invoice_external": "false|true"}
data

Extra data attached to the payment method, this is not shown to the customer and may later be retrieved when the order has been finished

{
    "data": {
        "uuid": "12345",
        "device": "Apple Watch"
    }
}

Available icons

We support the following payment method icons:
acceptgiro, achterafbetalen, afterpay, alfabank, americanexpress, banktransfer, belfius, betaalnaontvangst, bitcoin, cartebleue, cash, clickandbuy, dankort, directdebit, directebanking, discover, dotpay, ebon, ecare, ecelv, elv, empayment, eps, eurocard, ewallet, fashioncheque, giftcard, giropay, ideal, incasso, invoice, ippies, klarna, maestro, mailru, mastercard, minitix, mistercash, multisafepay, nordea, notused, onlinegiro, onlinetransfer, paypal, paysafecard, phone, pickup, pin, postfinance, przelewy24, qiwi, refund, rembours, ukash, visa, visadebit, visaelectron, vpay, wallie, webmoney, webshopgiftcard, yourgift

Creating a payment

When the customer chooses to use one of your payment methods, we'll send you a POST after the checkout has been finalized. If you respond with a payment_url we'll send the customer to this url. After the customer has paid on your service, you simply redirect the user back to the redirect_url that we have passed in the previous POST request. When the customer returns, we'll send a GET request to your service to fetch the status of the payment.

Arguments

NameValue
order

Order object

{
    "order": {
        "id": 2996178,
        "number": "01918",
        "price_incl": 29.34,
        "price_excl": 25.12,
        "price_tax": 4.22,
        "currency": "eur"
    }
}
customer

Customer object

{
    "customer": {
        "gender": "male|female",
        "birthdate": "Y-m-d",
        "phone": "+31 (0) 20 820 23 91",
        "mobile": "0612345678",
        "national_id": "",
        "email": "info@seoshop.com",
        "password": "",
        "firstname": "Ruud",
        "middlename": "",
        "lastname": "Stelder",
        "type": "private|company",
        "company": "SEOshop Group Bv",
        "vatnumber": "NL10294830B01",
        "cocnumber": "1234567890",
        "sameaddress": true
    }
}
payment_method

Payment method object

{
    "payment_method": {
        "id": "my-awesome-app",
        "method": "pay-after-delivery",
        "title": "Pay After Delivery - MyAwesomeApp",
        "data": [

        ]
    }
}
redirect_url

The url you must redirect the user back to after he is finished on your service

{"redirect_url": "\"http://domain.webshopapp.com/nl/payment/my-awesome-app/success/?order_id={order_id}"}
webhook_url

Some payments to a while to process, for example a bank transfer. You may update the payment status using this webhook url.

{"webhook_url": "\"http://domain.webshopapp.com/nl/payment/my-awesome-app/notify/?order_id={order_id}"}
DefinitionPOST {your_endpoint}/payment
Create a new paymentService
Example Request
POST {your_endpoint}/payment
{
   "order":{
      "id":2996178,
      "number":"01918",
      "price_incl":29.3400,
      "price_excl":25.1200,
      "price_tax":4.2200,
      "currency":"eur"
   },
   "customer":{
      "id":103,
      "email":"info@seoshop.com",
      "gender":"male",
      "firstname":"Menno",
      "middlename":"",
      "lastname":"Wolvers",
      "fulllastname":"Wolvers",
      "fullname":"Menno Wolvers",
      "phone":"",
      "mobile":"",
      "birthdate":"685144800",
      "type":"private",
      "company":"SEOshop",
      "cocnumber":false,
      "vatnumber":false
   },
   "payment_method":{
      "id":"my-awesome-app",
      "method":"pay-after-delivery",
      "title":"Pay After Delivery - MyAwesomeApp",
      "data":{
         "gender":"male",
         "phone":"02012345678",
         "birthdate_d":"18",
         "birthdate_m":"9",
         "birthdate_y":"1991",
         "terms":"1",
         "method":"ideal",
         "birthdate":"1991-9-18",
         "app_id":"72"
      }
   },
   "redirect_url":"http://domain.webshopapp.com/nl/payment/my-awesome-app/success/?order_id=2996178",
   "webhook_url":"https://domain.webshopapp.com/nl/payment/my-awesome-app/notify/?order_id=2996178"
}
Example Response
HTTP/1.1 201 Created
{
  "payment_url": "http://yourdomain.com/pay/2996178"
}

Return the customer

After the payment has been processed on your service, you redirect the customer back to the redirect_url that we have provide you with in the POST /payment request. Now we'll send you a GET request to fetch the status of the payment.

Arguments

No arguments available.

DefinitionGET {your_endpoint}/payment/{order_id}
Get a list of all paymentServices of a shop.
Example Response
HTTP/1.1 200 OK
{
  "status": "paid|pending|expired|cancelled"
}

Cancel the payment

In some cases the payment was not successful or the customer simply wants to choose another payment method. In this case you also redirect the customer to the redirect_url. We will fetch the payment status from your API which will return cancelled. You can also return the status expired for when the user has not finished the payment in the timeframe that you have set, for example 15 minutes.

Arguments

No arguments available.

DefinitionGET {your_endpoint}/payment/{order_id}
Get a list of all paymentServices of a shop.
Example Response
HTTP/1.1 200 OK
{
  "status": "cancelled"
}

The payment is still being processed

Sometimes the payment will take a while to be processed, for example a bank transfer. In this case you are not sure of the payment was successful. You redirect the customer to the redirect_url, after which we will call your API to fetch the payment status. You return the status pending that'll tell us to send the customer to the "Thank you" page without a "payment was successful" message.

When you have processed the payment, for example a day later, you call the webhook_url. We will fetch the new status from your API and update the order accordingly. The payment status can be paid, expired or cancelled.

Arguments

No arguments available.

DefinitionGET {your_endpoint}/payment/{order_id}
Get a list of all paymentServices of a shop.
Example Response
HTTP/1.1 200 OK
{
  "status": "pending"
}
Was this article helpful? Yes No
One moment please
Thanks for your feedback.