Payactive API (2.0)

A valid API key is required to perform any request. You can manage the API keys for your account in the payactive portal (for Sandbox use this link).

Include your API key in the HTTP header api_key with every request.

⚠️ The API key must only be used in secure backend environments. Never expose your API key in public frontends (e.g. browser-based JavaScript, mobile apps, or publicly accessible client-side code). If exposed, the key must be considered compromised and rotated immediately.

Example

curl -X GET https://api.sandbox.payactive.app/payments \
  -H "api_key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

We offer separate environments for testing and production. Please find the information below:

Webhooks enable you to get notified about certain events. For example, we can send you a webhook in case a payment has been settled. You can manage your Webhooks in our Portal and subscribe to specific events that are important to you.

We will call your configured endpoint using HTTP POST. A connection error or an HTTP status code >= 400 will be interpreted as a failed webhook. In this case we will retry three times (exponentially increasing the delay between each try).

payment.initiated

A payment has been successfully initiated.

For type ONLINE_PAYMENT, this event is fired when the customer initiated an online bank transfer by logging into their bank account or when they initiated a manual transfer.

For type DIRECT_DEBIT, this event is fired when the direct debit was successfully submitted to your bank.

{
    "event_type": "payment.initiated",
    "event_time": "2022-05-23T12:12:05.735586Z",
    "event_data": {
        "amount": 47.6,
        "purpose": "Tagespass XL",
        "payment_id": "d6d8d863-d46c-4044-9ff3-68cd67142abd",
        "payment_method": "ONLINE_PAYMENT"
    },
    "metadata": {}
}

payment.settled

A payment has been successfully settled.

For type ONLINE_PAYMENT, this event is fired when the payment has been matched with a transaction on your account or if you manually verified the payment in the portal.

For type DIRECT_DEBIT, this event is fired when the requested funds were successfully credited to your account.

{
    "event_type": "payment.settled",
    "event_time": "2022-05-23T12:12:23.189114Z",
    "event_data": {
        "amount": 47.6,
        "purpose": "Tagespass XL",
        "payment_id": "d6d8d863-d46c-4044-9ff3-68cd67142abd",
        "payment_method": "ONLINE_PAYMENT"
    },
    "metadata": {}
}

checkout.initiated

A checkout has been initiated.

This event is fired when a customer successfully completed the checkout process but before the payment is settled.

{
    "event_type": "checkout.initiated",
    "event_time": "2022-05-23T12:11:23.337559Z",
    "event_data": {
      "checkout_custom_fields": [
        {
          "fieldIdentifier": "10f16330-73a3-470c-a8d9-45b771b5ecc9",
          "externalFieldIdentifier": null,
          "required": true,
          "fieldLabel": "Datum",
          "fieldType": "DATE",
          "fieldValue": "25.05.2022"
        }
      ],
      "checkout_id": "13a1ec76-6c6a-4df1-a943-00960831c3c8",
      "payment_id": "d6d8d863-d46c-4044-9ff3-68cd67142abd",
      "product_id": "fa17378e-47e6-442e-a0c0-c3c9e65d4ba6",
      "invoice_id": null,
      "product_name": "Tagespass XL"
    },
    "metadata": null
}

checkout.completed

A checkout has been completed.

This event is fired when the corresponding payment that is linked to the checkout was settled (see payment.settled).

{
    "event_type": "checkout.completed",
    "event_time": "2022-05-23T12:12:23.568858Z",
    "event_data": {
      "checkout_custom_fields": [
        {
          "fieldIdentifier": "10f16330-73a3-470c-a8d9-45b771b5ecc9",
          "externalFieldIdentifier": null,
          "required": true,
          "fieldLabel": "Datum",
          "fieldType": "DATE",
          "fieldValue": "25.05.2022"
        }
      ],
      "checkout_id": "13a1ec76-6c6a-4df1-a943-00960831c3c8",
      "payment_id": "d6d8d863-d46c-4044-9ff3-68cd67142abd",
      "product_id": "fa17378e-47e6-442e-a0c0-c3c9e65d4ba6",
      "invoice_id": null,
      "product_name": "Tagespass XL"
    },
    "metadata": null
}

All webhooks are signed. We encourage you to verify the signature. The signature will be sent in HTTP Header field x-payload-signature. You can find your shared secret on your personal webhook configuration page.

Example signed webhook call to your URL

POST /endpoint HTTP/1.1
Host: yourserver.com
Content-Type: application/json
x-payload-signature: 58bd36e9348d3f240ae517cbff675f992d378bc3d63b3abec0373dd504814cf4

{
"event_type": "payment.settled",
"event_time": "2022-05-16T09:49:59.429218Z",
"event_data": {
    "amount": 100,
    "purpose": "Test Test",
    "payment_id": "d3173567-6dc4-4eec-81fd-08aa4e11f20e",
    "payment_method": "ONLINE_PAYMENT"
},
"metadata": null
}

Validate Signatures In order to validate the signature you need to calculate a hash ( HMAC-SHA256 ) of the content and compare it with the value of x-payload-signature.

You need to calculate the hash value with the following parameters:

• Algorithm: HMAC-SHA256
• Payload: Entire payload (including whitespaces)
• Signing secret: Webhook signing secret which is unique for each configured Webhook. The signing secret can be found on your webhook configuration page.

Example

• Payload: Hello World!
• Signing secret: secret_password
• Calculated hash value: faeffaa195ee7b044d20f034b5cf7ed1309c9e1f043836a65227d55be6452af2

You can test this yourself using this online tool. There are examples for creating and verifying HmacSHA256 signatures for Java and NodeJS ( see crypto.createHmac(algorithm, key[, options])).

Please reach out to our support team if you have any more questions about this.

Endpoints for checkout management

Endpoints for credit management

Endpoints for credit note management

Endpoints for customer management

Endpoints for instalment plan management