Jens Schuppe
commit
b53befbb41
34 changed files with 411 additions and 165 deletions
184
README.md
184
README.md
|
|
@ -1,160 +1,42 @@
|
||||||
# Twingle API
|
# Twingle API
|
||||||
|
|
||||||
Extension to connect to the Twingle fundraising service via its API.
|
Twingle is a payment service provider that makes it possible to create donation
|
||||||
|
forms with various payment options and embed them on websites or integrate them
|
||||||
|
into your homepage. Interested parties can donate via known payment options (
|
||||||
|
e.g. credit card, PayPal). The procedure is also set up and optimised for mobile
|
||||||
|
devices. If you want to use the Twingle fundraising service, you have to set up
|
||||||
|
a corresponding online account.
|
||||||
|
|
||||||
* [About Twingle](https://www.twingle.de/)
|
For further information about Twingle fundraising
|
||||||
|
see the [Twingle website](https://www.twingle.de/).
|
||||||
|
|
||||||
The extension is licensed under
|
Twingle as fundraising service can be connected to CiviCRM via its API with the
|
||||||
[AGPL-3.0](https://github.com/systopia/de.systopia.twingle/blob/master/LICENSE.txt).
|
extension **Twingle API**.
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
* Donations from Twingle can be automatically created as contributions in
|
||||||
|
CiviCRM and assigned to existing or new contacts and administered in CiviCRM.
|
||||||
|
* Supporters and contacts of donations can be managed in CiviCRM.
|
||||||
|
* Donations can be submitted with different payment statuses depending on the
|
||||||
|
payment type
|
||||||
|
* SEPA mandates can be created for one-off and recurring payments.
|
||||||
|
* Donors can be added into groups for receiving newsletters, mailings and
|
||||||
|
donation receipts.
|
||||||
|
* A memberships can be set up for a donor.
|
||||||
|
* Data can be entered in user-defined fields
|
||||||
|
|
||||||
## Configuration
|
## Configuration
|
||||||
|
|
||||||
### Configure Twingle
|
Following the successful installation of the Twingle API extension, there is
|
||||||
|
some configuration work to do in order to set up the smooth connection between
|
||||||
|
CiviCRM and Twingle fundraising service.
|
||||||
|
|
||||||
Please refer to the
|
You have to carry out the following configuration steps:
|
||||||
[Twingle FAQ on using Twingle with CiviCRM](https://support.twingle.de/faq/de-de/9/46)
|
|
||||||
(currently only available in German).
|
|
||||||
|
|
||||||
### Configure Extended Contact Matcher (XCM)
|
* Creating a Twingle user and a user role in your CMS (Drupal, Wordpress, etc.)
|
||||||
|
* Configuring the *Extended Contact Matcher (XCM)* in CiviCRM
|
||||||
Make sure you use an XCM profile with the option *Match contacts by contact ID*
|
* Creating a Twingle User and an API key in CiviCRM
|
||||||
enabled.
|
* Activating the SEPA connection in CiviCRM (optional)
|
||||||
|
* Configuring the Twingle profile in CiviCRM
|
||||||
Be careful when enabling the *"Change Primary Detail?"* option. While it might
|
* Configuring your Twingle Account on the Twingle website
|
||||||
appear useful to update even primary contact details, this might lead to a
|
|
||||||
loss of contact information due to the fact that along with a submission that
|
|
||||||
contains e.g. a PayPal donation the `user_country` is transmitted as the only
|
|
||||||
address detail. The `user_country` then will be treated by the XCM as a whole
|
|
||||||
new address. So the contact may end up with a new address that contains only
|
|
||||||
the country.
|
|
||||||
|
|
||||||
### Configure CiviCRM
|
|
||||||
|
|
||||||
- Go to the Administration console at `/civicrm/admin`
|
|
||||||
- Open "Twingle API Configuration" at `/civicrm/admin/settings/twingle`
|
|
||||||
|
|
||||||
#### Configure CiviSEPA integration
|
|
||||||
|
|
||||||
Open "Configure extension settings" at
|
|
||||||
`/civicrm/admin/settings/twingle/settings` and configure whether to integrate
|
|
||||||
with the [CiviSEPA](https://github.com/project60/org.project60.sepa) extension.
|
|
||||||
|
|
||||||
This enables you to map incoming donations from Twingle with a specific payment
|
|
||||||
method (e.g. *debit_manual*) to be processed with CiviSEPA, that is, creating a
|
|
||||||
SEPA mandate and managing recurring payments.
|
|
||||||
|
|
||||||
#### Configure profiles
|
|
||||||
|
|
||||||
Open "Configure profiles" at `/civicrm/admin/settings/twingle/profiles`.
|
|
||||||
|
|
||||||
The *default* profile is used whenever the plugin cannot match the Twingle
|
|
||||||
project ID from any other profile. Therefore the default profile will be used
|
|
||||||
for all newly created Twingle projects.
|
|
||||||
|
|
||||||
| Label | Description |
|
|
||||||
|---------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
||||||
| Profile name | Internal name, used inside the extension. |
|
|
||||||
| Project IDs | Twingle project IDs. Separate multiple IDs with commas. |
|
|
||||||
| Location type | Specify how the address data sent by the form should be categorised in CiviCRM. The list is based on your CiviCRM configuration. |
|
|
||||||
| Location type for organisations | Specify how the address data sent by the form should be categorised in CiviCRM for organisational donations. The list is based on your CiviCRM configuration. |
|
|
||||||
| Financial type | Specify which financial type incoming one-time donations should be recorded with in CiviCRM. The list is based on your CiviCRM configuration. |
|
|
||||||
| Financial type (recurring) | Specify which financial type incoming recurring donations should be recorded with in CiviCRM. The list is based on your CiviCRM configuration. |
|
|
||||||
| CiviSEPA creditor | When enabled to integrate with CiviSEPA, specify the CiviSEPA creditor to use. |
|
|
||||||
| Gender options | Specify which CiviCRM gender option the incoming Twingle gender value should be mapped to. The list is based on your CiviCRM configuration. |
|
|
||||||
| Record *Payment method* as | Specifiy the payment methods mapping for incoming donations for each Twingle payment method. |
|
|
||||||
| Double Opt-In | Let CiviCRM handle the double opt-in. Group memberships for newsletter mailing lists stay pending until the subscription gets confirmed. Note that this only works for public mailing lists. Any non-public mailing list will be ignored. Do not forget to disable Twingle's double opt-in option in the Twingle Manager. |
|
|
||||||
| Sign up for groups | Whenever the donor checked the newsletter/postal mailing/donation receipt checkbox on the Twingle form, the contact will be added to the groups listed here. |
|
|
||||||
| Assign donation to campaign | The donation will be assigned to the selected campaign. If a campaign ID is being submitted using the `campaign_id` parameter, this setting will be overridden with the submitted value. |
|
|
||||||
| Create membership of type | A membership of the selected type will be created for the Individual contact for incoming one-time donations. If no membership type is selected, no membership will be created. |
|
|
||||||
| Create membership of type (recurring) | A membership of the selected type will be created for the Individual contact for incoming recurring donations. If no membership type is selected, no membership will be created. |
|
|
||||||
| Contribution source | The configured value will be set as the "Source" field for the contribution. |
|
|
||||||
| Custom field mapping | Additional field values may be set to CiviCRM custom fields using a mapping. See the option's help text for the exact format. |
|
|
||||||
|
|
||||||
|
|
||||||
## API documentation
|
|
||||||
|
|
||||||
The extension provides a new CiviCRM API entity `TwingleDonation` with API
|
|
||||||
actions to record a new donation, end a previously submitted recurring donation
|
|
||||||
and cancel previously submitted donation.
|
|
||||||
|
|
||||||
### Submit donation
|
|
||||||
|
|
||||||
This API action processes submitted Twingle donations and donor information.
|
|
||||||
|
|
||||||
- Entity: `TwingleDonation`
|
|
||||||
- Action: `Submit`
|
|
||||||
|
|
||||||
The action accepts the following parameters:
|
|
||||||
|
|
||||||
| Parameter | Type | Description | Values/Format | Required |
|
|
||||||
|----------------------------------------|---------|-------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------|
|
|
||||||
| <nobr>`project_id`</nobr> | String | The Twingle project ID | | Yes |
|
|
||||||
| <nobr>`trx_id`</nobr> | String | The unique transaction ID of the donation | A unique transaction ID for the donation. | Yes |
|
|
||||||
| <nobr>`confirmed_at`</nobr> | String | The date when the donation was issued | A string representing a date in the format `YmdHis` | Yes |
|
|
||||||
| <nobr>`purpose`</nobr> | String | The purpose of the donation | | |
|
|
||||||
| <nobr>`amount`</nobr> | Integer | The donation amount in minor currency unit | | Yes |
|
|
||||||
| <nobr>`currency`</nobr> | String | The ISO-4217 currency code of the donation | A valid ISO-4217 currency code | Yes |
|
|
||||||
| <nobr>`newsletter`</nobr> | Boolean | Whether to subscribe the contact to the newsletter group defined in the profile | | |
|
|
||||||
| <nobr>`postinfo`</nobr> | Boolean | Whether to subscribe the contact to the postal mailing group defined in the profile | | |
|
|
||||||
| <nobr>`donation_receipt`</nobr> | Boolean | Whether the contact requested a donation receipt | | |
|
|
||||||
| <nobr>`payment_method`</nobr> | String | The Twingle payment method used for the donation | One of:<br /><ul><li><nobr>`banktransfer`</nobr></li><li><nobr>`debit_manual`</nobr></li><li><nobr>`debit_automatic`</nobr></li><li><nobr>`creditcard`</nobr></li><li><nobr>`mobilephone_germany`</nobr></li><li><nobr>`paypal`</nobr></li><li><nobr>`sofortueberweisung`</nobr></li><li><nobr>`amazonpay`</nobr></li><li><nobr>`paydirekt`</nobr></li><li><nobr>`applepay`</nobr></li><li><nobr>`googlepay`</nobr></li></ul> | Yes |
|
|
||||||
| <nobr>`donation_rhythm`</nobr> | String | The interval which the donation is recurring in | One of:<br /><ul><li><nobr>`'one_time',`</nobr></li><li><nobr>`'halfyearly',`</nobr></li><li><nobr>`'quarterly',`</nobr></li><li><nobr>`'yearly',`</nobr></li><li><nobr>`'monthly'`</nobr></li></ul> | Yes |
|
|
||||||
| <nobr>`debit_iban`</nobr> | String | The IBAN for SEPA Direct Debit payments | A valid ISO 13616-1:2007 IBAN | Yes, if `payment_method` is `debit_manual` and CiviSEPA is used |
|
|
||||||
| <nobr>`debit_bic`</nobr> | String | The BIC for SEPA Direct Debit payments | A valid ISO 9362 BIC | Yes, if `payment_method` is `debit_manual` and CiviSEPA is used |
|
|
||||||
| <nobr>`debit_mandate_reference`</nobr> | String | The mandate reference for SEPA Direct Debit payments | | |
|
|
||||||
| <nobr>`debit_account_holder`</nobr> | String | The account holder for SEPA Direct Debit payments | | |
|
|
||||||
| <nobr>`is_anonymous`</nobr> | Boolean | Whether the donation is submitted anonymously | | |
|
|
||||||
| <nobr>`user_gender`</nobr> | String | The gender of the contact | | |
|
|
||||||
| <nobr>`user_birthdate`</nobr> | String | The date of birth of the contact | A string representing a date in the format `Ymd` | |
|
|
||||||
| <nobr>`user_title`</nobr> | String | The formal title of the contact | | |
|
|
||||||
| <nobr>`user_email`</nobr> | String | The e-mail address of the contact | A valid e-mail address | |
|
|
||||||
| <nobr>`user_firstname`</nobr> | String | The first name of the contact | | |
|
|
||||||
| <nobr>`user_lastname`</nobr> | String | The last name of the contact | | |
|
|
||||||
| <nobr>`user_street`</nobr> | String | The street address of the contact | | |
|
|
||||||
| <nobr>`user_postal_code`</nobr> | String | The postal code of the contact | | |
|
|
||||||
| <nobr>`user_city`</nobr> | String | The city of the contact | | |
|
|
||||||
| <nobr>`user_country`</nobr> | String | The country of the contact | A [ISO 3166-1 Alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) | |
|
|
||||||
| <nobr>`user_telephone`</nobr> | String | The telephone number of the contact | | |
|
|
||||||
| <nobr>`user_company`</nobr> | String | The company of the contact | | |
|
|
||||||
| <nobr>`user_extrafield`</nobr> | String | Additional information of the contact | | |
|
|
||||||
| <nobr>`user_language`</nobr> | String | The preferred language of the contact. | A [ISO-639-1 2-digit language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) | |
|
|
||||||
| <nobr>`campaign_id`</nobr> | Integer | The CiviCRM ID of a campaign to assign the contribution | A valid CiviCRM Campaign ID. This overrides the campaign ID configured within the profile. | |
|
|
||||||
|
|
||||||
You may also refer to
|
|
||||||
[the code](https://github.com/systopia/de.systopia.twingle/blob/master/api/v3/TwingleDonation/Submit.php)
|
|
||||||
for more insight into this API action.
|
|
||||||
|
|
||||||
### End recurring donation
|
|
||||||
|
|
||||||
- Entity: `TwingleDonation`
|
|
||||||
- Action: `Endrecurring`
|
|
||||||
|
|
||||||
The action accepts the following parameters:
|
|
||||||
|
|
||||||
| Parameter | Type | Description | Values/Format | Required |
|
|
||||||
|---------------------------|---------|------------------------------------------------|-------------------------------------------------------|----------|
|
|
||||||
| <nobr>`project_id`</nobr> | String | The Twingle project ID | | Yes |
|
|
||||||
| <nobr>`trx_id`</nobr> | String | The unique transaction ID of the donation | A unique transaction ID for the donation. | Yes |
|
|
||||||
| <nobr>`ended_at`</nobr> | Integer | The date when the recurring donation was ended | A string representing a date in the format `YmdHis` | Yes |
|
|
||||||
|
|
||||||
You may also refer to
|
|
||||||
[the code](https://github.com/systopia/de.systopia.twingle/blob/master/api/v3/TwingleDonation/Endrecurring.php)
|
|
||||||
for more insight into this API action.
|
|
||||||
|
|
||||||
### Cancel donation
|
|
||||||
|
|
||||||
- Entity: `TwingleDonation`
|
|
||||||
- Action: `Cancel`
|
|
||||||
|
|
||||||
The action accepts the following parameters:
|
|
||||||
|
|
||||||
| Parameter | Type | Description | Values/Format | Required |
|
|
||||||
|------------------------------|--------|----------------------------------------------------|-------------------------------------------------------|----------|
|
|
||||||
| <nobr>`project_id`</nobr> | String | The Twingle project ID | | Yes |
|
|
||||||
| <nobr>`trx_id`</nobr> | String | The unique transaction ID of the donation | A unique transaction ID for the donation. | Yes |
|
|
||||||
| <nobr>`cancelled_at`</nobr> | String | The date when the recurring donation was cancelled | A string representing a date in the format `YmdHis` | Yes |
|
|
||||||
| <nobr>`cancel_reason`</nobr> | String | The reason for the donation being cancelled | | Yes |
|
|
||||||
|
|
||||||
You may also refer to
|
|
||||||
[the code](https://github.com/systopia/de.systopia.twingle/blob/master/api/v3/TwingleDonation/Cancel.php)
|
|
||||||
for more insight into this API action.
|
|
||||||
|
|
|
||||||
87
docs/api.md
Normal file
87
docs/api.md
Normal file
|
|
@ -0,0 +1,87 @@
|
||||||
|
# API documentation
|
||||||
|
|
||||||
|
The extension provides a new CiviCRM API 3 entity `TwingleDonation` with API
|
||||||
|
actions to record a new donation, end a previously submitted recurring donation
|
||||||
|
and cancel previously submitted donation.
|
||||||
|
|
||||||
|
### Submit donation
|
||||||
|
|
||||||
|
This API action processes submitted Twingle donations and donor information.
|
||||||
|
|
||||||
|
- Entity: `TwingleDonation`
|
||||||
|
- Action: `Submit`
|
||||||
|
|
||||||
|
The action accepts the following parameters:
|
||||||
|
|
||||||
|
| Parameter | Type | Description | Values/Format | Required |
|
||||||
|
| -------------------------------------- | ------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
|
||||||
|
| <nobr>`project_id`</nobr> | String | The Twingle project ID | | Yes |
|
||||||
|
| <nobr>`trx_id`</nobr> | String | The unique transaction ID of the donation | A unique transaction ID for the donation. | Yes |
|
||||||
|
| <nobr>`confirmed_at`</nobr> | String | The date when the donation was issued | A string representing a date in the format `YmdHis` | Yes |
|
||||||
|
| <nobr>`purpose`</nobr> | String | The purpose of the donation | | |
|
||||||
|
| <nobr>`amount`</nobr> | Integer | The donation amount in minor currency unit | | Yes |
|
||||||
|
| <nobr>`currency`</nobr> | String | The ISO-4217 currency code of the donation | A valid ISO-4217 currency code | Yes |
|
||||||
|
| <nobr>`newsletter`</nobr> | Boolean | Whether to subscribe the contact to the newsletter group defined in the profile | | |
|
||||||
|
| <nobr>`postinfo`</nobr> | Boolean | Whether to subscribe the contact to the postal mailing group defined in the profile | | |
|
||||||
|
| <nobr>`donation_receipt`</nobr> | Boolean | Whether the contact requested a donation receipt | | |
|
||||||
|
| <nobr>`payment_method`</nobr> | String | The Twingle payment method used for the donation | One of:<br /><ul><li><nobr>`banktransfer`</nobr></li><li><nobr>`debit_manual`</nobr></li><li><nobr>`debit_automatic`</nobr></li><li><nobr>`creditcard`</nobr></li><li><nobr>`mobilephone_germany`</nobr></li><li><nobr>`paypal`</nobr></li><li><nobr>`sofortueberweisung`</nobr></li><li><nobr>`amazonpay`</nobr></li><li><nobr>`paydirekt`</nobr></li><li><nobr>`applepay`</nobr></li><li><nobr>`googlepay`</nobr></li></ul> | Yes |
|
||||||
|
| <nobr>`donation_rhythm`</nobr> | String | The interval which the donation is recurring in | One of:<br /><ul><li><nobr>`'one_time',`</nobr></li><li><nobr>`'halfyearly',`</nobr></li><li><nobr>`'quarterly',`</nobr></li><li><nobr>`'yearly',`</nobr></li><li><nobr>`'monthly'`</nobr></li></ul> | Yes |
|
||||||
|
| <nobr>`debit_iban`</nobr> | String | The IBAN for SEPA Direct Debit payments | A valid ISO 13616-1:2007 IBAN | Yes, if `payment_method` is `debit_manual` and CiviSEPA is used |
|
||||||
|
| <nobr>`debit_bic`</nobr> | String | The BIC for SEPA Direct Debit payments | A valid ISO 9362 BIC | Yes, if `payment_method` is `debit_manual` and CiviSEPA is used |
|
||||||
|
| <nobr>`debit_mandate_reference`</nobr> | String | The mandate reference for SEPA Direct Debit payments | | |
|
||||||
|
| <nobr>`debit_account_holder`</nobr> | String | The account holder for SEPA Direct Debit payments | | |
|
||||||
|
| <nobr>`is_anonymous`</nobr> | Boolean | Whether the donation is submitted anonymously | | |
|
||||||
|
| <nobr>`user_gender`</nobr> | String | The gender of the contact | | |
|
||||||
|
| <nobr>`user_birthdate`</nobr> | String | The date of birth of the contact | A string representing a date in the format `Ymd` | |
|
||||||
|
| <nobr>`user_title`</nobr> | String | The formal title of the contact | | |
|
||||||
|
| <nobr>`user_email`</nobr> | String | The e-mail address of the contact | A valid e-mail address | |
|
||||||
|
| <nobr>`user_firstname`</nobr> | String | The first name of the contact | | |
|
||||||
|
| <nobr>`user_lastname`</nobr> | String | The last name of the contact | | |
|
||||||
|
| <nobr>`user_street`</nobr> | String | The street address of the contact | | |
|
||||||
|
| <nobr>`user_postal_code`</nobr> | String | The postal code of the contact | | |
|
||||||
|
| <nobr>`user_city`</nobr> | String | The city of the contact | | |
|
||||||
|
| <nobr>`user_country`</nobr> | String | The country of the contact | A [ISO 3166-1 Alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) | |
|
||||||
|
| <nobr>`user_telephone`</nobr> | String | The telephone number of the contact | | |
|
||||||
|
| <nobr>`user_company`</nobr> | String | The company of the contact | | |
|
||||||
|
| <nobr>`user_extrafield`</nobr> | String | Additional information of the contact | | |
|
||||||
|
| <nobr>`user_language`</nobr> | String | The preferred language of the contact. | A [ISO-639-1 2-digit language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) | |
|
||||||
|
| <nobr>`campaign_id`</nobr> | Integer | The CiviCRM ID of a campaign to assign the contribution | A valid CiviCRM Campaign ID. This overrides the campaign ID configured within the profile. | |
|
||||||
|
|
||||||
|
You may also refer to
|
||||||
|
[the code](https://github.com/systopia/de.systopia.twingle/blob/master/api/v3/TwingleDonation/Submit.php)
|
||||||
|
for more insight into this API action.
|
||||||
|
|
||||||
|
### End recurring donation
|
||||||
|
|
||||||
|
- Entity: `TwingleDonation`
|
||||||
|
- Action: `Endrecurring`
|
||||||
|
|
||||||
|
The action accepts the following parameters:
|
||||||
|
|
||||||
|
| Parameter | Type | Description | Values/Format | Required |
|
||||||
|
| ------------------------- | ------- | ---------------------------------------------- | --------------------------------------------------- | -------- |
|
||||||
|
| <nobr>`project_id`</nobr> | String | The Twingle project ID | | Yes |
|
||||||
|
| <nobr>`trx_id`</nobr> | String | The unique transaction ID of the donation | A unique transaction ID for the donation. | Yes |
|
||||||
|
| <nobr>`ended_at`</nobr> | Integer | The date when the recurring donation was ended | A string representing a date in the format `YmdHis` | Yes |
|
||||||
|
|
||||||
|
You may also refer to
|
||||||
|
[the code](https://github.com/systopia/de.systopia.twingle/blob/master/api/v3/TwingleDonation/Endrecurring.php)
|
||||||
|
for more insight into this API action.
|
||||||
|
|
||||||
|
### Cancel donation
|
||||||
|
|
||||||
|
- Entity: `TwingleDonation`
|
||||||
|
- Action: `Cancel`
|
||||||
|
|
||||||
|
The action accepts the following parameters:
|
||||||
|
|
||||||
|
| Parameter | Type | Description | Values/Format | Required |
|
||||||
|
| ---------------------------- | ------ | -------------------------------------------------- | --------------------------------------------------- | -------- |
|
||||||
|
| <nobr>`project_id`</nobr> | String | The Twingle project ID | | Yes |
|
||||||
|
| <nobr>`trx_id`</nobr> | String | The unique transaction ID of the donation | A unique transaction ID for the donation. | Yes |
|
||||||
|
| <nobr>`cancelled_at`</nobr> | String | The date when the recurring donation was cancelled | A string representing a date in the format `YmdHis` | Yes |
|
||||||
|
| <nobr>`cancel_reason`</nobr> | String | The reason for the donation being cancelled | | Yes |
|
||||||
|
|
||||||
|
You may also refer to
|
||||||
|
[the code](https://github.com/systopia/de.systopia.twingle/blob/master/api/v3/TwingleDonation/Cancel.php)
|
||||||
|
for more insight into this API action.
|
||||||
27
docs/configuration/account.md
Normal file
27
docs/configuration/account.md
Normal file
|
|
@ -0,0 +1,27 @@
|
||||||
|
# Twingle account settings on the Twingle website
|
||||||
|
|
||||||
|
The use of the Twingle API extension requires that you already have a Twingle
|
||||||
|
account and that you make some settings in this account for the connection.
|
||||||
|
|
||||||
|
You will have to provide the following settings in your Twingle account settings
|
||||||
|
in order to send donations to CiviCRM:
|
||||||
|
|
||||||
|
1. API key from your Twingle user
|
||||||
|
2. Site key
|
||||||
|
3. URL
|
||||||
|
|
||||||
|
Important: The URL must always be the complete URL to the CiviCRM REST API
|
||||||
|
endpoint.
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
- Drupal (with the *AuthX* extension): https://example.org/civicrm/ajax/rest
|
||||||
|
- Drupal (legacy
|
||||||
|
method): https://example.org/sites/all/modules/civicrm/extern/rest.php
|
||||||
|
- Wordpress (with CiviCRM <
|
||||||
|
5.25): https://example.org/wp-content/plugins/civicrm/civicrm/extern/rest.php
|
||||||
|
- Wordpress (with CiviCRM
|
||||||
|
5.25+): https://example.org/wp-json/civicrm/v3/rest
|
||||||
|
|
||||||
|
For detailled information, please see
|
||||||
|
the [Twingle documentation](https://support.twingle.de/faq/de-de/9-anbindung-externer-systeme/46-wie-kann-ich-civicrm-mit-twingle-nutzen) (
|
||||||
|
in German language only).
|
||||||
32
docs/configuration/civisepa.md
Normal file
32
docs/configuration/civisepa.md
Normal file
|
|
@ -0,0 +1,32 @@
|
||||||
|
# Activating CiviSEPA integration
|
||||||
|
|
||||||
|
The Twingle API extension provides integration with the [
|
||||||
|
*CiviSEPA*](https://civicrm.org/extensions/civisepa-sepa-direct-debit-extension)
|
||||||
|
extension. This allows for managing SEPA mandates and collections with
|
||||||
|
*CiviSEPA* for donations being initiated via a *Twingle* form.
|
||||||
|
|
||||||
|
1. In CiviCRM, go to **Administer**.
|
||||||
|
2. Choose **Twingle API configuration**.
|
||||||
|
|
||||||
|
|
||||||
|
3. Then click on **Configure extension settings**.
|
||||||
|
|
||||||
|
|
||||||
|
4. Tick the boxes **Use CiviSEPA** and **Use CiviSEPA generated reference**.
|
||||||
|
These options can only be activated if CiviSEPA is installed and used. If it
|
||||||
|
is not activated, the administration of SEPA mandates will have to take place
|
||||||
|
in Twingle, which is subject to configuration of your available payment
|
||||||
|
methods.
|
||||||
|
5. Write **TW-** in the **Twingle ID Prefix** field.
|
||||||
|
To avoid overlaps when assigning CiviCRM IDs and Twingle transaction IDs, a
|
||||||
|
prefix should be assigned here, e.g. "TWNGL" or "Twingle" or similar.
|
||||||
|
Attention: The prefix should not be changed later, otherwise problems may
|
||||||
|
occur.
|
||||||
|
6. In the **Protect Recurring Contributions** field select **No**.
|
||||||
|
If you choose Yes, all recurring donations created by Twingle can no longer
|
||||||
|
be changed in CiviCRM, but must then be changed accordingly in Twingle. If no
|
||||||
|
recurring payments are processed via Twingle, but only one-off donations,
|
||||||
|
then this does not need to be activated. Otherwise, we strongly recommend
|
||||||
|
setting the button here to **Yes** so that there are no discrepancies between
|
||||||
|
CiviCRM and Twingle.
|
||||||
|
|
||||||
30
docs/configuration/profiles.md
Normal file
30
docs/configuration/profiles.md
Normal file
|
|
@ -0,0 +1,30 @@
|
||||||
|
# Configuring the Twingle Profile in CiviCRM
|
||||||
|
|
||||||
|
The Twingle API extension is being configured through configuration profiles.
|
||||||
|
This allows you to have different sets of configuration, as you might want to
|
||||||
|
handle donation submissions differently, depending on which form was used.
|
||||||
|
Each profile can react to one ore more form IDs being submitted along with
|
||||||
|
donation data.
|
||||||
|
|
||||||
|
1. In CiviCRM, go to **Administer**.
|
||||||
|
2. Choose **Twingle API configuration**.
|
||||||
|
|
||||||
|
|
||||||
|
3. Then click on **Configure profiles**.
|
||||||
|
|
||||||
|
|
||||||
|
4. The Twingle configuration is always done with the help of a profile. Please
|
||||||
|
use the Twingle default profile and click on **Edit**.
|
||||||
|
|
||||||
|
|
||||||
|
5. Then you will identify the Twingle API profile window. Start by entering the
|
||||||
|
corresponding information in the **General settings** section.
|
||||||
|
|
||||||
|
|
||||||
|
6. Define the different payment methods in the Payments section.
|
||||||
|
|
||||||
|
|
||||||
|
7. Make the settings for the groups.
|
||||||
|
|
||||||
|
|
||||||
|
8. When you have made all the settings, please press the **Save** button.
|
||||||
82
docs/configuration/user_permissions.md
Normal file
82
docs/configuration/user_permissions.md
Normal file
|
|
@ -0,0 +1,82 @@
|
||||||
|
# User, permissions, and API authentication
|
||||||
|
|
||||||
|
After the installation of the Twingle API extension, various configuration steps
|
||||||
|
must be carried out so that the connection functions smoothly. Among other
|
||||||
|
things, certain configurations must be made on the CMS platform CiviCRM is
|
||||||
|
implemented on.
|
||||||
|
|
||||||
|
Connecting to the Twingle API via CiviCRM's REST interface requires a user with
|
||||||
|
appropriate permissions in your CMS-system.
|
||||||
|
|
||||||
|
You might want to create a specific user role to assign permissions necessary
|
||||||
|
for calling the Twingle API only. This section describes how to accomplish this
|
||||||
|
in *Drupal* and *Wordpress*:
|
||||||
|
|
||||||
|
## New User Role in Drupal
|
||||||
|
|
||||||
|
1. In Drupal, go to **Administration/People/Permissions/Roles**.
|
||||||
|
2. Type Twingle API in the text box and select **Add role**. To the right of
|
||||||
|
your role there will be a *edit role* function and an *edit permissions*
|
||||||
|
button. The *edit permissions* selection will show only the permission
|
||||||
|
selections for the individual role.
|
||||||
|
3. As Permission you only have to select the following entry: **Twingle API:
|
||||||
|
Access Twingle API**.
|
||||||
|
|
||||||
|
## New User Role in Wordpress
|
||||||
|
|
||||||
|
1. In CiviCRM, go to **Administer/User and Permissions (Access Control)**.
|
||||||
|
2. Then select the **WordPress Access Control** link.
|
||||||
|
Here you can adjust the CiviCRM settings for each of the predefined User
|
||||||
|
Roles from WordPress.
|
||||||
|
3. Scroll down. As Permission you only have to select the following entry: *
|
||||||
|
*Twingle API: Access Twingle API**.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## New User in Drupal
|
||||||
|
|
||||||
|
1. In Drupal, go to **Administration/People**.
|
||||||
|
2. Then select **Add user**.
|
||||||
|
3. In user name field enter something like **Twingle API**
|
||||||
|
5. In Roles select **Twingle API**.
|
||||||
|
|
||||||
|
## Take over user
|
||||||
|
|
||||||
|
The Twingle API only works correctly if a contact connected to the permissioned
|
||||||
|
user exists in CiviCRM.
|
||||||
|
|
||||||
|
Here, the corresponding steps are described by way of example when using Drupal.
|
||||||
|
|
||||||
|
1. In CiviCRM, go to **Administer**.
|
||||||
|
2. In the **Users and Permissions** section, choose **Synchronize Users to
|
||||||
|
Contacts**.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
This function checks each user record in Drupal for a contact record in CiviCRM.
|
||||||
|
If there is no corresponding contact record for a user, a new one will be
|
||||||
|
generated. Check this in your CiviCRM contact management.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## Assign API key for the Twingle API user
|
||||||
|
|
||||||
|
The Twingle API contact in CiviCRM needs their own API key for authenticating
|
||||||
|
against CiviCRM's REST API endpoint. The API key is assigned with the help of
|
||||||
|
the API Explorer in CiviCRM.
|
||||||
|
|
||||||
|
1. Select the Twingle API contact in CiviCRM.
|
||||||
|
2. Look for the corresponding **CiviCRM ID** and remember the ID.
|
||||||
|
3. Go to **Support/Developper/API Explorer v4**.
|
||||||
|
4. Enter **Contact** in the entity field, **create** in action field and the
|
||||||
|
**ID** of the Twingle User in the **index** field.
|
||||||
|
5. In the values field, select **api_key**.
|
||||||
|
6. Enter the API key for the Twingle API user in the **add value** field.
|
||||||
|
7. Click on **Execute**.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
!!!note
|
||||||
|
You can also create API keys for contacts by using the [*API
|
||||||
|
Key*](https://civicrm.org/extensions/api-key) extension or with administrator
|
||||||
|
tools like *cv* or *drush*.
|
||||||
75
docs/configuration/xcm.md
Normal file
75
docs/configuration/xcm.md
Normal file
|
|
@ -0,0 +1,75 @@
|
||||||
|
# Configuring the Extended Contact Manager extension (XCM)
|
||||||
|
|
||||||
|
After the installation of the Twingle API extension, various configuration steps
|
||||||
|
must be carried out so that the connection functions smoothly. Twingle API
|
||||||
|
depends on the *Extended Contact Manager (XCM)* extension.
|
||||||
|
|
||||||
|
Taking over contact data using the Twingle API means that they may produce
|
||||||
|
duplicates in your CiviCRM contact management. Before contacts are added or
|
||||||
|
updated in CiviCRM a data check should take place to avoid this problem. This
|
||||||
|
data check is handled by the *Extended Contact Manager (XCM)* extension. This
|
||||||
|
extension must be configured accordingly for use with Twingle by defining a
|
||||||
|
corresponding profile.
|
||||||
|
|
||||||
|
## Creating an XCM Profile
|
||||||
|
|
||||||
|
Your first task regarding the Extended Contact Manager extension (XCM)
|
||||||
|
configuration will be to create an XCM profile to be used for the Twingle API.
|
||||||
|
This works best if you copy the *Default* profile.
|
||||||
|
|
||||||
|
1. In CiviCRM, go to **Administer**.
|
||||||
|
|
||||||
|
2. Select **Xtended Contact Matcher (XCM) Configuration** in the **System
|
||||||
|
Settings** section.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
3. Click on **Copy** in the **Default** profile.
|
||||||
|
|
||||||
|
4. Rename the new profile with **Twingle** in the **Profile name** field.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
5. Click **Save** at the bottom of this window. In the Profiles overview you can
|
||||||
|
find your new Twingle profile.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## Set up the Extended Contact Manager extension
|
||||||
|
|
||||||
|
After you have created the XCM profile, you must enter the configuration
|
||||||
|
settings for the Twingle connection to CiviCRM in this profile. Generally, you
|
||||||
|
will find a description of all the settings in
|
||||||
|
the [Extended Contact Manager (XCM) documentation](https://docs.civicrm.org/xcm/en/latest/configuration/).
|
||||||
|
|
||||||
|
Here you will find as support screenshots of the various sections of the
|
||||||
|
Extended Contact Manager extension (XCM). The settings are only an example.
|
||||||
|
Please adapt the settings to your individual requirements or environnement.
|
||||||
|
|
||||||
|
#### General section
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
#### Update section
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
#### Assignment rules section
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
#### Identified contacts section
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
#### New contact section
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
#### Duplicate section
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
#### Difference Handling section
|
||||||
|
|
||||||
|
|
||||||
BIN
docs/img/GenSet.jpg
Normal file
BIN
docs/img/GenSet.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 52 KiB |
BIN
docs/img/Kon_syn.jpg
Normal file
BIN
docs/img/Kon_syn.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 31 KiB |
BIN
docs/img/Konso.jpg
Normal file
BIN
docs/img/Konso.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 95 KiB |
BIN
docs/img/NewUser_Tw.jpg
Normal file
BIN
docs/img/NewUser_Tw.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 68 KiB |
BIN
docs/img/ProNam.jpg
Normal file
BIN
docs/img/ProNam.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 41 KiB |
BIN
docs/img/Prof.jpg
Normal file
BIN
docs/img/Prof.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
BIN
docs/img/Role_Twingle.jpg
Normal file
BIN
docs/img/Role_Twingle.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 60 KiB |
BIN
docs/img/Sepa.jpg
Normal file
BIN
docs/img/Sepa.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
BIN
docs/img/SepaKon.jpg
Normal file
BIN
docs/img/SepaKon.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 12 KiB |
BIN
docs/img/Twgrou.jpg
Normal file
BIN
docs/img/Twgrou.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 36 KiB |
BIN
docs/img/Twin_per.png
Normal file
BIN
docs/img/Twin_per.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
BIN
docs/img/XCMAdmin.jpg
Normal file
BIN
docs/img/XCMAdmin.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 279 KiB |
BIN
docs/img/XCMAkt.jpg
Normal file
BIN
docs/img/XCMAkt.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
BIN
docs/img/XCMDup.jpg
Normal file
BIN
docs/img/XCMDup.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 18 KiB |
BIN
docs/img/XCMGen.jpg
Normal file
BIN
docs/img/XCMGen.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 66 KiB |
BIN
docs/img/XCMIde.jpg
Normal file
BIN
docs/img/XCMIde.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 29 KiB |
BIN
docs/img/XCMNeu.jpg
Normal file
BIN
docs/img/XCMNeu.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 31 KiB |
BIN
docs/img/XCMPro.jpg
Normal file
BIN
docs/img/XCMPro.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 122 KiB |
BIN
docs/img/XCMReg.jpg
Normal file
BIN
docs/img/XCMReg.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 76 KiB |
BIN
docs/img/XCMUpda.jpg
Normal file
BIN
docs/img/XCMUpda.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 157 KiB |
BIN
docs/img/XCM_Profile.jpg
Normal file
BIN
docs/img/XCM_Profile.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 77 KiB |
BIN
docs/img/apikey.jpg
Normal file
BIN
docs/img/apikey.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 45 KiB |
BIN
docs/img/civiuser_tw.jpg
Normal file
BIN
docs/img/civiuser_tw.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
BIN
docs/img/twpay.jpg
Normal file
BIN
docs/img/twpay.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 71 KiB |
BIN
docs/img/xcmdif.jpg
Normal file
BIN
docs/img/xcmdif.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 7.8 KiB |
19
docs/installation.md
Normal file
19
docs/installation.md
Normal file
|
|
@ -0,0 +1,19 @@
|
||||||
|
# Installation
|
||||||
|
|
||||||
|
You can find an official release archive from
|
||||||
|
the [release page](https://github.com/systopia/de.systopia.twingle).
|
||||||
|
|
||||||
|
1. First, download and then unpack the archive and move the directory into your
|
||||||
|
CiviCRM extensions folder (e.g.,`.../civicrm/ext/`.
|
||||||
|
If you don't know where your extensions folder is, just have a look in your
|
||||||
|
CiviCRM settings ( **Administer**/**System Settings**/**Directories**)).
|
||||||
|
2. Next, open the extensions page in the CiviCRM settings (**Administer**/*
|
||||||
|
*System Settings**/**Extensions**).
|
||||||
|
3. Find the extension Twingle API in the*Extensions*tab and click on**Install**.
|
||||||
|
The extension will be set up.
|
||||||
|
|
||||||
|
## Extended Contact Matcher (XCM)
|
||||||
|
|
||||||
|
Please note that for the correct working of Twingle API you still need to
|
||||||
|
install the extension Extended Contact Matcher (XCM), see
|
||||||
|
the [documentation](https://docs.civicrm.org/xcm).
|
||||||
36
mkdocs.yml
36
mkdocs.yml
|
|
@ -1,20 +1,32 @@
|
||||||
site_name: Twingle API
|
site_name: Twingle API
|
||||||
repo_url: https://github.com/systopia/de.systopia.twingle
|
|
||||||
theme:
|
theme:
|
||||||
name: material
|
name: material
|
||||||
|
|
||||||
nav:
|
nav:
|
||||||
- 'Home': index.md
|
- Introduction: index.md
|
||||||
|
- Installation: installation.md
|
||||||
|
- Configuration:
|
||||||
|
- User, permissions and API authentication: configuration/user_permissions.md
|
||||||
|
- Extended Contact Manager (XCM) extension: configuration/xcm.md
|
||||||
|
- CiviSEPA integration: configuration/civisepa.md
|
||||||
|
- Twingle Profiles: configuration/profiles.md
|
||||||
|
- Configuring the Twingle Account on the Twingle website: configuration/account.md
|
||||||
|
- API documentation: api.md
|
||||||
|
|
||||||
markdown_extensions:
|
markdown_extensions:
|
||||||
- attr_list
|
- attr_list
|
||||||
- admonition
|
- admonition
|
||||||
- def_list
|
- def_list
|
||||||
- codehilite
|
- pymdownx.highlight:
|
||||||
- toc:
|
guess_lang: false
|
||||||
|
- toc:
|
||||||
permalink: true
|
permalink: true
|
||||||
- pymdownx.superfences
|
- pymdownx.superfences
|
||||||
- pymdownx.inlinehilite
|
- pymdownx.inlinehilite
|
||||||
- pymdownx.tilde
|
- pymdownx.tilde
|
||||||
- pymdownx.betterem
|
- pymdownx.betterem
|
||||||
- pymdownx.mark
|
- pymdownx.mark
|
||||||
|
|
||||||
|
plugins:
|
||||||
|
- search:
|
||||||
|
lang: en
|
||||||
Loading…
Add table
Add a link
Reference in a new issue