Easy invoicing and webshop ticketing quick steps

From Cyclos4 Wiki
Jump to: navigation, search

Introduction

Shops with their own external webshop (not a webshop in the Cyclos marketplace) who want to receive a payment in Cyclos, can use the Webshop ticketing module to offer payments in Cyclos to their customers. This can be compared with what PayPal or for example Stripe offers. This process is described below in detail and a php example is given. This integration is quite easy and straight forward, still it will cost a good programmer at least couple of hours to make this integration.


For webshops with less technical knowledge or for companies that send auto generated invoices by email, or non profit organizations that ask for a contribution there also is the Easy invoicing module in Cyclos. This allows Cyclos users to create a link with a payment directed to them, the url contains all the information needed for the payment. You can create such a link in seconds an put in on your website, email etc. An example of such a link is the url below: https://demo.cyclos.org/pay/?to=demo&amount=10


Finally also physical shops can use the tickets as a POS. First the shop has to generate the ticket in the Cyclos mobile app. Subsequently the customer can scan the QR with his mobile app to pay the shop. After the payment is made the shop will get an instant notification.


In all cases mentioned above the user has to enter their credentials to process the payment, or scan a QR code and do the payment with their mobile app. The difference between a ticket and easy invoicing is that easy invoicing can be used an unlimited amount of times, while a webshop ticket on the other hand can only be used once, and is created for a specific purchase, here the shop can also check with the ticket number if this payment has really been made.

Cyclos configuration

The Cyclos configuration is very simple. Login as admin in the system. Probably there are multiple products in the system. Some of these products give users permissions to have an account and do payments. Please open one of these products and select the fields:

  • Receive payments (tickets), here you can select for which transfer types a user can create a ticket. Thus if you select a transfer type here, the user can generate a QR code.
  • Make payments (tickets), here you can select for with which transfer types users can pay a ticket. Thus if you select a transfer type here, the user can pay a generated QR code.

In most cases in one product the same transfer type will be selected under both options described above.

After this, make sure the setting 'Show QR scan option at login page in mobile' is selected in the configuration that is bound to the URL the mobile app connects to.

POS ticket

The POS tickets work extremely simple. The screenshots below show this process. First the shop has to generate the ticket in the Cyclos mobile app. Subsequently the customer can scan the QR with his mobile app to pay the shop. After the payment is made the shop will get an instant notification.


Easy invoicing

The process contains only 2 simple steps. Please be aware this documentation is meant for administrators of Cyclos or people who are testing with the demo. Administrators should provide examples for their own users depending their configuration and the internal names they use.


Step 1: creating the link (shop)

In the first step the shop (or user that wishes to receive money) has to create the link. He just has to add his username, email address or account number (which is used depends on how the system is configured) to the url. Here are some examples (you can test these example by using the username demo2 and password 1234):


Step 2: doing the payment (customer)

After the link is generated it needs to be shared with the payer, this can be done by email, chat, showing it on a website, etc. It is also possible to already open the link and copy the QR code, so that people can scan this QR code to make the payment. When the payer opens the link, on the left side of the screen all information from the query string is shown. Only the username is not shown, this is only shown after the payer has logged in, so that people can't use this form to retrieve personal information about other users they are not supposed to see. Finally after logging in, the payer can fill in any additional payment fields (if they are configured in his system). And finally he can confirm the payment. If a confirmation password is needed (set in the web services channel) he will also need to fill this in to complete the payment.

Webshop ticketing

These instructions are meant for Cyclos 4.10 and above, if you are using Cyclos 4.8 or 4.9 please click here. The diagram below show the complete process of how a webshop can use a ticket to receive a payment in Cyclos.


Webshop ticketing flow


To summarize the main steps in the diagram above (how to implement each step is described in the paragraphs below):

  1. Once the order is ready to be paid, the webshop creates a ticket in Cyclos, indicating the order identifier, the payment amount and description and the webhook / success / cancel URLs;
  2. Then the webshop redirects the client to Cyclos, so he can approve the ticket with his credentials and password, or by using his mobile app. Once the ticket is approved, Cyclos will call the webhook / success URLs;
  3. Finally, either webhook / success service needs to process the ticket, which will effectively transfer the balance from the client to the webshop accounts. The success page (if any) then shows a confirmation message to the client.


Note: The webshop admin can also login manually to Cyclos to see a complete overview and history of all tickets and their status (in Banking - Payments - Tickets). This can be enabled with a permission. It is also possible to give the webshop permissions to cancel pending tickets from the Cyclos web interface.

Step 1: Create a Cyclos ticket

First the shop needs to create a ticket, this can be done through Cyclos API, which is described here: https://demo.cyclos.org/api/


This process can easily be tested, just go to https://demo.cyclos.org/api, go to Authorize and provide the user login data:

  • User: ticket
  • Password: 1234

Now scroll down and go to "Tickets" (click to open), click on item "POST /tickets". Click on the "Try it out" button. Click on edit to edit the request body and enter here the following JSON:

{
  "orderId": "1234567",
  "amount": "75",
  "description": "This is the description for this ticket. It might be a bit large, though.\nAnd it is...\nmultiline!!!",
  "successWebhook": "http://www.example.com/webhook",
  "successUrl": "http://www.example.com/success",
  "cancelUrl": "http://www.example.com/cancel"
}

Then scroll down a bit and click on the button "Execute".

This will post the JSON request to Cyclos and Cyclos will generate a ticket for the given amount, description and urls. Cyclos should respond with response code 201 (created). Now look at the response body here you can find the ticketNumber. Please copy the ticket number (do not copy the quotation marks)

