Custom Payments

As standard, Spektrix allows clients to take payments using several standard methods of payment: cash, card, Chip & PIN (for UK/ROI users), Account Credit, and – as long as they are enabled – Gift Vouchers. Many organisations accept payment by cheque, invoice, BACS payments or many other methods; these can be set up in Spektrix by creating Custom Payment Types. These methods of payment aren't processed within Spektrix – the client processes them elsewhere, but they need to let Spektrix know that they have taken the payment.

Find out more about Custom Payment Types and how the client you are working with can set this up for you. The client should set up a unique Custom Payment Type name for each partner product that processes sales.

Using Custom Payment Types for Partner Products

Many of our clients want to take advantage of the capabilities of Spektrix’s CRM functionality to fully understand their customers by connecting our platform to other systems and writing sales made in those systems into Spektrix.

We have an open approach to those who want to integrate with Spektrix, and welcome third parties to make use of our APIs which can send and receive data from other third party systems.

Any product that integrates with Spektrix and processes any type of sale (such as EPOS, donations, video streaming platforms) should use the Custom Payment Types API endpoints in order to create a record of the transaction of the type and value of the payment.

The following calls are made on System Owner mode, so they must be authenticated. If you attempt to make these calls in web/public mode you will get a 401 Unauthorized error.

Retrieving available Custom Payments

Using api/v3/custom-payment-types, you can pull a full list of all active custom payment types that are set in the Admin interface.

The response will include any custom attributes, set up by the clients, that are available and can be POSTed, for things such as reference numbers for financial reconciliation.

Request

GET

https://system.spektrix.com/{{clientname}}/api/v3/custom-payment-types

Response

[
    {
        "name": "EPOS System",
        "id": "93AGQTGJBKVCQVRRKBVCCRTPJTBKCNLBH",
        "isRefund": false,
        "attributeDefinitions": [
            {
                "name": "Reference",
                "isRequired": false,
                "type": "Text field"
            },
            {
                "name": "Receipt Number",
                "isRequired": false,
                "type": "Text field"
            }
        ]
    },
    {
        "name": "Quick Donation",
        "id": "7641ANMTGPDKSKCSGLJHMMLMMQCKCNQGP",
        "isRefund": false,
        "attributeDefinitions": [
            {
                "name": "Reference number",
                "isRequired": false,
                "type": "Text field"
            }
        ]
    }
]

Once you have found the relevant Custom Payment Type ID, you can use it to attach the Custom Payment Type to the transaction. A Custom Payment Id will never change once it has been set up, although they will vary per client. You may wish to therefore save Payment Type ID(s) as a per-client variable(s).

Adding Custom Payment to the transaction

The next step is to POST the Custom Payment information in order to balance the transaction with the correct custom payment.

Request

POST

https://system.spektrix.com/{{clientname}}/api/v3/baskets/{id}/custom-payments

Body

{
    "PaymentTypeId": "93AGQTGJBKVCQVRRKBVCCRTPJTBKCNLBH",
    "Amount": 10.40,
    "PaymentAttributes": [
        {
            "Name": "Payment ref",
            "Value": "ABC_123"
        }
    ]
}

Response

{
    "name": "EPOS System",
    "amount": 10.0,
    "attributes": [
        {
            "name": "Payment ref",
            "value": "ABC_123"
        }
    ]
}

The total of all custom payment Amount must balance the basket total, which you can retrieve the Basket Total with api/v3/basket.

The Name of PaymentAttributes must match the Name of AttributeDefinitions.

It is possible to waive the transaction commission by POSTing or PATCHing "WaiveTransactionCommission": true to baskets/{id} endpoint.