Guides (SDK /API) | Technical Reference | BBDN | How-to Documentation

You are here: REST API for the Advanced Donation Form > Donation API

Donation API

Endpoints:

{PartId}/Donation/{Id} - GET
{PartId}/Donation/Create - POST
{PartId}/Donation/{Id}/CompleteBBSPDonation - POST
{PartId}/Donation/{Id}/ConfirmationHtml - GET

Enums:

PaymentMethod
TransactionStatus
ErrorCode
DayOfWeek
RecurrenceFrequency

Donation API - Endpoints

{PartId}/Donation/{Id} - GET

Summary: Gets the donation object of the specified Id if the user has appropriate access.

Behavior: Ensures the user has access to this donation by finding the Id in their session. If so, loads the donation out of the database.

Parameters
Name	Type	Required	Description
PartId	Integer	true	Id of a donation form part.
Id	GUID	true	Id of a donation.

Possible Responses
Status	Body	Description
403 Forbidden		User does not have access to the specified donation.
404 Not Found		No donation was found by the specified Id.
200 OK	Donation	Returns a Donation object containing information about the requested donation Id.

Example Responses:

Name: Success

Status:200 OK

Body:

                        {
	"Donor":{
		"Address":{
			"City":"Columbia",
			"Country":"United States",
			"PostalCode":"29212",
			"State":"SC",
			"StreetAddress":"123 Main St."
			},
		"EmailAddress":"john.doe@blackbaud.com",
		"FirstName":"John",
		"LastName":"Doe",
		"Phone":"555-555-5555",
		"Title":"Mr."
		},
	"Gift":{
		"Designations":
			[{
			"Amount":5,
			"DesignationId":"3439a5c7-9977-4f9c-ba11-fadfb8144d35"
			}],
		"FinderNumber":0,
		"IsAnonymous":false,
		"PaymentMethod":1,
		"Comments":"Gift comments here.",
    "CreateGiftAidDeclaration":false,
		"Attributes":
			[{
			"AttributeId":"BD18B3FD-B382-4183-A415-8F84B1E0E411",
			"Value":"Volunteer;Member;Alumni"
			},
			{
			"AttributeId":"3607C77D-19DC-4EE0-A0CD-A352762A8EF0",
			"Value":"1985"
			}],
      "Recurrence":
        {
        "DayOfMonth":26,
        "DayOfWeek":null,
        "EndDate":null,
        "Frequency":2,
        "Month":null,
        "StartDate":"Date(1337227200000-0400)"
        },
      "Tribute":
      {
      "Acknowledgee":
        {
        "AddressLines":"123 Sunset ln.",
        "City":"Charleston",
        "Country":"USA",
        "Email":"email@address.com",
        "FirstName":"Jane",
        "LastName":"Doe",
        "Phone":"123-123-1234",
        "PostalCode":"29482",
        "State":"SC"
        },
      "TributeDefinition":
        {
        "Description":"New tribute",
        "FirstName":"John",
        "LastName":"Hancock",
        "Type":"Tribute"
        },
      "TributeId":null
      }
	},
	"Id":"853f96be-bf08-4828-aefa-326a06e48d31","
	Origin":{
		"AppealId":"C3B20FD8-6A81-451E-BF78-D195E82B4CBF",
		"PageId":784,
		"PageName":"Sample Page"
		},
	"TransactionStatus":1
}

{PartId}/Donation/Create - POST

Summary: Attempts to create a donation from the posted object.

Behavior: Validates the fields in the posted CreateDonationRequest. If valid, creates a donation transaction and saves it to the database. Stores the Id of the new donation in session so the user has permissions for the donation instance. If the payment type is credit card, communicates with Blackbaud secured payment to set up a check out URI and adds that URI to the return object. For credit card payment, the donation is saved in a Pending state. For payments not using a credit card, the donation is saved in a Completed state and an acknowledgement email is sent.

Parameters
Name	Type	Required	Description
PartId	Integer	true	Id of a donation form part.

Possible Responses
Status	Body	Description
400 Bad Request	Error[]	A validation error was found with the post data or an error occurred in the processing. Returns an array of Errror objects. Possible Errors: • RecordNotFound (106) • RequiredFieldMissing (101) • InvalidFieldSupplied (102) • ValueBelowMinimum (103) • ValueExceedsMaximum (104) • ValueNotAllowed (105) • ExceedsMaximumLength (107)
201 OK	CreateDonationReply	Returns a CreateDonationReply object containing information about the created donation and optionally a Uri for completing payment of the donation with Blackbaud secured payment. A location header is also returned containing a Uri of the new donation object.

