87 lines
23 KiB
Markdown
87 lines
23 KiB
Markdown
# 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.
|