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.