# Parameters to Create Recurring Donations
source: https://developer.mastercard.com/donations/documentation/parameters/manage-recur-donation-param/monthly/index.md

## Method to Create a Recurring Donation {#method-to-create-a-recurring-donation}

| Method |                                                   Endpoint                                                    |
|--------|---------------------------------------------------------------------------------------------------------------|
| POST   | **Deprecated:** ~~/donations/donors/{donor_id}/setups~~ **New:** /donations/donors/{donor_id}/donation-setups |

## Path parameters {#path-parameters}

|    Name     |  Type  |                           Description                           |    Notes     |
|-------------|--------|-----------------------------------------------------------------|--------------|
| **donorId** | string | Unique ID generated by Mastercard when a new donor is enrolled. | **Required** |

## Request Parameters {#request-parameters}

|            Name            |  Type  |                                                                                               Description                                                                                               |                                                    Notes                                                     |
|----------------------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
| **cardId**                 | string | Unique ID for the card on file. Generated by Mastercard at the time the card was added.                                                                                                                 | **Required**                                                                                                 |
| **charityId**              | string | The charity's unique identifier assigned by Mastercard during charity onboarding.                                                                                                                       | **Required**                                                                                                 |
| **donationType**           | enum   | Specifies the type of donation the donor is setting up. Options include **Monthly** , **Micro** , and **Roundup**.                                                                                      | **Required**                                                                                                 |
| **amount**                 | number | The donation amount. * For micro-donations this is the small amount donated each time the payment card is used to make a purchase. * For monthly donations this is the amount to be donated each month. | **Conditional** This field is required only for monthly and micro-donations only, not for roundup donations. |
| **maxCap**                 | number | The maximum amount allowed for donations each month.                                                                                                                                                    | **Conditional** This field required only for roundup and micro-donations, not for monthly donations.         |
| **authPayerResponse**      | object | See [Auth Payer Response](https://developer.mastercard.com/donations/documentation/parameters/manage-recur-donation-param/monthly/index.md#authpayerresponse) attributes                                | Optional                                                                                                     |
| **authentication**         | object | See [Authentication](https://developer.mastercard.com/donations/documentation/parameters/manage-recur-donation-param/monthly/index.md#authentication) attributes                                        | **Required** Required if `authPayerResponse` object is passed.                                               |
| **~~3ds~~ secureAuth**     | object | See [secureAuth](https://developer.mastercard.com/donations/documentation/parameters/manage-recur-donation-param/monthly/index.md#3ds) attributes                                                       | **Required** Required if `authPayerResponse` object is passed.                                               |
| **~~3ds2~~ secureAuthTwo** | object | See [secureAuthTwo](https://developer.mastercard.com/donations/documentation/parameters/manage-recur-donation-param/monthly/index.md#3ds2) attributes                                                   | **Required** Required if `authPayerResponse` object is passed, only for MPGS.                                |

### Child Attributes {#child-attributes}

#### authpayerresponse {#authpayerresponse}

|        Name        |  Type  |               Description                |                             Notes                              |
|--------------------|--------|------------------------------------------|----------------------------------------------------------------|
| **authentication** | object | Contains details of 3DS and 3DS2 Objects | **Required** Required if `authPayerResponse` object is passed. |

#### authentication {#authentication}

|            Name            |  Type  |                                                                                                   Description                                                                                                    |    Notes     |
|----------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **~~3ds~~ secureAuth**     | object | Contains SCA details such as `acsEci`, `authenticationToken`, and `transactionId`. **~~3ds~~ secureAuth has nothing to do with version of 3DS, it is a format in which the payment gateway accepts SCA fields.** | **Required** |
| **~~3ds2~~ secureAuthTwo** | object | Contains SCA details such as `transactionStatus` and `protocolVersion`. **~~3ds~~ secureAuth has nothing to do with version of 3DS, it is a format in which the payment gateway accepts SCA fields.**            | **Required** |

#### {#3ds}~~3ds~~ secureAuth {#a-id3dsa3ds-secureauth}

|          Name           |            Type            |                                       Description                                       |                                  Notes                                   |
|-------------------------|----------------------------|-----------------------------------------------------------------------------------------|--------------------------------------------------------------------------|
| **acsEci**              | String                     | Value returned by issuers indicating the outcome of authentication on 3DS transactions. | **Conditional** This field is: * Required for Stripe * Optional for MPGS |
| **version**             | String                     | Version returned by issuer to authenticate 3DS payments.                                | **Conditional** This field is required only for Stripe.                  |
| **authenticationToken** | String                     | Value returned by issuers to authenticate 3DS transactions.                             | **Required**                                                             |
| **transactionId**       | String (valid UUID String) | A unique identifier of each 3DS transaction.                                            | **Required**                                                             |

#### {#3ds2}~~3ds2~~ secureAuthTwo {#a-id3ds2a3ds2-secureauthtwo}

The ~~3ds2~~ 'secureAuthTwo' parameter is required only for MPGS.

|         Name          |  Type  |                                               Description                                                |    Notes     |
|-----------------------|--------|----------------------------------------------------------------------------------------------------------|--------------|
| **transactionStatus** | String | Value retuned by issuer showing status of transaction. Permissible values are: * Y * N                   | **Required** |
| **protocolVersion**   | String | Version returned by issuer to authenticate 3DS payments. Permissible value is: #.#.# where # is numeric. | Optional     |

## Response Parameters {#response-parameters}

A successful request returns the `HTTP 201 Created` status code and a JSON response body that includes a unique donation setup ID.

|          Name          |                                                       Description                                                       |
|------------------------|-------------------------------------------------------------------------------------------------------------------------|
| **donorId**            | Unique ID generated by Mastercard when a new donor is enrolled.                                                         |
| **setupStatus**        | Indicates the status of the set-up. Can be **ACTIVE** , **INACTIVE** , or **FAILED**.                                   |
| **transactionId**      | Unique ID generated by Mastercard. This is used only for monthly donations and not for round-up and micro-donations.    |
| **transactionStatus**  | Returns **SUCCESS** or **FAILURE** for monthly donations. Not used for roundup and micro-donations.                     |
| **transactionMessage** | Returns **APPROVED** or **DECLINE** for monthly donations. Not used for roundup and micro-donations.                    |
| **donationSetupId**    | The unique identifier of the monthly donation configuration generated by Mastercard at the time the donation was setup. |
| **reasonCode**         | The failure reason code (**only in case of failed transaction**).                                                       |
| **reasonMessage**      | The message for the failure reason (**only in case of failed transaction**).                                            |