Example Responses:

Name: Success

Status: 201 OK

Body:

                        {
	"Donation":{
		"Donor":{
			"Address":{
				"City":"Columbia",
				"Country":"United States",
				"PostalCode":"29212",
				"State":"SC",
				"StreetAddress":"123 Main St."
				},
			"EmailAddress":"john.doe@blackbaud.com",
			"FirstName":"John",
			"LastName":"Doe",
			"Phone":"555-555-5555",
			"Title":"Mr."
			},
		"Gift":{
			"Designations":
				[{
				"Amount":5,
				"DesignationId":"3439a5c7-9977-4f9c-ba11-fadfb8144d35"
				}],
			"FinderNumber":0,
			"IsAnonymous":false,
			"PaymentMethod":1,
			"Comments":"Gift comments here.",
      "CreateGiftAidDeclaration":false,
			"Attributes":
				[{
				"AttributeId":"BD18B3FD-B382-4183-A415-8F84B1E0E411",
				"Value":"Volunteer;Member;Alumni"
				},
				{
				"AttributeId":"3607C77D-19DC-4EE0-A0CD-A352762A8EF0",
				"Value":"1985"
				}],
      "Recurrence":
        {
        "DayOfMonth":26,
        "DayOfWeek":null,
        "EndDate":null,
        "Frequency":2,
        "Month":null,
        "StartDate":"\/Date(1337227200000-0400)\/"
        },
      "Tribute":
      {
      "Acknowledgee":
        {
        "AddressLines":"123 Sunset ln.",
        "City":"Charleston",
        "Country":"USA",
        "Email":"email@address.com",
        "FirstName":"Joe",
        "LastName":"Schmo",
        "Phone":"123-123-1234",
        "PostalCode":"29482",
        "State":"SC"
        },
      "TributeDefinition":
        {
        "Description":"New tribute",
        "FirstName":"John",
        "LastName":"Hancock",
        "Type":"Tribute"
        },
      "TributeId":null
      }
		},
		"Id":"853f96be-bf08-4828-aefa-326a06e48d31","
		Origin":{
			"AppealId":"C3B20FD8-6A81-451E-BF78-D195E82B4CBF",
			"PageId":784,
			"PageName":"Sample Page"
			},
		"TransactionStatus":1
	},
	"BBSPCheckoutUri":" https://payments.blackbaud.com/Pages/Index.aspx?t=853f96be-bf08-4828-aefa-326a06e48d31"
}

Description:

Name: Error

Status: 400 Bad Request

Body:

                        [
	{
		"ErrorCode":101,
		"Field":"Donor.LastName",
		"Message":null
	},
	{
		"ErrorCode":103,
		"Field":"Gift.Designations.Amount",
		"Message":"A designation's amount should be greater than 0."
	}
]

{PartId}/Donation/{Id}/CompleteBBSPDonation - POST

Summary: Signals the application to confirm that the donation has been paid in Blackbaud secured payment and to complete the creation of the donation.

Behavior: Ensures the user has access to this donation by finding the Id in their session. If so, loads the donation out of the database. Ensures the donation is a credit card donation and not already in a completed state. If not, then confirms with Blackbaud secured payment whether the donation is paid. If so, updates the donation status and sends the acknowledgment email.

Parameters
Name	Type	Required	Description
PartId	Integer	true	Id of a donation form part.
Id	GUID	true	Id of a donation.

Possible Responses
Status	Body	Description
403 Forbidden		User does not have access to the specified donation.
404 Not Found		No donation was found by the specified Id.
400 Bad Request	Error[]	The donation payment was not properly completed in Blackbaud secured payment or the donation has already been marked as completed. Possible Errors: • InvalidOperation (102) • BBSPTransactionNotProcessed (203)
200 OK	Donation	Ensures the user has access to this donation by finding the Id in their session. If so, loads the donation out of the database. Ensures the donation is a credit card donation and not already in a completed state. If not, then confirms with Blackbaud secured payment whether the donation is paid. If so, updates the donation status and sends the acknowledgment email.

Example Responses:

Name: Success

Status: 200 OK

Body:

                        {
	"Donor":{
		"Address":{
			"City":"Columbia",
			"Country":"United States",
			"PostalCode":"29212",
			"State":"SC",
			"StreetAddress":"123 Main St."
			},
		"EmailAddress":"john.doe@blackbaud.com",
		"FirstName":"John",
		"LastName":"Doe",
		"Phone":"555-555-5555",
		"Title":"Mr."
		},
	"Gift":{
		"Designations":
			[{
			"Amount":5,
			"DesignationId":"3439a5c7-9977-4f9c-ba11-fadfb8144d35"
			}],
		"FinderNumber":0,
		"IsAnonymous":false,
		"PaymentMethod":1,
		"Comments":"Gift comments here.",
    "CreateGiftAidDeclaration":false,
		"Attributes":
			[{
			"AttributeId":"BD18B3FD-B382-4183-A415-8F84B1E0E411",
			"Value":"Volunteer;Member;Alumni"
			},
			{
			"AttributeId":"3607C77D-19DC-4EE0-A0CD-A352762A8EF0",
			"Value":"1985"
			}],
      "Recurrence":
        {
        "DayOfMonth":26,
        "DayOfWeek":null,
        "EndDate":null,
        "Frequency":2,
        "Month":null,
        "StartDate":"\/Date(1337227200000-0400)\/"
        },
      "Tribute":
      {
      "Acknowledgee":
        {
        "AddressLines":"123 Sunset ln.",
        "City":"Charleston",
        "Country":"USA",
        "Email":"email@address.com",
        "FirstName":"Joe",
        "LastName":"Schmo",
        "Phone":"123-123-1234",
        "PostalCode":"29482",
        "State":"SC"
        },
      "TributeDefinition":
        {
        "Description":"New tribute",
        "FirstName":"John",
        "LastName":"Hancock",
        "Type":"Tribute"
        },
      "TributeId":null
      }
	},
	"Id":"853f96be-bf08-4828-aefa-326a06e48d31","
	Origin":{
		"AppealId":"C3B20FD8-6A81-451E-BF78-D195E82B4CBF",
		"PageId":784,
		"PageName":"Sample Page"
		},
	"TransactionStatus":1
}

Description:

Name: Error

Status: 400 Bad Request

Body:

                        [
	{
		"ErrorCode":102,
		"Field":null,
		"Message":null
	}
]

{PartId}/Donation/{Id}/ConfirmationHtml - GET

Summary: Gets HTML for a confirmation screen for the completed donation.

Behavior: Ensures the user has access to this donation by finding the Id in their session. If so, loads the donation out of the database and merges the fields into the part’s confirmation block.

Parameters
Name	Type	Required	Description
PartId	Integer	true	Id of a donation form part.
Id	GUID	true	Id of a donation.

Possible Responses
Status	Body	Description
403 Forbidden		User does not have access to the specified donation.
404 Not Found		No donation was found by the specified Id.
200 OK	String	Returns a string containing the HTML block of the confirmation with the donation fields merged in.

Example Responses:

Name: Success

Status: 200 OK

Body:

                        “<div>;Thank you for donating $10.00.</div>;”

Donation API - Enums

PaymentMethod

CreditCard (0)
BillMeLater (1)

TransactionStatus

Pending (0)
Completed (1)

ErrorCode

RequiredFieldMissing (101) A required field was not supplied.
InvalidFieldSupplied (102) A field was provided which is not allowed, given the values of other fields.
ValueBelowMinimum (103)
ValueExceedsMaximum (104)
ValueNotAllowed (105) Generic problem with the value of the field.
RecordNotFound (106) No record was found for the specified id.
ExceedsMaximumLength (107) The value contained too many characters.
InvalidOperation (201) The operation is not valid for the current state of the object.
BBSPBeginTransactionFailed (202) The initial request to Blackbaud secured payment to begin the transaction failed.
BBSPTransactionNotProcessed (203) Blackbaud secured payment returned that the transaction has not been paid.
BBSPTransactionGatewayDeclined (204) Blackbaud secured payment returned that the gateway declined the transaction.
BBSPTransactionValidationError (205) Blackbaud secured payment returned that the transaction had a validation error.
BBSPTransactionProcessingError (206) Blackbaud secured payment returned that the transaction had a processing error.

DayOfWeek

Sunday (0)
Monday (1)
Tuesday (2)
Wednesday (3)
Thursday (4)
Friday (5)
Saturday (6)

RecurrenceFrequency

Weekly (1) Represents a weekly recurrence frequency.
Monthly (2) Represents a monthly recurrence frequency.
Quarterly (3) Represents a quarterly recurrence frequency.
Annually (4) Represents an annual recurrence frequency.