Download the PHP package drsdre/laravel-hellocash without Composer

HelloCash for Laravel

This package provides an interface for the HelloCash API. It handles the Invoices, and Payments, as well as Webhooks.

Check out the documentation for more information: https://api-et.hellocash.net/docs/

Note: This project is not an official package, and I'm not affiliated with HelloCash in any way.

Table of Contents

• Setup
  • Installation
  • Service Provider
  • Configuration
• Handling Webhooks
  • Extend the controller
  • Define the route
  • Exclude from CSRF protection
• API Methods
  • Invoices
    • Validate an invoice
    • Create an invoice
    • Get the status of an invoice
    • Get a list of invoices
    • Remove an invoice
  • Transfers
    • Validate a new transfer
    • Create a new transfer
    • Replace a transfer
    • Get a list of transfers
    • Find a transfer by id
    • Cancel a transfer
    • Authorize transfers
  • Webhooks
    • Get an authorization code
• Exceptions
• Tests

Setup

Installation

Install the package through Composer.

This package requires Laravel 5.0 or higher, and uses Guzzle to make API calls. Use the appropriate version according to your dependencies.

Service Provider

This package supports auto-discovery for Laravel 5.5.

If you are using an older version, add the following service provider in your config/app.php.

Configuration

In config/hellocash.php the connection parameters are managed. It is recommended to use 'token' based authentication instead of 'credentials'.

The principal and system data you get from HelloCash. The 'token' you generate in the HelloCash portal in connection or through the 'connection' API endpoint.

Read more about API authentication in the documentation: https://api-et.hellocash.net/docs/#/Authenticate

Handling Webhooks

HelloCash supports Webhooks, and this package offers a controller which can be extended to handle incoming notification events. Make sure to set the 'HELLOCASH_WEBHOOK_SECRET' environment parameter. This can be generated in the HelloCash portal connection settings or through 'connection' API endpoint.

Read more about the Webhooks on the wiki: https://api-et.hellocash.net/docs/#/Connection

Extend the controller

You can make one controller to handle all the events, or make a controller for each event. Either way, your controllers must extend the drsdre\HelloCash\WebhookController. The webhook verification is handled automatically.

HelloCash send updates on transfers and invoices through the webhook. To handle those events, you controller must extend the handleEventNotification method.

Define the route

In your routes/web.php define the following route for the webhook you have in your profile, replacing the URI(s) and your controller(s) accordingly.

Exclude from CSRF protection

Don't forget to add your webhook URI(s) to the $except array on your VerifyCsrfToken middleware.

API Methods

Postman Collection

A Postman collection is available to test the calls. Make sure to setup an environment with the following keys:

• endpoint: https://api-et.hellocash.net
• principal: as provided to you
• credentials: as provided to you
• system: as provided to you

Invoices

Create or validate an invoice

See: https://api-et.hellocash.net/docs/#/Invoice

Get the status of an invoice

See: https://api-et.hellocash.net/docs/#!/Invoice/invoice_findByIdWrap

Search for invoices

See: https://api-et.hellocash.net/docs/#!/Invoice/invoice_findWrap

Remove an invoice

See: https://api-et.hellocash.net/docs/#!/Invoice/invoice_deleteById

Transfers

Create or validate a new transfer

See: https://api-et.hellocash.net/docs/#!/Transfer/transfer_create

Search for transfers

See: https://api-et.hellocash.net/docs/#!/Transfer/transfer_find

Get a transfer by ID

See: https://api-et.hellocash.net/docs/#!/Transfer/transfer_findByIdWrap

Cancel a transfer

See: https://api-et.hellocash.net/docs/#!/Transfer/transfer_cancel

Authorize a group of transfers

See: https://api-et.hellocash.net/docs/#!/Transfer/transfer_authorize

Webhooks

Setup an connection to your webhook URL

See: https://api-et.hellocash.net/docs/#!/Connection/connection_create

Exceptions

When the HelloCash API returns an error, a drsdre\HelloCash\HelloCashException is thrown.

For any other HTTP error a GuzzleHttp\Exception\ClientException is thrown.

Tests

Unit tests are triggered by running phpunit --group unit.

To run functional tests you have to include a .env file in the root folder, containing the credentials (HELLOCASH_PRINCIPAL, HELLOCASH_CREDENTIALS, HELLOCASH_SYSTEM), in order to hit the HelloCash staging API. Then run phpunit --group functional to trigger the tests.