# Twingle API
Extension to connect to the Twingle fundraising service via its API.
* [About Twingle](https://www.twingle.de/)
The extension is licensed under
[AGPL-3.0](https://github.com/systopia/de.systopia.twingle/blob/master/LICENSE.txt).
## Configuration
### Configure Twingle
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).
### Configure Extended Contact Matcher (XCM)
Make sure you use an XCM profile with the option *Match contacts by contact ID*
enabled.
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.
### 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 |
|----------------------------------------|---------|-------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------|
| `project_id` | String | The Twingle project ID | | Yes |
| `trx_id` | String | The unique transaction ID of the donation | A unique transaction ID for the donation. | Yes |
| `confirmed_at` | String | The date when the donation was issued | A string representing a date in the format `YmdHis` | Yes |
| `purpose` | String | The purpose of the donation | | |
| `amount` | Integer | The donation amount in minor currency unit | | Yes |
| `currency` | String | The ISO-4217 currency code of the donation | A valid ISO-4217 currency code | Yes |
| `newsletter` | Boolean | Whether to subscribe the contact to the newsletter group defined in the profile | | |
| `postinfo` | Boolean | Whether to subscribe the contact to the postal mailing group defined in the profile | | |
| `donation_receipt` | Boolean | Whether the contact requested a donation receipt | | |
| `payment_method` | String | The Twingle payment method used for the donation | One of:
- `banktransfer`
- `debit_manual`
- `debit_automatic`
- `creditcard`
- `mobilephone_germany`
- `paypal`
- `sofortueberweisung`
- `amazonpay`
- `paydirekt`
- `applepay`
- `googlepay`
| Yes |
| `donation_rhythm` | String | The interval which the donation is recurring in | One of:
- `'one_time',`
- `'halfyearly',`
- `'quarterly',`
- `'yearly',`
- `'monthly'`
| Yes |
| `debit_iban` | 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 |
| `debit_bic` | String | The BIC for SEPA Direct Debit payments | A valid ISO 9362 BIC | Yes, if `payment_method` is `debit_manual` and CiviSEPA is used |
| `debit_mandate_reference` | String | The mandate reference for SEPA Direct Debit payments | | |
| `debit_account_holder` | String | The account holder for SEPA Direct Debit payments | | |
| `is_anonymous` | Boolean | Whether the donation is submitted anonymously | | |
| `user_gender` | String | The gender of the contact | | |
| `user_birthdate` | String | The date of birth of the contact | A string representing a date in the format `Ymd` | |
| `user_title` | String | The formal title of the contact | | |
| `user_email` | String | The e-mail address of the contact | A valid e-mail address | |
| `user_firstname` | String | The first name of the contact | | |
| `user_lastname` | String | The last name of the contact | | |
| `user_street` | String | The street address of the contact | | |
| `user_postal_code` | String | The postal code of the contact | | |
| `user_city` | String | The city of the contact | | |
| `user_country` | String | The country of the contact | [ISO 3166-1 Alpha-2 country codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) | |
| `user_telephone` | String | The telephone number of the contact | | |
| `user_company` | String | The company of the contact | | |
| `user_extrafield` | String | Additional information of the contact | | |
| `campaign_id` | 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 |
|---------------------------|---------|------------------------------------------------|-------------------------------------------------------|----------|
| `project_id` | String | The Twingle project ID | | Yes |
| `trx_id` | String | The unique transaction ID of the donation | A unique transaction ID for the donation. | Yes |
| `ended_at` | 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 |
|------------------------------|--------|----------------------------------------------------|-------------------------------------------------------|----------|
| `project_id` | String | The Twingle project ID | | Yes |
| `trx_id` | String | The unique transaction ID of the donation | A unique transaction ID for the donation. | Yes |
| `cancelled_at` | String | The date when the recurring donation was cancelled | A string representing a date in the format `YmdHis` | Yes |
| `cancel_reason` | 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.