Step 2: Forward the client to Cyclos for approving the ticket

The webshop sends the client to Cyclos, under /pay/ticketNumber. So, assuming that Cyclos is running in https://yourdomain.org, the URL to be used is https://yourdomain.org/pay/putTheTicketNumberHere.

When using full-page redirects the full browser page must be assigned to that URL. However, when using only webhooks, either a new browser window or an IFRAME should be used to show the ticket confirmation page. In this case, it would be desirable some sort of server push (such as Server-Sent events or WebSockets on the original page to notify the client once the payment is performed.

The customer can approve the ticket in 2 ways:

  • By logging-in with his credentials and approving the ticket. A page will be shown that the ticket was a approved and the client will be forwarded to the success URL, if any. When no success URL is used, Cyclos will inform the client that the browser window can be safely closed.
  • By logging in the mobile app > Payment > Scan QR / Barcode, and scan the barcode that is displayed on the payment page.


Following the previous example, you can test the ticket approval using the https://demo.cyclos.org/pay/ URL. For example if Cyclos replies with "ticketNumber": "pRFLs90xnOXdsgea3q9Fsbfil8egJkxG" then, in this example, open the following URL in your browser: https://demo.cyclos.org/pay/pRFLs90xnOXdsgea3q9Fsbfil8egJkxG.

In the demo example, login with the username demo and password 1234 and approve the ticket.

Step 3: Process the ticket in Cyclos

Cyclos will send both order identifier and ticket number as query parameters to the webhook (server to server) and / or via the success URL (client redirect). Those services must then process the ticket through the Cyclos API, which can be found here: https://demo.cyclos.org/ap > Tickets > POST ​/tickets​/{ticket}​/process. The webshop should pass back both ticket number and order identifier.

The operation result will be a JSON object which indicates if the payment was actually processed in this request and contains a reference to the transaction (payment) that was generated when the ticket was processed. The actuallyProcessed flag is very important - indicates whether the payment was actually processed in this request (true) or if it was previously processed by another request (false). The webshop shouldn't actually update any local order status if this flag is false, because that would mean that either both webhook / success URLs are being called, or that the request is being reattempted (possibly maliciously). Also, when both webhook and success URLs are used, Cyclos guarantees that only one is actually processed, never generating 2 payments for the ticket.

The other field in the operation result is transaction, which contains data about the performed payment. An important field contained in this object is transactionNumber, which is a unique identifier visible to users in the account history, which can be later used on the Cyclos main interface to lookup this specific payment if needed. A note for the Cyclos administrator: make sure transaction number is enabled in System > Currencies.


Again this process can easily be tested, just go to https://demo.cyclos.org/api, go to Authorize and provide the user login data:

  • User: ticket
  • Password: 1234

Now scroll down and go to "Tickets" (click to open), click on item "POST /tickets/{ticket}/process". Click on the "Try it out" button. In Parameters, set both ticket number (in the previous example, pRFLs90xnOXdsgea3q9Fsbfil8egJkxG) and the order identifier (in the previous example, 1234567). Then scroll down a bit and click on the button "Execute". If the result shows "actuallyProcessed": true," in the response body the payment has been executed.

Additional notes

  • The ticket can be looked up in the API, so, if needed, the status can be checked. See: https://demo.cyclos.org/api > Tickets > /viewTicket
  • Webshops are free to choose whether they want to integrate using webhooks and / or full-page redirects. Even when using full-page redirects, using webhooks can improve the process in 2 ways:
    • The webhook will probably arrive before the client redirect, as it is performed on the backend immediately, while the user is redirected after a few seconds. In that way, it is very likely that there will be no extra delay on the redirect page, making the process faster. The webshop can even first check the order, and if already paid not even call the Cyclos API;
    • Without a webhook, if the browser redirect fails after approval, no payment will be performed. Using a webhook adds extra confidence that the webshop won't loose sales because the redirect fails.
  • Receiving the order identifier on ticket creation and processing is optional. This is offered as a service to webshops, keeping the link between the local webshop order and the ticket number in Cyclos, which prevents an extra update in the local order once the ticket is created. Alternatively, the webshop can omit the order identifier on the ticket creation and manually store the ticket number. Then, on either webhook / success services, the webshop would need to find its local order using the Cyclos ticket and then check the local order status to make sure it is still pending payment, before attempting to process the ticket.

Customize layout

It is also possible to customized the style from within Cyclos using themes and static pages. This is very easy and will be sufficient for must users.

There are 2 static pages:

  • Menu: Content - Static content - Ticket confirmation page - Ticket / easy invoice confirmation page header details
  • Menu: Content - Static content - Ticket confirmation page - Ticket / easy invoice confirmation page footer details

Note: The header and footer are optional, they are not used in the online example.

The ticket and easy invoice theme can be found in: Menu: Content - Themes - (Chose New or edit) - Ticket confirmation theme
You can change the basic colors with color pickers (e.g. buttons, input text), and additionally make changes directly with CSS.

Other examples

Custom payment fields

If there are certain payment fields on a payment that need to be filled in by the webshop, then this is possible too, the following JSON can then be used: *

{
  "amount": "15",
  "description": "This is the description for this ticket. It might be a bit large, though.\nAnd it is...\nmultiline!!!",
  "customValues": {
    "invoice_nr": "123456789",
    "date": "2011-07-29T13:15:00Z"
  },
  "cancelUrl": "http://localhost/cancel",
  "successUrl": "http://localhost/success"
}

* All documentation can be found here: https://demo.cyclos.org/api > Tickets > POST ​/tickets

Php script

A php script example can be found here: https://documentation.cyclos.org/current/php-ticket-example.zip.