Documentation update.
This commit is contained in:
Michael Amos
parent
30ad463549
commit
4d750b1ab6
35 changed files with 350 additions and 141 deletions
163
README.md
163
README.md
|
|
@ -1,160 +1,45 @@
|
|||
# Twingle API
|
||||
# CiviCRM extension Twingle API[¶](https://docs.civicrm.org/twingle/en/latest/#twingle-api "Permanent link")
|
||||
|
||||
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 follow [this link](https://www.twingle.de/).
|
||||
|
||||
The extension is licensed under
|
||||
[AGPL-3.0](https://github.com/systopia/de.systopia.twingle/blob/master/LICENSE.txt).
|
||||
Twingle as fundraising service can be connected to CiviCRM via its API with the extension **Twingle API**.
|
||||
|
||||
## Configuration
|
||||
## What advantages does the Twingle API extension offer?
|
||||
|
||||
### Configure Twingle
|
||||
- Donations from Twingle can be automatically created in CiviCRM and assigned to existing or new contacts and administered yourself in CiviCRM.
|
||||
|
||||
Please refer to the
|
||||
[Twingle FAQ on using Twingle with CiviCRM](https://support.twingle.de/faq/de-de/9/46)
|
||||
(currently only available in German).
|
||||
- Supporters and contacts of donations can be managed yourself in CiviCRM and contacts yourself.
|
||||
|
||||
### Configure Extended Contact Matcher (XCM)
|
||||
- Donations can be declared as closed or open depending on the payment type
|
||||
|
||||
Make sure you use an XCM profile with the option *Match contacts by contact ID*
|
||||
enabled.
|
||||
- SEPA mandates can be created for one-off and recurring payments.
|
||||
|
||||
Be careful when enabling the *"Change Primary Detail?"* option. While it might
|
||||
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.
|
||||
- Donors can be entered into groups for newsletters, mailings and donation receipts.
|
||||
|
||||
### Configure CiviCRM
|
||||
- A memberships can be set up for a donor.
|
||||
|
||||
- Go to the Administration console at `/civicrm/admin`
|
||||
- Open "Twingle API Configuration" at `/civicrm/admin/settings/twingle`
|
||||
- Data can be entered in user-defined fields
|
||||
|
||||
#### Configure CiviSEPA integration
|
||||
## How to set up the Twingle API extension
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
You have to carry out the following configuration steps:
|
||||
|
||||
#### Configure profiles
|
||||
- Creating a Twingle user and a user role in your CMS-System (Drupal, Wordpress ...)
|
||||
|
||||
Open "Configure profiles" at `/civicrm/admin/settings/twingle/profiles`.
|
||||
- Configuring the Extended Contact Matcher (XCM) in CiviCRM
|
||||
|
||||
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.
|
||||
- Creating a Twingle User and an API key in CiviCRM
|
||||
|
||||
| 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. |
|
||||
- Activating the SEPA connection in CiviCRM
|
||||
|
||||
- Configuring the Twingle profile in CiviCRM
|
||||
|
||||
- Configuring your Twingle Account on the Twingle website
|
||||
|
||||
|
||||
## 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.
|
||||
The Twingle API extension is licensed under [AGPL-3.0](https://github.com/systopia/de.systopia.twingle/blob/master/LICENSE.txt).
|
||||
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 |
87
docs/api_tw.md
Normal file
87
docs/api_tw.md
Normal file
|
|
@ -0,0 +1,87 @@
|
|||
# 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.
|
||||
39
docs/con_civi.md
Normal file
39
docs/con_civi.md
Normal file
|
|
@ -0,0 +1,39 @@
|
|||
# Twingle API: Creating a Twingle User in CiviCRM
|
||||
|
||||
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 regarding the general CiviCRM administration. Among other things, there must be in either case a Twingle user in the CiviCRM contacts.
|
||||
|
||||
## Take over user
|
||||
|
||||
The Twingle API only works correctly if a user with the name **Twingle API** exists in CiviCRM. Make sure that you have previously created the corresponding user your CMS user administration (Drupal, Wordpress ...).
|
||||
|
||||
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 user in CiviCRM needs his own API key. The API key is assigned with the help of the API Explorer in CiviCRM.
|
||||
|
||||
1. Select the Twingle API user 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**.
|
||||
|
||||
|
||||
41
docs/con_drup.md
Normal file
41
docs/con_drup.md
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
# Twingle API: Creating a Twingle user and a user roll in your CMS system
|
||||
|
||||
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.
|
||||
|
||||
In an CMS system, administration of permissions is made easier by creating roles and assigning permissions to them rather than assigning permissions to each user.
|
||||
|
||||
The Twingle API requires a user with the name Twingle API and a user role with the name Twingle API in your CMS-system.
|
||||
|
||||
Here, the corresponding steps are described by way of example when using Drupal.
|
||||
|
||||
## 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 **Twingle API**
|
||||
|
||||
4. In the e-mail field enter either **info@example.de** or **mailtest@example.de**.
|
||||
|
||||
5. In Roles select **Twingle API**.
|
||||
22
docs/con_man.md
Normal file
22
docs/con_man.md
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
# Twingle API: Configuring the Twingle account 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 make the following settings:
|
||||
|
||||
1. API key from your Twingle user
|
||||
|
||||
2. Site key
|
||||
|
||||
3. URL
|
||||
|
||||
Important: The URL must always be the complete URL to the interface.
|
||||
Examples:
|
||||
|
||||
- Drupal: https://meine-domain.de/sites/all/modules/civicrm/extern/rest.php
|
||||
- Wordpress (with CiviCRM <5.25): https://meine-domain.de/wp-content/plugins/civicrm/civicrm/extern/rest.php
|
||||
- Wordpress (with CiviCRM 5.25+): https://meine-domain.de/wp-json/civicrm/v3/rest
|
||||
|
||||
|
||||
|
||||
[For detailled information please follow this link](https://support.twingle.de/faq/de-de/9-anbindung-externer-systeme/46-wie-kann-ich-civicrm-mit-twingle-nutzen) (in German language only).
|
||||
31
docs/con_tw.md
Normal file
31
docs/con_tw.md
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
# Configuring the Twingle Profile in CiviCRM
|
||||
|
||||
After the installation of the Twingle API extension, various configuration steps must be carried out so that the connection functions smoothly. Among other things, you have to make some settings in the Twingle Profile in CiviCRM.
|
||||
|
||||
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.
|
||||
25
docs/con_twse.md
Normal file
25
docs/con_twse.md
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
# Activating SEPA for the Twingle API extension in CiviCRM
|
||||
|
||||
After the installation of the extension, various configuration steps must be carried out so that the connection functions smoothly. If you would like to create and manage the SEPA mandates yourself for the one-off and recurring payments with CiviCRM, you have to make some settings regarding the SEPA connection.
|
||||
|
||||
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 takes place in Twingle.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
59
docs/con_xcm.md
Normal file
59
docs/con_xcm.md
Normal file
|
|
@ -0,0 +1,59 @@
|
|||
# Twingle API: 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 works only correctly when you have previously installed the Extended Contact Manager extension (XCM).
|
||||
|
||||
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 extension (XCM). This extension must be configured accordingly for use with Twingle by defining a corresponding profile.
|
||||
|
||||
## Creating a Twingle Profile
|
||||
|
||||
Your first task regarding the Extended Contact Manager extension (XCM) configuration will be to create a corresponding Twinge profile. 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 (XCM)
|
||||
|
||||
After you have created the Twingle 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
|
||||
|
||||
|
||||
12
docs/install_tw.md
Normal file
12
docs/install_tw.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
# Installation Twingle API
|
||||
|
||||
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). You can find the corresponding information therefore [here](https://docs.civicrm.org/xcm/en/latest/).
|
||||
12
mkdocs.yml
12
mkdocs.yml
|
|
@ -1,10 +1,18 @@
|
|||
site_name: Twingle API
|
||||
repo_url: https://github.com/systopia/de.systopia.twingle
|
||||
theme:
|
||||
name: material
|
||||
|
||||
nav:
|
||||
- 'Home': index.md
|
||||
- Home: index.md
|
||||
- Installation: install_tw.md
|
||||
- Configuration:
|
||||
- Creating a Twingle user in the CMS system: con_drup.md
|
||||
- Configuring the Extended Contact Manager extension: con_xcm.md
|
||||
- Creating a Twingle user in CiviCRM: con_civi.md
|
||||
- Activating SEPA for the Twingle API extension in CiviCRM: con_twse.md
|
||||
- Configuring the Twingle Profile in CiviCRM: con_tw.md
|
||||
- Configuring the Twingle Account on the Twingle website: con_man.md
|
||||
- API documentation: api_tw.md
|
||||
|
||||
markdown_extensions:
|
||||
- attr_list
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue