Webshop ticketing

Shops with their own external webshop (not a webshop in the Hudson Valley Current marketplace) who want to receive a payment in Currents, can use the Webshop ticketing module to offer payments in Currents 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.

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

Once the order is ready to be paid, the webshop creates a ticket in Cyclos HVC app, indicating the order identifier, the payment amount and description and the webhook / success / cancel URLs;
Then the webshop redirects the client to Cyclos HVC app, so he can approve the ticket with his credentials and password, or by using his mobile app. Once the ticket is approved, HVC app will call the webhook / success URLs;
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.

Step 1: Create a Cyclos ticket

First the shop needs to create a ticket, this can be done through Cyclos HVC app API, which is described here:

FOR TESTING: https://demo.cyclos.org/api

FOR PRODUCTION: https://app.hudsonvalleycurrent.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.\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 HVC app and the app will generate a ticket for the given amount, description and urls. Cyclos HVC app 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 HVC app, under /pay/ticketNumber. So, assuming that Cyclos HVC app 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 HVC app 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 HVC app 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

HVC app 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 HVC app API, which can be found here: https://app.hudsonvalleycurrent.org/api > 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, HVC app 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 HVC app main interface to lookup this specific payment if needed.

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 for testing or https://app.hudsonvalleycurrent.org/api for production > 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 HVC app 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 HVC app, 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 HVC app ticket and then check the local order status to make sure it is still pending payment, before attempting to process the ticket.

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.\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://app.hudsonvalleycurrent.org/api > Tickets > POST /tickets

Php script

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

Note: The HVC admins can also login manually to see a complete overview and history of all tickets and their status (in Banking - Payments - Tickets). They can also cancel pending tickets from the web interface.