Hackware Web Services Payment
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
/lib/sys 09afce860e LibreDTE.cl boletas gateway support.
Introduces a new kind of gateway, for receipts of payments.
2 weeks ago
config LibreDTE.cl boletas gateway support. 2 weeks ago
database/migrations LibreDTE.cl boletas gateway support. 2 weeks ago
public/img PayPal and DLocalGo payment gateways 9 months ago
routes LibreDTE.cl boletas gateway support. 2 weeks ago
src LibreDTE.cl boletas gateway support. 2 weeks ago
COPYING Add licensing information 4 years ago
README.md LibreDTE.cl boletas gateway support. 2 weeks ago
composer.json Use Brick/Money for Payment->amount. 9 months ago


Hackware Web Services Payment


Pay through various payment gateways.

Main goals

  • Web API with RESTful JSON responses.
  • Pay through offsite payment gateways.
  • Notify payment to custom HTTP service (such as the wallet API).


  • Multi-tenant, can be used with different configurations by origin.
  • As consumer I can perform a payment.
  • As consumer I can choose to pay with the Khipu, Flow, DLocalGo and PayPal payment gateways.
  • As system I can receive payment notifications from offsite payment gateways so that a payment is confirmed.
  • As system I can send a notification to a custom HTTP service so that a payment gets processed on that end.


  • GET /{origin}/gateways/ list of available gateways
  • GET /{origin}/gateways/payment-methods/{schema=purchase} list of all payment methods, incluiding gateway and property (which indicates the field that selects payment method remotely)
  • GET /{origin}/gateways/{gateway}/schemas/{schema=purchase} fields required for schema
  • POST /{origin}/gateways/{gateway}/purchase pay something
  • POST /{origin}/gateways/{gateway}/notify IPN
  • POST /{origin}/gateways/{gateway}/receipt/{paymentUuid} emit receipt for existing payment
  • POST /payments/{uuid} payment status

Standard payment provider properties on purchase schemas

Different payment providers will require you to send different parameters. In order to make its conversion a no-brainer for HTTP consumers, common fields have an standard name that will be translated to the proper property name for a specific provider, and set and as a readOnly default value when you request a purchase schema and send these as query params.

  • subject
  • email
  • amount
  • payment_method
  • currency

A request example:

GET /gateways/khipu/schemas/purchase?email=hello@example.org&amount=10000

> ...
> "properties": {
>   ...
>   "amount": {
>     "title": "Monto",
>     "type": "number",
>     "multipleOf": 1,
>     "default": 10000,
>     "readOnly": true
>   },
>   "payer_email": {
>     "title": "Email",
>     "type": "string",
>     "format": "idn-email",
>     "default": "hello@example.com",
>     "readOnly": true
>   },
>   ...

Additionally, you can always set a return_url query param parameter when you POST /gateways/{gateway}/purchase in order to dynamically set the url to return the user after he has paid or cancelled the payment (overriding config('payment.return_url'), a uuid query param will be appended to this url so you can verify its status. The reasoning for not including this field in the schema is because it's never a user-set field.



Configuration based

  • class: full class name (incluiding namespace) for this gateway.
  • payment_methods: payment methods property name for each schema, used to list available payment methods for all available gateways.
  • schemas: an associative array with valid JSON Schemas, each schema represents a form displayed to the final user containing data to send to the payment gateway (or exceptionally required by the processing payment method).


Database based

uuid, user_uid, gateway, currency, amount, description, detail, status


Configuration based, except gateway_credentials which is database based.

  • return_url
  • notify
  • gateway_credentials: id, origin_id, gateway_id, test_mode, api_key, secret_key
  • receipts

Run it



Require the package on a hawese based project.

composer require hackware/hawese-payment

Run migrations.

php artisan migrate

Insert credentials for each origin and gateway. You need to specify if those correspond to test_mode (development) or not (production).

php artisan payment:insert-credentials <origin> <gateway> <test_mode> <api_key> <secret_key>

Configure origins

This package will trigger a request to an external service automattically after reception of an Instant Payment Notification (IPN) from a payment gateway, take it as an external IPN which triggers an internal IPN (I think this is actually very handy :P).

It's configured to work with hackware/hawese-wallet by default, but it will work with any other endpoint if configured properly.

  1. After a proper installation of this package, move to the base hawese project.
  2. Append $app->configure('payment'); under Custom configuration on bootstrap/app.php.
  3. Copy the file vendor/hackware/hawese-payment/config/payment.php to config/payment.php.
  4. Append a proper config to the origin array, according to your origin's requirements.*
  5. Setup setup gateway credentials for that origin with php artisan payment:insert-credentials (get help with php artisan help payment:insert-credentials).

* Proper config example:

'example_org' => [
    'return_url' => 'https://example.org/checkout',
    'notify' => [
        'status' => ['completed', 'aborted'],
        'uri' => 'https://example.org/verify-payment',
        'headers' => [
            'Content-Type' => 'application/json',
            // or 'Content-Type' => 'application/x-www-form-urlencoded',
        'method' => 'POST',
        'params' => [
            'status' => 'payment.status',
            'uuid' => 'payment.uuid'
    'receipts' => [
        'libredteboleta' => [
            'Encabezado' => [
                'Emisor' => [
                    'RUTEmisor' => '11111111-1',
                    // 'CdgSIISucur' => '',

There's nothing cryptic about it. In the params associative array setup your endpoint input fields as keys and payment attributes with the format payment.payment_model_attribute.

Environment variables

  • DLOCALGO_COUNTRIES enabled countries list, separated by spaces.
  • PAYMENT_SOURCE_URL is the place where to download the source code of your version of this project. Required.
  • PAYMENT_WALLET_ENDPOINT endpoint to a running hackware/hawese-wallet instance for IPN.
  • PAYMENT_RETURN_URL where to return the payer after a successful or failed payment, an uuid query param will be appended to this URL, so you can call to the payments.verify route from that endpoint. hackware/userland is already prepared for that on the /add-funds/verify endpoint.
  • PAYMENT_CORE_AUTH_TOKEN system token in key:secret format. It's returned by the hackware/hawese composer run-script seed command, which runs the initial hackware/hawese-seeds.


If you want to create a custom gateway please contact me first for guidelines, otherwise your contribution might be rejected (and implementation will be harder to grasp).

Error codes

    1. UnexpectedResponseException: Unexpected HTTP response.
    1. UnexpectedValueException: Unsupported request method.
    1. LogicException: Exclusive to getBodyOrQueryParams, POST & GET parameters in the same request. Write this logic yourself.

Copyright 2019-2022 Hackware SpA.

This project is licensed under the GNU Affero General Public License v3 or any later version.

How to comply with license terms?

To comply with license terms you must provide the means to access the source code of your version of the software easily and free of charge to any person that has access to the software, even users which access through a network (i.e. web browser). I've provided an easy way to accomplish this requirement by setting the PAYMENT_SOURCE_URL environment variable, this will show the link on the index page (/) under the JSON links.payment_sourcecode property.

Any modification or inclusion of this source code will inherit the same license, that is, it can't be sublicensed. But since it's a REST API you can consume it with any other software. That means that this software must always respect users freedom, even if the HTTP API is consumed by a privative one.

Other licensing options

If you want to use the software but are afraid of or can't comply with the license terms we can arrange other license terms for your case. Though most probably I'll not accept if you don't provide your modifications to the software back.