Skip to main content

Using Custom Parameters

Custom Parameters are a useful tool that helps to implement custom business workflows often in conjunction with an external CRM or other third-party tools. For example, they can be used to store a CRM contact identifier on a Subscription to then later map all Payments created through that Subscription back to the CRM contact.

Adding and updating Custom Parameters​

Merge behaviour when updating Custom Parameters​

The Supporter, Subscription, Payment and Payment Source APIs offer endpoints to manipulate their Custom Parameters. In update requests, a key with a null value will be removed from the stored data. All other keys will overwrite pre-existing keys with the new value. Other keys remain untouched.

Example:​

Given an object with following existing Custom Parameters:

{
  "my-key": "existing-value",
  "my-other-key": "will-remain-here",
  "yet-another-key": "will-be-removed"
}

And we send a request with:

{
  "custom_parameters": {
    "my-key": "new-value",
    "yet-another-key": null
  }
}

The resulting Custom Parameters:

{
  "my-key": "new-value",
  "my-other-key": "will-remain-here"
}

Supporters​

Creating a Supporter with Custom Parameters during the Payment process​

When using the Initialise Payment endpoint Custom Parameter for a Supporter can be specified in the custom_parameters object inside the supporter object.

Example request:

{
    "account_uuid": "c57bf7b0-2b23-4224-acb8-0fe168640552",
    "amount": {
        "value": 1000,
        "currency": "CHF"
    },
    "profile": "default",
    "locale": "de",
    "payment_method": "card",
    "payment_information": {},
    "return_url": "https://my.site.com/return",
    "test_mode": false,
    "supporter": {
        "first_name": "John",
        "last_name": "Smith",
        "custom_parameters": {
          "my-custom-parameter": "my-value"
        }
    }
}

The resulting Supporter will have a my-custom-parameter field with the value my-value.

Via the Supporter API​

When creating a new Supporter using the Create Supporter endpoint Custom Parameters can be specified in the custom_parameters object.

For existing Supporters Custom Parameters can be managed through the Update Supporter endpoint.

Subscriptions​

Creating a Subscription with Custom Parameters during the Payment process​

Subscriptions can be created during the Payment process using the Initialise Payment endpoint by using the custom_parameters object inside the subscription object.

Example request:

{
    "account_uuid": "c57bf7b0-2b23-4224-acb8-0fe168640552",
    "amount": {
        "value": 1000,
        "currency": "CHF"
    },
    "profile": "default",
    "locale": "de",
    "payment_method": "card",
    "payment_information": {},
    "return_url": "https://my.site.com/return",
    "test_mode": false,
    "subscription": {
        "interval": "monthly",
        "custom_parameters": {
          "my-custom-parameter": "my-value"
        }
    }
}

The resulting Subscription will have a my-custom-parameter field with the value my-value.

Via the Subscription API​

When creating a new Subscription using the Create Subscription endpoint Custom Parameters can be specified in the custom_parameters object.

For existing Subscriptions Custom Parameters can be managed through the Update Subscription endpoint.

Payments​

Custom Parameters of a Payment can be set when initialising a Payment using the Initialise Payment endpoint and later be managed through the Payments API.

Payment Sources​

Creating a Payment Source during the Payment process​

Payment Sources can be created during the Payment process with the Initialise Payment endpoint by setting the create_payment_source field to true. Payment Sources created this way will have the same Custom Parameters as the Payment itself.

Example request:

{
    "account_uuid": "c57bf7b0-2b23-4224-acb8-0fe168640552",
    "amount": {
        "value": 1000,
        "currency": "CHF"
    },
    "profile": "default",
    "locale": "de",
    "payment_method": "card",
    "payment_information": {},
    "return_url": "https://my.site.com/return",
    "test_mode": false,
    "create_payment_source": true,
    "custom_parameters": {
      "my-custom-parameter": "my-value"
    }
}

With this example both the Payment, and the Payment Source will have a my-custom-parameter field with the value my-value.

Via the Payment Source API​

When creating a Payment Source using the Create Payment Source endpoint Custom Parameters can be set in the custom_parameters object in the request.

Custom Parameters of existing Payment Sources can be managed with the Payment Source API.