# Parameters to Make One-time Donations source: https://developer.mastercard.com/donations/documentation/parameters/manage-onetime-guest-dn-param/onetime/index.md ## Method to Make a One-time Donation {#method-to-make-a-one-time-donation} | Method | Endpoint | |--------|---------------------| | POST | /donations/payments | Note: The Entire Request Body has to be encrypted! For more details, refer to the [How to Encrypt](https://developer.mastercard.com/donations/tutorial/how-to-access-sandbox-environment/mastercard-encryption-decryption-mechanism/index.md) section. ## One-Time Donation with a Payment Card-on-File {#one-time-donation-with-a-payment-card-on-file} Charges a card on file with the amount of the donation to the charity selected by a donor. ### Request parameters {#request-parameters} | Name | Type | Description | Notes | |-----------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------| | **donorId** | string | Unique ID generated by Mastercard when a new donor is enrolled. | **Required** | | **cardId** | string | Unique ID generated by Mastercard when a donor adds a payment card on file. | **Required** | | **card** | object | See [Card](https://developer.mastercard.com/donations/documentation/parameters/manage-onetime-guest-dn-param/onetime/index.md#card) attribute. | Optional | | **donation** | object | See [Donation](https://developer.mastercard.com/donations/documentation/parameters/manage-onetime-guest-dn-param/onetime/index.md#donation) attribute. | **Required** | | **authPayerResponse** | object | See [Auth Payer Response](https://developer.mastercard.com/donations/documentation/parameters/manage-onetime-guest-dn-param/onetime/index.md#authpayerresponse) attributes | Optional | | **authentication** | object | See [Authentication](https://developer.mastercard.com/donations/documentation/parameters/manage-onetime-guest-dn-param/onetime/index.md#authentication) attributes | **Required** If authPayerResponse is used | | **3ds** | object | See [3DS](https://developer.mastercard.com/donations/documentation/parameters/manage-onetime-guest-dn-param/onetime/index.md#3ds) attributes | **Required** If authPayerResponse is used | | **3ds2** | object | See [3DS2](https://developer.mastercard.com/donations/documentation/parameters/manage-onetime-guest-dn-param/onetime/index.md#3ds2) attributes | **Required** If authPayerResponse is used , only for MPGS | ### Child Attributes {#child-attributes} #### card {#card} | Name | Type | Description | Notes | |---------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| | **cvc** | string | The card verification code of the payment card selected for the donation. Optional for MPGS and Stripe payment gateways on Guest and One-Time payments. It is the three digits of the number printed on the signature strip on the reverse of the card. On American Express it is usually a four-digit code on the front. | **Conditional** | #### donation {#donation} | Name | Type | Description | Notes | |------------------|--------|---------------------------------------------------------------------------------------------------------------------------|--------------| | **charityId** | string | Unique Id of the charity generated by Mastercard at the time the charity was onboarded into the Mastercard Donate Service | **Required** | | **amount** | number | The amount of the donation selected by the donor. | **Required** | | **donationType** | enum | The type of donation. Can be either **ONE-TIME** or **DISASTER** | **Required** | ##### authpayerresponse {#authpayerresponse} | Name | Type | Description | Notes | |--------------------|--------|------------------------------------------|-------------------------------------------| | **authentication** | object | Contains details of 3DS and 3DS2 Objects | **Required** If authPayerResponse is used | ##### authentication {#authentication} | Name | Type | Description | Notes | |----------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| | **3ds** | object | Contains SCA details like acsEci, authenticationToken, transactionId. Note : 3ds has nothing to do with version of 3ds , it is format in which payment gateway accepts SCA fields. | **Required** | | **3ds2** | object | Contains SCA details like transactionStatus, protocolVersion. Note : 3ds has nothing to do with version of 3ds2 , it is format in which payment gateway accepts SCA fields. | **Required** | ##### 3ds {#3ds} | Name | Type | Description | Notes | |-------------------------|----------------------------|----------------------------------------------------------------------------------------|---------------------------------------------| | **acsEci** | String | Value returned by Issuers indicating the outcome of authentication on 3DS transactions | Optional for MPGS , **Required** for Stripe | | **version** | String | Version returned by issuer to authenticate 3DS payments | **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 - Required only for MPGS {#3ds2---required-only-for-mpgs} | Name | Type | Description | Notes | |-----------------------|--------|--------------------------------------------------------------------------------------------------------|--------------| | **transactionStatus** | String | Value retuned by issuer showing status of transaction. Permissible values -(Y,N) | **Required** | | **protocolVersion** | String | Version returned by issuer to authenticate 3DS payments. Permissible value - #.#.# where # is numeric. | Optional | ### Response Parameters {#response-parameters} A successful request returns the `HTTP 200 Success` status code and a JSON response body that includes a unique transaction identifier. | Name | Type | Description | |------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **transactionId** | string | The unique Id of the transaction. | | **transactionStatus** | string | The status of the transaction. **SUCCESS :** if transaction approved. **FAILURE :** if transaction declined. **PENDING :** if the transaction is pending with gateway or with user (SCA authentication). | | **transactionMessage** | string | The message of the transaction. | | **reasonCode** | String | The failure reason code (**only in case of failed transaction**) | | **reasonMessage** | String | The message for the failure reason (**only in case of failed transaction**) | ## One-time Donation with a New Card {#one-time-donation-with-a-new-card} Donors who have previously enrolled in the Mastercard Donate Service can add a new payment card at the time they are making a one-time donation. | Method | Endpoint | |--------|---------------------| | POST | /donations/payments | ### Request parameters {#request-parameters-1} Note: The Entire Request Body has to be encrypted! | Name | Type | Description | Notes | |-----------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------| | **donorId** | string | Unique ID generated by Mastercard when a new donor is enrolled. | **Required** | | **card** | object | See [Card](https://developer.mastercard.com/donations/documentation/parameters/manage-onetime-guest-dn-param/onetime/index.md#card) attribute. | **Required** | | **donation** | object | See [Donation](https://developer.mastercard.com/donations/documentation/parameters/manage-onetime-guest-dn-param/onetime/index.md#donation) attribute | **Required** | | **authPayerResponse** | object | See [Auth Payer Response](https://developer.mastercard.com/donations/documentation/parameters/manage-onetime-guest-dn-param/onetime/index.md#authpayerresponse) attributes | Optional | | **authentication** | object | See [Authentication](https://developer.mastercard.com/donations/documentation/parameters/manage-onetime-guest-dn-param/onetime/index.md#authentication) attributes | **Required** If authPayerResponse is used | | **3ds** | object | See [3DS](https://developer.mastercard.com/donations/documentation/parameters/manage-onetime-guest-dn-param/onetime/index.md#3ds) attributes | **Required** If authPayerResponse is used | | **3ds2** | object | See [3DS2](https://developer.mastercard.com/donations/documentation/parameters/manage-onetime-guest-dn-param/onetime/index.md#3ds2) attributes | **Required** If authPayerResponse is used , only for MPGS | ### Child Attributes {#child-attributes-1} #### card {#card-1} | Name | Type | Description | Notes | |----------------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| | primaryAccountNumber | string | The PAN entered by the donor at the time of the donation | **Required** | | **cvc** | string | The card verification code of the payment card selected for the donation. It is the final three digits of the number printed on the signature strip on the reverse of the card. On American Express it is usually a four-digit code on the front. | **Required** | | **expiryInfo** | object | The expiration date for the payment card added by the donor. | **Required** | #### expiryInfo {#expiryinfo} | Name | Type | Description | Notes | |-----------|--------|----------------------|--------------| | **month** | string | The expiration month | **Required** | | **year** | string | The expiration year | **Required** | #### donation {#donation-1} | Name | Type | Description | Notes | |------------------|--------|---------------------------------------------------------------------------------------------------------------------------|--------------| | **charityId** | string | Unique Id of the charity generated by Mastercard at the time the charity was onboarded into the Mastercard Donate Service | **Required** | | **amount** | number | The amount of the donation selected by the donor. | **Required** | | **donationType** | enum | The type of donation. Can be either **ONE-TIME** or **DISASTER** | **Required** | ##### authpayerresponse {#authpayerresponse-1} | Name | Type | Description | Notes | |--------------------|--------|------------------------------------------|-------------------------------------------| | **authentication** | object | Contains details of 3DS and 3DS2 Objects | **Required** If authPayerResponse is used | ##### authentication {#authentication-1} | Name | Type | Description | Notes | |----------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| | **3ds** | object | Contains SCA details like acsEci, authenticationToken, transactionId. Note : 3ds has nothing to do with version of 3ds , it is format in which payment gateway accepts SCA fields. | **Required** | | **3ds2** | object | Contains SCA details like transactionStatus, protocolVersion. Note : 3ds has nothing to do with version of 3ds2 , it is format in which payment gateway accepts SCA fields. | **Required** | ##### 3ds {#3ds-1} | Name | Type | Description | Notes | |-------------------------|----------------------------|----------------------------------------------------------------------------------------|---------------------------------------------| | **acsEci** | String | Value returned by Issuers indicating the outcome of authentication on 3DS transactions | Optional for MPGS , **Required** for Stripe | | **version** | String | Version returned by issuer to authenticate 3DS payments | **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 - Required only for MPGS {#3ds2---required-only-for-mpgs-1} | Name | Type | Description | Notes | |-----------------------|--------|--------------------------------------------------------------------------------------------------------|--------------| | **transactionStatus** | String | Value retuned by issuer showing status of transaction. Permissible values -(Y,N) | **Required** | | **protocolVersion** | String | Version returned by issuer to authenticate 3DS payments. Permissible value - #.#.# where # is numeric. | Optional | ### Response Parameters {#response-parameters-1} A successful request returns the `HTTP 200 Success` status code and a JSON response body that includes a unique transaction identifier. | Name | Type | Description | |------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **transactionId** | string | The unique identifier for the transaction. Generated by Mastercard. | | **transactionStatus** | string | The status of the donation processing. **SUCCESS :** if transaction approved. **FAILURE :** if transaction declined. **PENDING :** if the transaction is pending with gateway or with user (SCA authentication). | | **transactionMessage** | string | The message associated with the donations processing. | | **reasonCode** | String | The failure reason code (**only in case of failed transaction**) | | **reasonMessage** | String | The message for the failure reason (**only in case of failed transaction**) |