ammado API

About this document

ammado provides a global donations and engagement platform, one that accepts donations from all around the world – in more than 70 currencies and through all major and many local payment methods. ammado has created several tools that the fundraisers and nonprofits can use to accept donations on their websites:

History

Changes to required fields (validation rules, new fields, etc) will result in major version increment. New non-required fields and other non-breaking changes will result in minor version increment. Only the major version number will be included in the endpoint URLs, e.g. version 1.5 of /donate endpoint would be located at https://api.ammado.com/v1/donate.

Introduction

The ammado API currently supports the following methods:

To use the ammado API, you need to obtain an API key. Please send your API key request with your donation requirements to support@ammado.com.

Supported browsers

Where API interactions require donors to visit pages on ammado, we will endevour to provide backward and forward browser compatibility. However, currently we only provide A-grade support for the following browsers:

Privacy

At ammado we believe that donors should decide if they want to reveal their details to nonprofits. We may ask for certain details – such as a name and email address – to authorize credit card transactions and send receipts. We will not store such details unless explicitly provided during the donation process.

As an additional safeguard, we allow donors to make their donations anonymously. This means that even if they provide full details (name, email address and so forth), we still present them with an option to hide all identifying details from nonprofits during checkout.

We encourage you to respect these options and we recommend that you do not rely on donor's data being visible in your nonprofit/fundraiser statements. Should you require these details, you should collect them on your own (please ensure that you obtain the donor's permission before doing this).

Please also review our Giving Policy and Privacy Policy.

Automatic status updates

You can receive automatic updates on the status of donations made through your application. Ammado can "push" such update notifications to a defined designated URL. Please note that these automatic notifications will only be provided where those donations originated using your API key.

When the status of a donation changes (including the status of repeat donations), an automatic notification will be sent to your defined URL. The notification will contain the same information as that provided in the response from the /order/{guid} endpoint.

Please contact support@ammado.com if you wish to avail of automatic status updates.

Service availability

We will try to ensure maximum availability of the API, however, occassionally we will have to turn it off for upgrades and maintenance. We will be announcing planned outages on Twitter via @ammadoDev. During downtime periods all of the API endpoints will be returning 503 Service Temporarily Unavailable HTTP status.

/donate endpoint

To get started with the simple version of the /donate endpoint, you will need some practical HTML knowledge and a general understanding of web standards.

You may also use the more advanced version which involves submitting the donation details using a background request to create an order and then redirecting the donor to the checkout page with a simple GET request. This approach means that you can:

Donations using a simple form

The solution requires you to add an HTML form on your website (1) with several parameters to pass minimal amount of information to ammado.

Once the data is submitted from your website to ammado, we present the donor with a screen offering a choice of payment methods (2) and an option to enter some more details. Credit card payments are then handled by the WorldPay payment gateway (3).

After the donor successfully confirms the transaction, they are returned to a success page on your website (4). The funds received are distributed directly to nonprofits every month. For more information on this process, see our Giving Policy and FAQ.

  1. Donor submits form to ammado
  2. Donor is presented with a payment method list
  3. Donor enters credit card details
  4. Donor is returned to your website
You need to implement steps (1) and (4) - ammado handles the payment processing in steps (2) and (3).

To start raising funds on your website you need to pick a nonprofit or a fundraiser (alternatively, you may create your own fundraiser) and create an HTML form to pass the beneficiary and some other basic information to ammado.

See below for the parameter reference and a complete implementation example. Please contact support@ammado.com or tweet @ammadoDev if you have any comments, questions or suggestions.

Donations using background call

For this approach, you may use any method to collect the information (1) to make a donation on your website. Once you have the required data (beneficiary, amount, donor email), your server needs to make a request to the endpoint URL (2). If there are no validation errors, we will send you back a JSON object, which contains two properties: orderId and checkoutUrl.

  1. Donor enters details on your website
  2. Your website makes a background call to ammado
  3. Donor is redirected to a payment method selection screen
  4. Donor enters credit card details
  5. Donor is returned to your website
You need to implement steps (1), (2) and (5) - ammado handles the payment processing in steps (3) and (4).

You must redirect the donor to the checkoutUrl, where we will present the donor with a screen offering a choice of payment methods and an option enter some more details (3). Credit card payments are then handled by the WorldPay payment gateway (4).

After the donor successfully confirms the transaction, they are returned to a success page on your website (5). The funds received are distributed directly to nonprofits every month. For more information on this process, see our Giving Policy and FAQ.

See below for the parameter reference and a sample background request. Please contact support@ammado.com or tweet @ammadoDev if you have any comments, questions or suggestions.

Response format - success

The successful response content type will be application/json with a UTF-8 charset. The HTTP status code will be 201 Created. Any response, other than a JSON object with success data and HTTP status 201 Created should be treated as a failure.

The response JSON will contain the following fields:

orderId
A string which you can use with /order/{guid} endpoint to check the order status.
checkoutUrl
A string URL where you must redirect the donor to complete the transaction.

Note that if the donor does not complete the checkout process, the order will be removed from the system and subsequent calls to the /order/{guid} endpoint may result in a 404 Not Found.

Response format - validation failure

The response content type will be application/json with a UTF-8 charset. The HTTP status code will be 400 Bad Request.

The failure response JSON object will contain the following fields:

errorCodes
An array of error codes.

Parameter reference

apiKey (required)

Allowed values:
A string with your exact API key, as provided by ammado.

To obtain an API key, please contact support@ammado.com with your donation requirements.

Passing an invalid API key will result in a fatal error.

beneficiaryId (required)

Allowed values:
The permalink identifier of a nonprofit or a fundraiser.
Validation error codes:

1101 Beneficiary is invalid.

Will be returned if the provided value is empty or does not match a nonprofit/fundraiser on ammado.

1102 Beneficiary does not accept donations.

Will be returned if the provided value returns a nonprofit that is not enabled to accept donations or a fundraiser that has ended.

The nonprofit/fundraiser identifier is the number (3+ digits) in the last component of the path of the permalink. You can find the permalink option in the "Share this" section on the nonprofit/fundraiser profile page (right-hand column). Examples:

comment (introduced in v1.14)

Allowed values:
String, up to 1000 (Unicode) characters.
Default value:
Empty (i.e. no comment)
Validation error codes:

1802 Comment too long (max 1000 characters).

Will be returned if the value is longer than 1000 (Unicode) characters.

This parameter will allow donors to leave a comment and to display it in donations statements and statement exports.

currencyCode

Allowed values:
A three letter string representing an ISO code of one of the supported currencies.
Default value:
EUR
Validation error codes:

1201 Unsupported currency.

Will be returned if the provided value is not exactly one of the supported ISO currency codes.

The values for this parameter are not case sensitive.

You may retrieve the supported currency list with minimum and maximum donation amounts using the /currencies endpoint. The list may change without notice or increment in major version number.

You may provide the user with an option to select the currency. However, it is your responsibility to ensure the correct validation of supported currencies and their donation amount limits.

In case you have a fixed currency, you should use an <input type="hidden" /> for this field.

disableRepeatDonations (introduced in v1.13)

Allowed values:
true or false
Default value:
false
Validation error codes:

2501 Invalid parameter value.

Will be returned if the provided value is not exactly true or false.

If you do not wish donors to set up repeat donations, set the value of this parameter to true.

donationAmount (required)

Allowed values:
Valid numeric value.
Validation error codes:

1301 Donation amount is invalid.

Will be returned when the value passed is empty or not a valid number.

1302 Donation amount too small. Minimum amount {currency}{minAmount}.

Will be returned when the amount is less than the minimum amount for the provided currencyCode.

If the error is displayed on ammado - the {currency} and {minAmount} will be replaced with relevant values.

1303 Donation amount too large. Maximum amount {currency}{maxAmount}.

Will be returned when the amount is more than the maximum amount for the provided currencyCode.

If the error is displayed on ammado - the {currency} and {maxAmount} will be replaced with relevant values.

Only the dot (".") character is recognized as a valid decimal separator. All comma (",") characters are ignored (i.e. "1,000" will be interpreted as one thousand).

Most of the currencies support 2 decimal spaces. However, some currencies may support 0 to 3 decimal spaces. All extra decimals will be rounded to the supported number of spaces.

You may provide the end user with a choice of predefined amounts (e.g. using a list of radio inputs). In this case, you may have two donationAmount parameter values submitted, if you provide an "other amount" freeform input. You must ensure that one of these values is empty. You should progressively enhance the form using Javascript to disable the custom value input. See the sample implementation.

For the allowed minimum/maximum donation amounts, please see the supported currency list.

donorEmail (required)

Allowed values:
Valid email address, up to 100 characters.
Validation error codes:

1401 You must provide a valid email address.

Will be returned if there is no email provided.

1402 Email address must be formatted correctly (for example jsmith@example.com).

Will be returned if the provided value does not pass the following regular expression test:

^[\._a-zA-Z0-9!#\$%&'\*\+\-/=\?\^`\{\|\}~]+@[_a-zA-Z0-9-]+(\.[_a-zA-Z0-9-]+)+$

1403 Email provided was too long (max 100 characters).

Will be returned if the value is longer than 100 (Unicode) characters.

You must provide a way for the donors to use their own email address for the donation.

You may use a hidden field for donorEmail, when the form is implemented inside a system that requires authentication (e.g. a company intranet).

donorFirstName (required, only when isGiftAidDonation is true)

Allowed values:
String, up to 100 characters.
Validation error codes:

1503 Please enter a first name.

Will be returned "only" if if isGiftAidDonation is set to true.

1501 Sorry, the first name you entered does not seem to be valid. Please enter a name between 1 and 100 characters long. Some characters may not be valid.

Invalid characters: < > $ @ # etc.

1502 First name too long (max 100 characters).

Will be returned if the value is longer than 100 characters.

The first and last name of the donor will appear on the nonprofit statement pages, if the donor does not select an option to donate anonymously during checkout. If you are supporting Gift Aid requests, you must provide a way for the donors to enter a first name.

donorLastName (required, only when isGiftAidDonation is true)

Allowed values:
String, up to 100 characters.
Validation error codes:

1603 Please enter a last name.

Will be returned "only" if if isGiftAidDonation is set to true.

1601 Sorry, the last name you entered does not seem to be valid. Please enter a name between 1 and 100 characters long. Some characters may not be valid.

Invalid characters: < > $ @ # etc.

1602 Last name too long (max 100 characters).

Will be returned if the value is longer than 100 characters.

The first and last name of the donor will appear on the nonprofit statement pages, if the donor does not select an option to donate anonymously during checkout. If you are supporting Gift Aid requests, you must provide a way for the donors to enter a last name.

onSuccess

Allowed values:
A URL on your website that will handle the success message.
Default value:
empty
Validation error codes:
None - invalid values are silently ignored.

The URL must include the FQDN and full path to the success page. The URL must match the domain list associated with your API key - please contact support@ammado.com to define the domain white-list.

You may leave this parameter empty. In case the URL is invalid or empty, the donor will be presented with a standard ammado "Thank You" page.

After the donation is completed, the donor will be redirected to the URL provided in this parameter. The following values will be passed along with in the query string:

donationAmount

A number using a dot "." as a decimal separator, with all trailing decimal zeroes trimmed.

Note: donations made on ammado can have a maximum of 2 decimal spaces.

currencyCode
Uppercase three letter code of the currency used in the transaction.
orderId
A reference GUID of the order - hexadecimal uppercase string, formatted with dashes. You may use the /order/{guid} endpoint to check the status of the order.
signature

A SHA1 hash (uppercase hexadecimal string) of amount multiplied by 100, currency code, order ID and your shared secret.

Example:

  • Donation amount: 25
  • Currency: EUR
  • Order ID: 63E41FF8-4441-497E-A2BC-3550926C4CB0
  • Secret: wikil34k
  • Signature: SHA1("2500EUR63E41FF8-4441-497E-A2BC-3550926C4CB0wikil34k") = BE2991F1E3EE9D45B1164FB01B4213E9D543DF8A
isAnonymous (introduced in v1.1)

Donor's preference for anonymity, selected during donation.

The value will be true, if donor would like his details to not be stored or false if the donor does not opt-out.

repeatsEvery (introduced in v1.7)

Donor's preference for recurring donation frequency, selected during donation. This parameter will not be included, unless the donor selects to repeat the donation automatically.

The value will be one of [OneWeek|TwoWeeks|OneMonth|ThreeMonths|OneYear]

You should validate the correctness of the signature before storing the order data. You should check the validity of all the parameters (correct form and length) before passing them into the hashing method.

The data passed back to your website should only be considered as an advisory. The values which do not affect the signature may be added without incrementing the major version number.

onError

Allowed values:
A URL on your website that will handle the failure message.
Default value:
empty
Validation error codes:
None - invalid values are silently ignored.

The URL must include the FQDN and full path to the error page. The URL must match the domain list associated with your API key - please contact support@ammado.com to define the domain white-list.

You may leave this parameter empty. In case the URL is invalid or empty, the donor will be presented with standard ammado error handling pages.

The donor will be redirected to this URL upon validation or payment failures. An errorCode query string parameter will be passed. The value contained will be a 4 digit validation error code as outlined in this documentation (only used in simple form variant), or will contain 1000 if there was a payment error (used in simple form and background call variants).

In case of multiple errors, all the values will be passed, separated by a semicolon (";"), e.g. http://www.example.com/error.html?errorCode=1303;1401.

preferredLanguage (introduced in v1.10)

Allowed values:
Any valid IETF language tag, e.g. pt-BR for Portuguese (Brasil).
Default value:
empty
Validation error codes:
None - invalid values are treated as empty.

If this parameter is empty or the language is not supported, the language will be chosen based on the donor's browser setting. Failing that - English will be used as a fallback value.

The system will also try to match the closest supported language (e.g. de may be used when de-AT is requested).

The list of supported languages is visible on ammado homepage. It may change without notice or change in the API version.

donorCountryCode (required, only when isGiftAidDonation is true) (introduced in v1.20)

Allowed values:
A two letter ISO country code, e.g. GB for United Kingdom.
Default value:
Empty (i.e. no country code)
Validation error codes:

2910 Please enter a country.

Will be returned "only" if if isGiftAidDonation is set to true.

This parameter allows donation statements to update with the country of the donor. If this parameter is empty or the country code is not recognized, the country of the donor will not be included in donations statements. If you are supporting Gift Aid requests, you must provide a way for the donors to enter a country.

isGiftAidDonation (introduced in v1.21)

Allowed values:
true or false
Default value:
false
Validation error codes:

2911 Invalid parameter value.

Will be returned if the provided value is not exactly true or false.

This parameter is specific to the UK and requires you to provide donors - who must be UK tax payers - with a means to make a Gift Aid declaration. If the parameter is set to true, it means that the donor has confirmed this declaration. Note that the format of the Gift Aid declaration must conform to HMRC standards.

donorStreetAddress (required, only when isGiftAidDonation is true) (introduced in v1.21)

Allowed values:
String up to 100 characters.
Default value:
Empty
Validation error codes:

2901 Please enter a street address.

Will be returned "only" if isGiftAidDonation is set to true.

2902 Street address too long.

Will be returned if the value is longer than 100 characters.

2903 Sorry, the street address you entered does not seem to be valid. Please enter an address between 1 and 100 characters long. Some characters may not be valid. Invalid characters: < > $ @ # etc.

Will be returned if string contains non-alphanumeric characters.

This parameter allows donation statements to update with the street address of the donor. If this parameter is empty, the street address of the donor will not be included in donations statements. If you are supporting Gift Aid requests, you must provide a way for the donors to enter a street address.

donorCity (required, only when isGiftAidDonation is true) (introduced in v1.21)

Allowed values:
String up to 50 characters.
Default value:
Empty
Validation error codes:

2904 Please enter a city or town.

Will be returned "only" if isGiftAidDonation is set to true.

2905 City or town is too long (max 50 characters).

Will be returned if the value is longer than 50 characters.

2906 Sorry, the city or town you entered does not seem to be valid. Please enter a city or town between 1 and 50 characters long. Some characters may not be valid. Invalid characters: < > $ @ # etc.

Will be returned if string contains non-alphanumeric characters.

This parameter allows donation statements to update with the city or town of the donor. If this parameter is empty, the city or town of the donor will not be included in donations statements. If you are supporting Gift Aid requests, you must provide a way for the donors to enter a city or town.

donorPostalCode (required, only when isGiftAidDonation is true) (introduced in v1.21)

Allowed values:
String up to 50 characters.
Default value:
Empty
Validation error codes:

2907 Please enter a postal/ZIP code.

Will be returned "only" if isGiftAidDonation is set to true.

2908 Postal/ZIP code is too long (max 50 characters).

Will be returned if the value is longer than 50 characters.

2909 Sorry, the postal/ZIP code you entered does not seem to be valid. Please enter a postal/ZIP code between 1 and 50 characters long. Some characters may not be valid. Invalid characters: < > $ @ # etc.

Will be returned if string contains non-alphanumeric characters.

This parameter allows donation statements to update with the postal/ZIP code of the donor. If this parameter is empty, the postal/ZIP code of the donor will not be included in donations statements. If you are supporting Gift Aid requests, you must provide a way for the donors to enter a postal/ZIP code.

Sample implementation (simple form)

This sample demonstrates the minimum possible form that can be sumitted to the /donate endpoint.

<form method="post" action="https://api.ammado.com/v1/donate" accept-charset="utf-8">
	<div>
		<label for="donorEmail">Email:</label>
		<input type="email" name="donorEmail" id="donorEmail" value="" />
	</div>

	<fieldset>
		<div>
			<input type="radio" name="donationAmount" id="amount10" value="10" />
			<label for="amount10">€10</label>
		</div>

		<div>
			<input type="radio" name="donationAmount" id="amount25" value="25" />
			<label for="amount25">€25</label>
		</div>

		<div>
			<input type="radio" name="donationAmount" id="amount50" value="50" />
			<label for="amount50">€50</label>
		</div>

		<div>
			<input type="radio" name="donationAmount" id="amountOther" value="" />
			<label for="amountOther">Other</label>
			<input type="number" min="4" max="20000"
					name="donationAmount" id="customAmount" />
		</div>
	</fieldset>
	<input type="hidden" name="currencyCode" value="EUR" />
	<input type="hidden" name="beneficiaryId" value="112794" />
	<input type="hidden" name="apiKey" value="C41E20A0-E2B4-4F16-A414-401DBAC282BD" />
	
	<button type="submit">Donate</button>
</form>
<script>
	// example of how pre-defined amounts can be handled in JS
	var handleClick = function(e)
	{
		if (!e) var e = window.event;
		var input = e.target || e.srcElement;
		if (input.name == 'donationAmount')
		{
			var custom = document.getElementById('customAmount');
			if (input.id == 'amountOther')
			{
				custom.removeAttribute('disabled');
				custom.focus();
			}
			else if (input.id != 'customAmount')
			{
				custom.setAttribute('disabled', 'disabled');
			}
		}
	}
	var inputs = document.getElementsByTagName('input');
	for (var i = inputs.length - 1; i >= 0; i--)
	{
		inputs[i].onclick=handleClick;
	}
	
	// only disable the input if Javascript is available!
	if (!document.getElementById('amountOther').checked) {
		document.getElementById('customAmount').setAttribute('disabled', 'disabled');
	}
</script>

Sample background request

curl -X POST \
	-H "Accept: application/x-ammado-json, application/json, text/javascript, */*; q=0.01" \
	-d "apiKey=C41E20A0-E2B4-4F16-A414-401DBAC282BD" \
	-d "donorEmail=jsmith@example.com" \
	-d "beneficiaryId=112794" \
	-d "currencyCode=EUR" \
	-d "donationAmount=10" \
	-d "onSuccess=http://www.example.com/success" \
	https://api.ammado.com/v1/donate

Sample success response to a background request

Note: the sample is formatted for clarity - all unnecessary whitespace characters will be removed in the real response.

{
	"orderId":"2B622BF4-6DBB-4696-9A5A-A74E3A2FDCA3",
	"checkoutUrl":"https://api.ammado.com/pay/2B622BF4-6DBB-4696-9A5A-A74E3A2FDCA3?apiKey=6BDB1166-EBDA-4377-B7CA-8E792B09F2AB"
}

Sample validation failure response to a background request

The following response would be received if there is no email address and no donation amount provided:

{"errorCodes":[1301,1401]}

/giftcards endpoint

To get started with the simple version of the /giftcards endpoint, you will need some practical HTML knowledge and a general understanding of web standards.

You may also use the more advanced version which involves submitting the gift card details using a background request to create an order and then redirecting the purchaser to the checkout page with a simple GET request. This approach means that you can:

Purchasing Donation Gift Cards using a simple form

The solution requires you to add an HTML form on your website (1) with several parameters to pass minimal amount of information to ammado.

Once the data is submitted from your website to ammado, we present the purchaser with a screen offering a choice of payment methods (2) and an option to enter some more details. Credit card payments are then handled by the WorldPay payment gateway (3).

After the purchaser successfully confirms the transaction, they are returned to a success page on your website (4). The gift card book created is immediately available for viewing on the API keyholder’s site.

  1. Purchaser submits form to ammado
  2. Purchaser is presented with a payment method list
  3. Purchaser enters credit card details
  4. Purchaser is returned to your website
You need to implement steps (1) and (4) - ammado handles the payment processing in steps (2) and (3).

To start allowing the purchase of gift cards on your website, you need to create an HTML form to pass some basic information to ammado.

See below for the parameter reference and a complete implementation example. Please contact support@ammado.com or tweet @ammadoDev if you have any comments, questions or suggestions.

Purchasing gift cards using a background call

For this approach, you may use any method to collect the information (1) to purchase gift cards on your website. Once you have the required data (giftCardValue, giftCardQuantity , purchaserEmail), your server needs to make a request to the endpoint URL (2). If there are no validation errors, we will send you back a JSON object, which contains two properties: orderId and checkoutUrl.

  1. Purchaser enters details on your website
  2. Your website makes a background call to ammado
  3. Purchaser is redirected to a payment method selection screen
  4. Purchaser enters credit card details
  5. Purchaser is returned to your website
You need to implement steps (1), (2) and (5) - ammado handles the payment processing in steps (3) and (4).

You must redirect the purchaser to the checkoutUrl, where we will present the purchaser with a screen offering a choice of payment methods and an option to enter some more details (3). Credit card payments are then handled by the WorldPay payment gateway (4).

After the purchaser successfully confirms the transaction, they are returned to a success page on your website (5). The gift card book created is immediately available for viewing on the API keyholder’s site.

See below for the parameter reference and a sample background request. Please contact support@ammado.com or tweet @ammadoDev if you have any comments, questions or suggestions.

Response format - success

The successful response content type will be application/json with a UTF-8 charset. The HTTP status code will be 201 Created. Any response, other than a JSON object with success data and HTTP status 201 Created should be treated as a failure.

The response JSON will contain the following fields:

orderId
A string which you can use with the /order/{guid} endpoint to check the order status.
checkoutUrl
A string URL where you must redirect the purchaser to complete the transaction.

Note that if the purchaser does not complete the checkout process, the order will be removed from the system and subsequent calls to the /order/{guid} endpoint may result in a 404 Not Found.

Response format - validation failure

The response content type will be application/json with a UTF-8 charset. The HTTP status code will be 400 Bad Request.

The failure response JSON object will contain the following fields:

errorCodes
An array of error codes.

Parameter reference

apiKey (required)

Allowed values:
A string with your exact API key, as provided by ammado.

To obtain an API key, please contact support@ammado.com with your requirements.

Passing an invalid API key will result in a fatal error.

giftCardValue (required)

Allowed values:
Valid numeric value.
Validation error codes:

3201 Gift Card amount is invalid.

Will be returned when the value passed is not a valid number.

3202 Gift Card amount too small. Minimum amount {currency}{minAmount}.

Will be returned when the total gift card book value {giftCardBookValue}*{giftCardBookQuantity} is less than the minimum amount for the provided currencyCode.

If the error is displayed on ammado - the {currency} and {minAmount} will be replaced with relevant values.

3203 Gift Card amount too large. Maximum amount {currency}{maxAmount}.

Will be returned when the total gift card book value {giftCardBookValue}*{giftCardBookQuantity} is more than the maximum amount for the provided currencyCode.

If the error is displayed on ammado - the {currency} and {maxAmount} will be replaced with relevant values.

This parameter will allow purchasers to specify the value of “each” gift card in their gift card book. It should “always” be used in conjunction with the currencyCode parameter and the giftCardQuantity parameter. You should provide a suitable label for this field such as “Value per gift card:”

Only the dot (".") character is recognized as a valid decimal separator. All comma (",") characters are ignored (i.e. "1,000" will be interpreted as one thousand).

Most of the currencies support 2 decimal spaces. However, some currencies may support 0 to 3 decimal spaces. All extra decimals will be rounded to the supported number of spaces.

You may provide the end user with a choice of predefined amounts (e.g. using a list of radio inputs). In this case, you may have two giftCardValue parameter values submitted, if you provide an "other amount" freeform input. You must ensure that one of these values is empty. You should progressively enhance the form using Javascript to disable the custom value input. See the sample implementation.

For the allowed minimum/maximum donation amounts, please see the supported currency list.

giftCardQuantity (required)

Allowed values:
Valid numeric value.
Validation error codes:

3301 Gift Card quantity is invalid.

Will be returned when the value passed is empty or not a valid number.

Validation error codes:

3302 Gift Card quantity is too large.

Will be returned when the value passed is bigger than 1000.

This parameter will allow purchasers to specify the quantity of gift cards in their gift card book. It should “always” be used in conjunction with the currencyCode parameter and the giftCardValue parameter. You should provide a suitable label for this field such as “Quantity of gift cards:”.

You may provide the end user with a choice of predefined amounts (e.g. using a list of radio inputs). In this case, you may have two giftCardQuantity parameter values submitted, if you provide an "other quantity" freeform input. You must ensure that one of these values is empty. You should progressively enhance the form using Javascript to disable the custom value input. See the sample implementation.

purchaserEmail (required)

Allowed values:
Valid email address, up to 100 characters.
Validation error codes:

1401 You must provide a valid email address.

Will be returned if there is no email provided.

1402 Email address must be formatted correctly (for example jsmith@example.com).

Will be returned if the provided value does not pass the following regular expression test:

^[\._a-zA-Z0-9!#\$%&'\*\+\-/=\?\^`\{\|\}~]+@[_a-zA-Z0-9-]+(\.[_a-zA-Z0-9-]+)+$

1403 Email provided was too long (max 100 characters).

Will be returned if the value is longer than 100 (Unicode) characters.

1404 Email address is owner of unsupported ammado account (company or nonprofit).

Will be returned if the email address provided is owner of a company or nonprofit ammado account.

This email address will be established as the "owner" of the gift card book purchased. You must provide a way for the purchaser to use their own email address for the purchase.

You may use a hidden field for purchaserEmail, when the form is implemented inside a system that requires authentication (e.g. a company intranet).

currencyCode

Allowed values:
A three letter string representing an ISO code of one of the supported currencies.
Default value:
EUR
Validation error codes:

1201 Unsupported currency.

Will be returned if the provided value is not exactly one of the supported ISO currency codes.

The values for this parameter are not case sensitive.

You may retrieve the supported currency list with minimum and maximum donation amounts using the /currencies endpoint. The list may change without notice or increment in major version number.

You may provide the user with an option to select the currency. However, it is your responsibility to ensure the correct validation of supported currencies and their donation amount limits.

In case you have a fixed currency, you should use an <input type="hidden" /> for this field.

description

Allowed values:
String, up to 30 (Unicode) characters.
Default value:
Empty (i.e. no description).
Validation error codes:

1801 Description field can have max 30 characters.

Will be returned if the value is longer that 30 characters.

This parameter will allow purchasers to provide a short description of the purpose of the donation gift cards. The description will display alongside the gift card book details in the “gift cards” section of the API keyholder’s profile on ammado.com.

Note: the description must not contain any HTML.

partnerCode

Allowed values:
String, up to 20 alphanumeric (Unicode) characters.
Default value:
Empty (i.e. no partner code).
Validation error codes:

2701 Invalid parameter value.

Will be returned if the provided value is too long, contains non-alphanumeric characters or does not match any existing partner code.

This parameter allows gift cards to be purchased in conjunction with an ammado "partner" – generally to facilitate revenue-sharing. To obtain a partner code, please contact support@ammado.com.

preferredLanguage

Allowed values:
Any valid IETF language tag, e.g. pt-BR for Portuguese (Brasil).
Default value:
Empty (i.e. no preferred language).
Validation error codes:
None - invalid values are treated as empty.

This parameter allows you to specify the language in which you wish to conduct the transaction – as well as the language of the subsequent email communications.

If this parameter is empty or the language is not supported, the language will be chosen based on the donor's browser setting. Failing that - English will be used as a fallback value.

The system will also try to match the closest supported language (e.g. de may be used when de-AT is requested).

The list of supported languages is visible on the ammado homepage. It may change without notice or change in the API version.

purchaserCountryCode

Allowed values:
A two letter ISO country code, e.g. GB for United Kingdom.
Default value:
Empty (i.e. no country code)
Validation error codes:
None - invalid values are treated as empty.

This parameter allows for the country of the purchaser to be made available for reporting through the /giftcards/{bookCode} endpoint.

If this parameter is empty or the country code is not recognized, the country of the purchaser will not be included in reports.

onSuccess

Allowed values:
A URL on your website that will handle the success message.
Default value:
Empty.
Validation error codes:
None - invalid values are silently ignored.

The URL must include the FQDN and full path to the success page. The URL must match the domain list associated with your API key - please contact support@ammado.com to define the domain white-list.

You may leave this parameter empty. In case the URL is invalid or empty, the purchaser will be presented with a standard ammado "Thank You" page.

After the transaction is completed, the purchaser will be redirected to the URL provided in this parameter. The following values will be passed along with the query string:

giftCardBookCode

This is the unique code of the gift card book purchased - a string up to 6 (Unicode) characters. You may use the /giftcards/{bookCode} endpoint to check the status of the gift card book.

giftCardBookAmount

A number using a dot "." as a decimal separator, with all trailing decimal zeroes trimmed.

This is the value of the gift card book purchased i.e. giftCardValue x giftCardQuantity.

giftCardValue

A number using a dot "." as a decimal separator, with all trailing decimal zeroes trimmed.

giftCardQuantity

A number with no decimals.

currencyCode
Uppercase three letter code of the currency used in the transaction.
orderId
A reference GUID of the order - hexadecimal uppercase string, formatted with dashes. You may use the /order/{guid} endpoint to check the status of the order.
signature

A SHA1 hash (uppercase hexadecimal string) of gift card value, gift card quantity, currency code, order ID and your shared secret.

Example:

  • Gift card book code: 227TPQ
  • Gift card quantity: 10
  • Currency: EUR
  • Order ID: 55E3D30C-2844-4D08-A430-6A39E0E2CCA0
  • Secret: wikil34k
  • Signature: SHA1("227TPQ10EUR55E3D30C-2844-4D08-A430-6A39E0E2CCA0wikil34k") = B371860CD9558D970AC454951CC8896226F950F7

You should validate the correctness of the signature before storing the order data. You should check the validity of all the parameters (correct form and length) before passing them into the hashing method.

The data passed back to your website should only be considered as an advisory. The values which do not affect the signature may be added without incrementing the major version number.

onError

Allowed values:
A URL on your website that will handle the failure message.
Default value:
Empty.
Validation error codes:
None - invalid values are silently ignored.

The URL must include the FQDN and full path to the error page. The URL must match the domain list associated with your API key - please contact support@ammado.com to define the domain white-list.

You may leave this parameter empty. In case the URL is invalid or empty, the purchaser will be presented with standard ammado error handling pages.

The purchaser will be redirected to this URL upon validation or payment failures. An errorCode query string parameter will be passed. The value contained will be a 4 digit validation error code as outlined in this documentation (only used in simple form variant), or will contain 1000 if there was a payment error (used in simple form and background call variants).

In case of multiple errors, all the values will be passed, separated by a semicolon (";"), e.g. http://www.example.com/error.html?errorCode=1303;1401.

Sample implementation (simple form)

This sample demonstrates the minimum possible form that can be submitted to the /giftcards endpoint.

<form method="post" action="https://api.ammado.com/v1/giftcards" accept-charset="utf-8">
	<div>
		<label for="purchaserEmail">Email:</label>
		<input type="email" name="purchaserEmail" id="purchaserEmail" value="" />
	</div>

	<div>
		<label for="giftCardQuantity ">Gift Card Quantity:</label>
		<input type="number" min="1" max="1000" name="giftCardQuantity " id="giftCardQuantity " value="" />
	</div>

	<fieldset>
		<div>
			<input type="radio" name="giftCardValue" id="value10" value="10" />
			<label for="amount10">€10</label>
		</div>

		<div>
			<input type="radio" name="giftCardValue" id="value25" value="25" />
			<label for="amount25">€25</label>
		</div>

		<div>
			<input type="radio" name="giftCardValue" id="value50" value="50" />
			<label for="amount50">€50</label>
		</div>

		<div>
			<input type="radio" name="giftCardValue" id="valueOther" value="" />
			<label for="valueOther">Other</label>
			<input type="number" min="4" max="20000"
					name="giftCardValue" id="customValue" />
		</div>
	</fieldset>

	<input type="hidden" name="apiKey" value="C41E20A0-E2B4-4F16-A414-401DBAC282BD" />
	
	<button type="submit">Buy Gift Cards</button>
</form>
<script>
	// example of how pre-defined amounts can be handled in JS
	var handleClick = function(e)
	{
		if (!e) var e = window.event;
		var input = e.target || e.srcElement;
		if (input.name == 'giftCardValue')
		{
			var custom = document.getElementById('customValue');
			if (input.id == 'valueOther')
			{
				custom.removeAttribute('disabled');
				custom.focus();
			}
			else if (input.id != 'customValue')
			{
				custom.setAttribute('disabled', 'disabled');
			}
		}
	}
	var inputs = document.getElementsByTagName('input');
	for (var i = inputs.length - 1; i >= 0; i--)
	{
		inputs[i].onclick=handleClick;
	}
	
	// only disable the input if Javascript is available!
	if (!document.getElementById('valueOther').checked) {
		document.getElementById('customValue').setAttribute('disabled', 'disabled');
	}
</script>

Sample background request

curl -X POST \
	-H "Accept: application/x-ammado-json, application/json, text/javascript, */*; q=0.01" \
	-d "apiKey=C41E20A0-E2B4-4F16-A414-401DBAC282BD" \
	-d "purchaserEmail=jsmith@example.com" \
	-d "giftCardQuantity=10" \
	-d "giftCardValue=5" \
	-d "onSuccess=http://www.example.com/success" \
	https://api.ammado.com/v1/giftcards

Sample success response to a background request

Note: the sample is formatted for clarity - all unnecessary whitespace characters will be removed in the real response.

{
	"orderId":"55E3D30C-2844-4D08-A430-6A39E0E2CCA0",
	"checkoutUrl":"https://api.ammado.com/pay/55E3D30C-2844-4D08-A430-6A39E0E2CCA0?apiKey=6BDB1166-EBDA-4377-B7CA-8E792B09F2AB"
}

Sample validation failure response to a background request

The following response would be received if there is no purchaser email address and invalid gift card quantity provided:

{"errorCodes":[1401,3301]}

/giftcards/{bookCode} endpoint

Gift card books can be in various states depending on when the gift card book was purchased or the usage rates of the gift cards within the book i.e. the gift card book may be fully or partially available (there are still some or all gift cards remaining), expiring soon (have 1 month until the expiry date is reached) or have already expired (gift card books have a default expiry period of 1 year).

You can use this endpoint to check the status of gift card books that were purchased with your API key using the /giftcards endpoint. You can also retrieve a link to the gift card book as well as the next available gift card within a book.

Parameter reference

apiKey (required)

Allowed values:
A string with your exact API key, as provided by ammado.

To obtain an API key, please contact support@ammado.com with your requirements.

Passing an invalid API key will result in a 403 Forbidden.

signature (required)

Allowed values:
A SHA1 hash (uppercase hexadecimal string) of the normalized gift card book code and your shared secret, using "." (dot) as a field separator character.
Validation error codes:

1901 Invalid signature.

Example:

  • Gift card code: AABBCC
  • Shared secret: wikil34k
  • Signature: SHA1("AABBCC.wikil34k") = 2B2E20DB2B56AEF347D8098B05621CD4C1C447EE

Response format

The response content type will be application/json with a UTF-8 charset. The response body will contain a JSON object with the details of the gift card book:

giftCardBookCode

A string up to 6 (Unicode) characters.

This is the unique code of the gift card book purchased.

giftCardBookStatus
A string with the status of the gift card book (see below).
giftCardBookExpireDate
A date of when the gift card book expires in ISO 8601 date (YYYY-MM-DD) format.
giftCardBookAmount

A number using a dot "." as a decimal separator, with all trailing decimal zeroes trimmed.

This is the value of the gift card book purchased i.e. giftCardValue x giftCardQuantity.

currencyCode
Uppercase three letter code of the currency used in the transaction.
giftCardValue

A number using a dot "." as a decimal separator, with all trailing decimal zeroes trimmed.

This is the value of each gift card within the gift card book.

giftCardQuantity

A number with no decimals.

This is the quantity of gift cards within the gift card book.

description
String, up to 30 (Unicode) characters.
giftCardBookURL

A website address on ammado.com.

This is the unique address of the gift card book purchased - access requires login on ammado.com.

nextAvailableGiftCardCode

A string up to 6 (Unicode) characters.

This is the unique code of the next available gift card in the book. If empty, the book has “no” available gift cards left.

partnerCode

String, up to 20 alphanumeric (Unicode) characters.

Displays if the gift cards were purchased in conjunction with an ammado "partner" – generally to facilitate revenue-sharing. Otherwise, this will be empty.

purchaserFirstName
The first name of the purchaser of the gift card book - if provided. String, up to 100 characters.
purchaserLastName
The last name of the purchaser of the gift card book - if provided. String, up to 100 characters.
purchaserEmail
The email address of the purchaser of the gift card book.
purchaserStreetAddress
The street address of the purchaser of the gift card book - if provided. String, up to 100 characters.
purchaserCity
The city of the purchaser of the gift card book - if provided. String, up to 50 characters.
purchaserZIPCode
The postal/ZIP code of the purchaser of the gift card book - if provided. String, up to 50 characters.
purchaserCountryCode
The country of the purchaser of the gift card book - if provided. A two letter ISO country code, e.g. GB for United Kingdom.

Note: new values may be added to the response object without increasing the major version number of the API.

giftCardBookStatus values

The value for the giftCardBookStatus will be exactly one of the following:

active
The gift card book has at least one gift card available.
redeemed
The gift card book has no gift cards available.
expired
The gift card book has expired - any remaining gift cards in the book are no longer valid.
payment_charged_back
The payment for the gift card book has been charged back by the credit/debit card company. Any remaining gift cards in the book are no longer valid and payments from redeemed gift cards will “not” be made to beneficiaries of gift card donations.
payment_sent_for_refund
The payment for the gift card book has been sent for a refund to the purchaser. Any remaining gift cards in the book are no longer valid and payments from redeemed gift cards will “not” be made to beneficiaries of gift card donations.
payment_refunded
The payment for the gift card book has been refunded to the purchaser. Any remaining gift cards in the book are no longer valid and payments from redeemed gift cards will “not” be made to beneficiaries of gift card donations.
payment_cancelled
The payment for the gift card book was cancelled by the purchaser, ammado or the Payment Processor. Any remaining gift cards in the book are no longer valid and payments from redeemed gift cards will “not” be made to beneficiaries of gift card donations.
error
An unexpected fatal error occured during processing. Any remaining gift cards in the book are no longer valid and payments from redeemed gift cards will “not” be made to beneficiaries of gift card donations.

Sample response

Note: the sample is formatted for clarity - all unnecessary whitespace characters will be removed in the real response.

'giftCardBookCode' => '98BBCG',
'giftCardBookStatus' => 'active',
'giftCardBookExpireDate' => '2017-03-23',
'giftCardBookAmount' => 500,
'giftCardValue' => 5,
'giftCardQuantity' => 100,
'currencyCode' => 'EUR',
'description' => '',
'giftCardBookURL' => 'https://www.ammado.com/member/1251/mygiftcards/98bbcg',
'nextAvailableGiftCardCode' => '8RHHGG',
'partnerCode' => '',
'purchaserFirstName' => Peter,
'purchaserLastName' => Frampton,
'purchaserEmail' => 'p.rampton@example.com',
'purchaserStreetAddress' => 'Lakeside Drive',
'purchaserCity' => 'London',
'purchaserZIPCode' => '',
'purchaserCountryCode' => 'GB'

/redeem endpoint

ammado Donation Gift Cards can be used to donate to nonprofits and fundraisers on ammado. To purchase Donation Gift Cards, please contact support@ammado.com with your requirements or you can use the /giftcards endpoint to allow users to purchase ammado Donation Gift Cards directly on your site.

You may use this endpoint as an incentive for the fundraisers you may create via the API.

Parameter reference

apiKey (required)

Allowed values:
A string with your exact API key, as provided by ammado.

To use this endpoint, your API key needs to be associated with an ammado account, which owns the vouchers purchased.

To obtain an API key, please contact support@ammado.com with your donation requirements.

Passing an invalid API key will result in a 403 Forbidden.

beneficiaryId (required)

Allowed values:
The permalink identifier of a nonprofit or a fundraiser.
Validation error codes:

1101 Beneficiary is invalid.

Will be returned if the provided value is empty or does not match a nonprofit/fundraiser on ammado.

1102 Beneficiary does not accept donations.

Will be returned if the provided value returns a nonprofit that is not enabled to accept donations or a fundraiser that has ended.

1103 Beneficiary restricted.

Will be returned if the beneficiary is not included in the whitelist applied to the voucher.

1106 "Kickstart" not available.

Will only be returned when kickstart parameter is set to true and the beneficiaryId is not a fundraiser that was created with the same API key, or if the fundraiser has already been kickstarted.

The nonprofit/fundraiser identifier is the number (3+ digits) in the last component of the path of the permalink. You can find the permalink option in the "Share this" section on the nonprofit/fundraiser profile page (right-hand column). Examples:

kickstart

Allowed values:
true or false
Default value:
false
Validation error codes:

1106 "Kickstart" not available.

Will only be returned when kickstart parameter is set to true and the beneficiaryId is not a fundraiser that was created with the same API key, or if the fundraiser has already been kickstarted.

2401 Invalid parameter value.

Will be returned if the provided value is not exactly true or false.

This parameter may be used to trigger the "kickstart" functionality on fundraisers. When it is set to true, you can only redeem vouchers by donating them to the fundraisers you created via the API with your own key.

In case of successful voucher redemption, the fundraiser profile on ammado site will display a promotional message, with the name of the voucher owner.

voucherCode (required)

Allowed values:
Alphanumeric code of the voucher to be redeemed.
Validation error codes:

2001 Invalid voucher.

Will be returned if the code is not provided or provided code is invalid or incorrectly formatted.

2002 Voucher not available for donation.

Will be returned if the voucher has already been redeemed, expired or cancelled.

The voucher codes must be normalized - all dashes and spaces should be removed, and the code should be uppercased.

comment (introduced in v1.22)

Allowed values:
String, up to 1000 (Unicode) characters.
Default value:
Empty (i.e. no comment)
Validation error codes:

1802 Comment too long (max 1000 characters).

Will be returned if the value is longer than 1000 (Unicode) characters.

This parameter will allow a comment to be associated with a gift card donation. If included, the comment will display in donation statements and statement exports.

signature (required)

Allowed values:
A SHA1 hash (uppercase hexadecimal string) of the beneficiary ID, normalized voucher code and your shared secret, using "." (dot) as a field separator character.
Validation error codes:

1901 Invalid signature.

Example:

  • Beneficiary ID: 112794
  • Voucher code: AAAA-BBBB-CCCC
  • Shared secret: wikil34k
  • Signature: SHA1("112794.AAAABBBBCCCC.wikil34k") = 94FD6328417E01924D4BF95E8108F0FB1BEDD298

Response format

Note: any response, other than a JSON object with success data and HTTP status 200 OK should be treated as a failure.

Success

The response content type will be application/json with a UTF-8 charset. The HTTP status code will be 200 OK.

The response for a successfully redeemed voucher is a JSON object containing the following fields:

donationAmount

A number using a dot "." as a decimal separator.

currencyCode
Uppercase three letter code of the currency used in the transaction.
orderId
A reference GUID of the order - hexadecimal uppercase string, formatted with dashes. You may use the /order/{guid} endpoint to check the status of the order.

Note: new values may be added to the response object without increasing the major version number of the API.

Validation failure

The response content type will be application/json with a UTF-8 charset. The HTTP status code will be 400 Bad Request.

The failure response JSON object will contain the following fields:

errorCodes
An array of error codes.

Sample request

The example assumes the shared secret to be wikil34k

curl -X POST \
	-d "apiKey=C41E20A0-E2B4-4F16-A414-401DBAC282BD" \
	-d "beneficiaryId=112794" \
	-d "voucherCode=AAAABBBBCCCC" \
	-d "signature=94FD6328417E01924D4BF95E8108F0FB1BEDD298" \
	https://api.ammado.com/v1/redeem

Sample success response

Note: the sample is formatted for clarity - all unnecessary whitespace characters will be removed in the real response.

{
	"orderId": "63E41FF8-4441-497E-A2BC-3550926C4CB0",
	"donationAmount": 25.00000000,
	"currencyCode": "EUR"
}

Sample validation failure response

The following response would be received if the beneficiaryId is not enabled for donations and the signature is calculated incorrectly:

{"errorCodes":[1102,1901]}

/currencies endpoint

ammado donations platform supports 70+ currencies. You can retrieve the full list, with donation amount ranges by making a GET request to the https://api.ammado.com/v1/currencies endpoint.

Parameter reference

apiKey (required)

Allowed values:
A string with your exact API key, as provided by ammado.

To obtain an API key, please contact support@ammado.com with your donation requirements.

Passing an invalid API key will result in a 403 Forbidden.

Response format

The response content type will be application/json with a UTF-8 charset. The response body will contain a JSON object with a list of supported currencies, where currency code will be used as a key and currency definition object will be its value.

Currency object fields:

currencyCode
The three letter ISO code, uppercase.
currencyName
Full name of the currency, in English.
minAmount
The minimum donation amount in this currency.
maxAmount
The maximum donation amount in this currency.
decimals
The number of decimal spaces that will be retained during donation in this currency (0 or 2).

Sample response

Note: the sample is formatted for clarity - all unnecessary whitespace characters will be removed in the real response.

{
	"currencies" :
	{
		"EUR" :
		{
			"currencyCode": "EUR",
			"currencyName": "Euro",
			"minAmount": 4,
			"maxAmount": 20000,
			"decimals": 2
		},
		"GNF":
		{
			"currencyCode": "GNF",
			"currencyName": "Guinea Franc",
			"minAmount": 25000,
			"maxAmount": 180000000,
			"decimals": 0
		},
		"USD" :
		{
			"currencyCode": "USD",
			"currencyName": "US Dollar",
			"minAmount": 5,
			"maxAmount": 27000,
			"decimals": 2
		}
	}
}

/order/{guid} endpoint

Donations or gift card purchases made on the ammado platform may sometimes be cancelled or refunded. You can use this endpoint to check the status of the orders that were made with your API key using the /donate, /redeem, /giftcards or Giving Widget setup endpoint endpoints. You can also retrieve details of repeat donations where the original donation was made using your API key.

Note: You can receive automatic updates on the status of donations made through your application. Ammado can "push" such update notifications to a defined designated URL. Please note that these automatic notifications will only be provided where those donations originated using your API key.

When the status of a donation changes (including the status of repeat donations), an automatic notification will be sent to your defined URL. The notification will contain the same information as the information provided in the response from the /order/{guid} endpoint. Please contact support@ammado.com if you wish to avail of automatic status updates.

Parameter reference

apiKey (required)

Allowed values:
A string with your exact API key, as provided by ammado.

To obtain an API key, please contact support@ammado.com with your donation requirements.

Passing an invalid API key will result in a 403 Forbidden.

Response format

The response content type will be application/json with a UTF-8 charset. The response body will contain a JSON object with the details of the order:

orderId
The reference GUID of the order - hexadecimal uppercase string, formatted with dashes.
paymentId
A number representing the unique payment identifier for the order. The paymentId will be 0 until the payment is initiated.
orderStatus
A string with the order status (see below).
orderDate
A string with the ISO 8601 date: YYYY-MM-DD.
currencyCode
A three letter ISO currency code.
donationAmount
A number using a dot "." as a decimal separator.
beneficiaryId
A list of permalink identifier numbers of nonprofits/fundraisers - in most cases there will be just one beneficiary in the array.
repeatId
If this is a repeat donation, this value returns the reference GUID of the original order - hexadecimal uppercase string, formatted with dashes. If this is not a repeat donation, this value will be empty.

Note: currencyCode and donationAmount fields may not be present if the order was created using the Giving Widget setup endpoint until the donor completes the donation. The donationAmount, beneficiaryId and repeatId fields will not be present for the gift card book orders created using the /giftcards endpoint.

orderStatus values

The value for the orderStatus will be exactly one of the following:

successful
The order was processed successfully. For donation orders, this means that monies can be or have already been disbursed to the beneficiaries.
pending
The transaction was successful but the order is still being processed. It can resolve into either successful or cancelled if/when ammado receive the monies. This state is generally only relevant for donations made using an ammado gift card.
refunded
The transaction was refunded to the purchaser. For donations, this means that no payment will be made to the beneficiaries. If the order relates to gift cards, this means that no gift cards will be valid and payments from redeemed gift cards will “not” be made to beneficiaries of gift card donations.
due_refund
The transaction is in the process of being refunded to the donor or purchaser. It will resolve into refunded once the donor or purchaser has received the monies.
charged_back
A credit card chargeback occured. For donations, this means that no payment will be made to the beneficiaries. If the order relates to gift cards, this means that no gift cards will be valid and payments from redeemed gift cards will “not” be made to beneficiaries of gift card donations.
cancelled
The transaction was cancelled by the donor or purchaser, ammado or the Payment Processor. For donations, this means that no payment will be made to the beneficiaries. If the order relates to gift cards, this means that no gift cards will be valid and payments from redeemed gift cards will “not” be made to beneficiaries of gift card donations.
error
An unexpected fatal error occured during processing. For donations, this means that no payment will be made to the beneficiaries. If the order relates to gift cards, this means that no gift cards will be valid and payments from redeemed gift cards will “not” be made to beneficiaries of gift card donations.

Sample response

Note: the sample is formatted for clarity - all unnecessary whitespace characters will be removed in the real response.

{
	"orderId": "63E41FF8-4441-497E-A2BC-3550926C4CB0",
	"paymentId": 635,
	"orderStatus": "successful",
	"orderDate": "2012-01-19",
	"donationAmount": 25.00000000,
	"currencyCode": "EUR",
	"beneficiaryId": [579, 696],
	"repeatId": "34952925-2563-46A3-90A2-86844FCC0B58"
}

/fundraiser endpoint

A fundraiser is an online facility provided by ammado primarily to raise funds for a particular cause. Fundraisers have their own unique web address on ammado that allows viewers to donate or promote the cause. You can create a fundraiser by making a POST request to the https://api.ammado.com/v1/fundraiser endpoint.

Parameter reference

apiKey (required)

Allowed values:
A string with your exact API key, as provided by ammado.

To use this endpoint, your API key needs to be associated with an ammado account, which will be the default moderator of the fundraiser.

To obtain an API key, please contact support@ammado.com with your donation requirements.

Passing an invalid API key will result in a 403 Forbidden.

beneficiaryId (required)

Allowed values:
The permalink identifier of a nonprofit.
Validation error codes:

1101 Beneficiary is invalid.

Will be returned if the provided value is empty or does not match a nonprofit on ammado.

1102 Beneficiary does not accept donations.

Will be returned if the provided value matches a nonprofit that is not enabled to accept donations.

1105 Limit reached.

Will be returned if the request contains more beneficiaries than the maximum allowed number for the fundraiser.

1107 Multiple beneficiaries from the same country.

Will be returned when creating a fundraiser with fundraiserType=world and the request contains more than one beneficiary from the same country (excluding the "Default" nonprofit).

The nonprofit identifier is the number (3+ digits) in the last component of the path of the permalink. You can find the permalink option in the "Share this" section on the nonprofit profile page (right-hand side). Examples:

(introduced in v1.15) You may pass this parameter multiple times with different values to create a fundraiser with multiple beneficiaries. See also: fundraiserType parameter.

For fundraiserType=world, the first nonprofit in the list will be considered the "default" beneficiary.

In case of validation errors, an additional dictionary will be returned, outlining specific validation error codes for each invalid beneficiary.

fundraiserAim (introduced in v1.22)

Allowed values:
String, up to 200 (Unicode) characters.
Default value:
Empty (i.e. default one "Help us make a difference!")
Validation error codes:

1804 Fundraiser aim is too long (max 200 characters).

Will be returned if the value is longer than 200 characters.

This parameter will populate the new fundraiser's aim. If parameter is left empty, the fundraiser will be created with the default aim "Help us make a difference!" or its localized equivalent.

Fundraiser aim represents the fundraiser mission statement or a 1 sentence short description. This short text will usually be displayed alongside the fundraiser name and avatar on the ammado site and in the embedded widget.

The fundraiser aim will also populate the open graph meta tag 'og:description' that the Facebook share component on the ammado site will use to prepopulate its text content.

Note: the fundraiser aim must not contain any HTML.

fundraiserDescription

Allowed values:
String, up to 1000 (Unicode) characters.
Default value:
Empty (i.e. no description)
Validation error codes:

1801 Description field can have max 1000 characters.

Will be returned if the value is longer that 1000 characters.

Fundraiser description should describe why the fundraiser was created - the story behind it. The description of a fundraiser appears on the ammado site on the fundraiser's Profile and Fundraising pages, below the main menu.

Note: the description must not contain any HTML.

fundraiserTitle (required)

Allowed values:
String, between 2 and 200 (Unicode) characters.
Validation error codes:

1701 Please enter a title for your fundraiser.

Will be returned if the provided value is empty.

1702 Name must be between 2 and 200 characters in length.

Will be returned if the provided value is shorter then 2 or longer then 200 characters.

Note: the title must not contain any HTML.

fundraiserType (introduced in v1.6)

Allowed values:
standard or world
Default value:
standard
Validation error codes:

2101 Invalid fundraiser type.

Will be returned if the provided value is not exactly standard or world.

This parameter determines how the donations are split up when there are multiple beneficiaries in a fundraiser. You can add additional beneficiaries via UI or invite them using the /fundraiser/{id}/beneficiaries endpoint. As of v1.15 you can also pass the beneficiaryId parameter more than once.

If the fundraiserType is world, each beneficiary will have to be from a unique country. Each donation will go to the single beneficiary that matches the donor's country. Otherwise, donations will go to the "default" beneficiary.

If the fundraiserType is standard, each beneficiary will receive an equal percentage of every donation.

isSearchable (introduced in v1.10)

Allowed values:
true or false
Default value:
true
Validation error codes:

2301 Invalid parameter value.

Will be returned if the provided value is not exactly true or false.

This parameter provides an option to create fundraisers in "hidden" mode, which prevents fundraisers from being discovered through search.

partnerCode (introduced in v1.17)

Allowed values:
String, up to 20 alphanumeric (Unicode) characters.
Default value:
Empty (i.e. no partner code)
Validation error codes:

2701 Invalid parameter value.

Will be returned if the provided value is too long, contains non-alphanumeric characters or does not match any existing partner code.

This parameter allows fundraisers to be tracked as originating from an ammado "partner" and can be used to facilitate revenue-sharing. To obtain a partner code, please contact support@ammado.com.

targetAmount

Allowed values:
Valid numeric value.
Default value:
Empty (i.e. no target)
Validation error codes:

1304 Target amount must be a number.

Will be returned when the provided value is not a valid number.

1305 The target amount must be greater than {currency}{minAmount}.

Will be returned when the amount is less than the minimum amount for the provided targetCurrencyCode.

1306 The target amount must not exceed 1000*{currency}{maxAmount}.

Will be returned when the amount is more than the maximum target amount for the provided targetCurrencyCode.

Only the dot (".") character is recognized as a valid decimal separator. All comma (",") characters are ignored (i.e. "1,000" will be interpreted as one thousand).

Most of the currencies support 2 decimal spaces. However, some currencies may support 0 to 3 decimal spaces. All extra decimals will be rounded to the supported number of spaces.

The minimum target amount is the same as minimum donation amount. The maximum target amount is 1000 times greater than maximum donation amount (1000*{currency}{maxAmount}). Please see supported currency list for donation amounts.

Note: if targetCurrencyCode is empty, Euro will be used as a default currency.

targetCurrencyCode

Allowed values:
A three letter string representing an ISO code of one of the supported currencies.
Default value:
EUR
Validation error codes:

1201 Unsupported currency.

Will be returned if the provided value is not exactly one of the supported ISO currency codes.

The values for this parameter are not case sensitive.

You may retrieve the supported currency list with minimum and maximum donation amounts using the /currencies endpoint. The list may change without notice or increment in major version number.

thankYouMessage (introduced in v1.16)

Allowed values:
String, up to 1000 (Unicode) characters.
Default value:
Empty (i.e. no thank you message)
Validation error codes:

1803 Thank you message field can have max 1000 characters.

Will be returned if the provided value is too long.

This parameter provides an option to add a customized thank you message to donors in the donation confirmation email.

Note: the description must not contain any HTML.

signature (required)

Allowed values:

A SHA1 hash (uppercase hexadecimal string) of the beneficiary ID(s), base64 encoded fundraiser title and your shared secret, using "." (dot) as a field separator character.

In case there are multiple beneficiaries, the order for signature calculation should be the same as the order of beneficiaryId parameters.

Validation error codes:

1901 Invalid signature.

Example 1:

  • Fundraiser name: Running a marathon for children
  • Beneficiary ID: 224
  • Shared secret: wikil34k
  • Signature: SHA1("224.UnVubmluZyBhIG1hcmF0aG9uIGZvciBjaGlsZHJlbg==.wikil34k") = 409AE43F5159FAD37D3CC72DC29E94223D6EB2D4

Example 2:

  • Fundraiser name: Raising funds for multiple charities
  • Beneficiary ID #1: 226
  • Beneficiary ID #2: 225
  • Beneficiary ID #3: 224
  • Shared secret: wikil34k
  • Signature: SHA1("226.225.224.UmFpc2luZyBmdW5kcyBmb3IgbXVsdGlwbGUgY2hhcml0aWVz.wikil34k") = AE27F0FF4D7AB16C960EA7399C798ABF247FD5AC

Response format

Note: any response, other than a JSON object with success data and HTTP status 201 Created should be treated as a failure.

Success

The response content type will be application/json with a UTF-8 charset. The HTTP status code will be 201 Created.

The successfully created fundraiser response JSON object will contain the following fields:

beneficiaryId
ID number of the new entity (also contained in the URL). This number can be used for donations using the /donate endpoint.
permalink
A URL of the profile page of the fundraiser.
givingWidgetEmbedCode
An HTML snippet, that loads the ammado Giving Widget, with the newly created fundraiser pre-selected as a beneficiary.

Validation failure

The response content type will be application/json with a UTF-8 charset. The HTTP status code will be 400 Bad Request.

The failure response JSON object will contain the following fields:

errorCodes
An array of error codes.
beneficiaryErrors (optional - only available if beneficiaryId validation errors are present)
An object where beneficiaryId is the key, and the value is an array of error codes specific to that beneficiary.

Sample request

The example assumes the shared secret to be wikil34k

curl -X POST \
	-d "apiKey=C41E20A0-E2B4-4F16-A414-401DBAC282BD" \
	-d "beneficiaryId=226" \
	-d "beneficiaryId=225" \
	-d "beneficiaryId=224" \
	-d "fundraiserTitle=Raising%20funds%20for%20multiple%20charities" \
	-d "fundraiserDescription=Please%20donate%20to%20support%20children" \
	-d "targetAmount=1500" \
	-d "targetCurrencyCode=GBP" \
	-d "signature=AE27F0FF4D7AB16C960EA7399C798ABF247FD5AC" \
	https://api.ammado.com/v1/fundraiser

Sample success response

Note: the sample is formatted for clarity - all unnecessary whitespace characters will be removed in the real response.

{
	"beneficiaryId":112794,
	"permalink":"https://www.ammado.com/community/112794",
	"givingWidgetEmbedCode":"<iframe src=\"https://www.ammado.com/guest/884c6c67-dcc4-49c1-b0ef-cd2130ea6ba8/givingwidget?112794\" scrolling=\"no\" width=\"320\" height=\"436\" frameborder=\"0\" marginwidth=\"0\" marginheight=\"0\" hspace=\"0\" vspace=\"0\" allowtransparency=\"true\"></iframe>"
}

Sample validation failure response

The following response would be received if the beneficiaryId=46496 nonprofit is not enabled for donations and targetCurrency is invalid:

Note: the sample is formatted for clarity - all unnecessary whitespace characters will be removed in the real response.

{
	"errorCodes": [1102, 1201],
	"beneficiaryErrors": {
		46496: [1102]
	}
}

/fundraiser/{id}/moderators endpoint

The fundraising feature on ammado includes functionality which allows people to publish content (photos, articles, videos, etc.) about their cause and fundraising efforts. When a fundraiser is created on ammado.com or via the /fundraiser endpoint, the creator becomes the moderator for the community. You may use this endpoint to invite additional people to manage the content and the social network.

Parameter reference

apiKey (required)

Allowed values:
A string with your exact API key, as provided by ammado.

To use this endpoint, your API key needs to be associated with an ammado account. The account must already be a moderator of the community you want to invite new moderators to.

To obtain an API key, please contact support@ammado.com with your donation requirements.

Passing an invalid API key or accessing a community you do not moderate will result in a 403 Forbidden.

email (required)

Allowed values:
Valid email address, up to 100 characters.
Validation error codes:

1401 You must provide a valid email address.

Will be returned if there is no email provided.

1402 Email address must be formatted correctly (for example jsmith@example.com).

Will be returned if the provided value does not pass the following regular expression test:

^[\._a-zA-Z0-9!#\$%&'\*\+\-/=\?\^`\{\|\}~]+@[_a-zA-Z0-9-]+(\.[_a-zA-Z0-9-]+)+$

1403 Email provided was too long (max 100 characters).

Will be returned if the value is longer than 100 (Unicode) characters.

1404 Invite already sent.

Will be returned if the person you are trying to invite has already been invited or has already accepted a previous invitation.

firstName (introduced in v1.20)

Allowed values:
String, up to 100 characters.
Validation error codes:

1501 Sorry, the first name you entered does not seem to be valid. Please enter a name between 1 and 100 characters long. Some characters may not be valid.

Invalid characters: < > $ @ # etc.

1502 First name too long (max 100 characters).

Will be returned if the value is longer than 100 (Unicode) characters.

The first and last name can be used to customize salutation in the moderator invitation email that is sent as a result of the successful endpoint call.

lastName (introduced in v1.20)

Allowed values:
String, up to 100 characters.
Validation error codes:

1601 Sorry, the last name you entered does not seem to be valid. Please enter a name between 1 and 100 characters long. Some characters may not be valid.

Invalid characters: < > $ @ # etc.

1602 Last name too long (max 100 characters).

Will be returned if the value is longer than 100 (Unicode) characters.

The first and last name can be used to customize salutation in the moderator invitation email that is sent as a result of the successful endpoint call.

signature (required)

Allowed values:
A SHA1 hash (uppercase hexadecimal string) of the fundraiser ID, invitee email and your shared secret, using "." (dot) as a field separator character.
Validation error codes:

1901 Invalid signature.

Example:

  • Fundraiser ID: 112794
  • Invitee email: jsmith@example.com
  • Shared secret: wikil34k
  • Signature: SHA1("112794.jsmith@example.com.wikil34k") = B79288E5E3EED024CB9B95CDBC8D9B0CDF1C8F6F

Response format

Note: any response, other than a JSON object with success data and HTTP status 200 OK should be treated as a failure.

Success

The response content type will be application/json with a UTF-8 charset. The HTTP status code will be 200 OK.

The response JSON will contain a success property which is true:

{"success":true}

Validation failure

The response content type will be application/json with a UTF-8 charset. The HTTP status code will be 400 Bad Request.

The failure response JSON object will contain the following fields:

errorCodes
An array of error codes.

Sample request

The example assumes the shared secret to be wikil34k

curl -X POST \
	-d "apiKey=C41E20A0-E2B4-4F16-A414-401DBAC282BD" \
	-d "email=jsmith@example.com" \
	-d "signature=B79288E5E3EED024CB9B95CDBC8D9B0CDF1C8F6F" \
	https://api.ammado.com/v1/fundraiser/112794/moderators

Sample validation failure response

The following response would be received if the email address provided is too long and the signature is calculated incorrectly:

{"errorCodes":[1403,1901]}

/fundraiser/{id}/beneficiaries endpoint

Fundraisers on ammado can support multiple nonprofits. You can use this endpoint to invite additional nonprofits to a fundraiser. Each invitee will receive an email explaining how to join the fundraiser as a beneficiary. They can then decide to accept or decline the invitation.

When a nonprofit accepts the invitation, they can receive donations to the fundraiser. For standard fundraisers, the money will be divided evenly among all beneficiaries. For World Fundraisers (see fundraiserType), a single beneficiary will receive the full donation amount if they come from the same country as the donor or they are designated to be the "default" beneficiary.

Parameter reference

apiKey (required)

Allowed values:
A string with your exact API key, as provided by ammado.

To use this endpoint, your API key needs to be associated with an ammado account. The account must already be a moderator of the community you want to invite new moderators to.

To obtain an API key, please contact support@ammado.com with your donation requirements.

Passing an invalid API key or accessing a community you do not moderate will result in a 403 Forbidden.

beneficiaryId (required)

Allowed values:
The permalink identifier of a nonprofit.
Validation error codes:

1101 Beneficiary is invalid.

Will be returned if the provided value is empty or does not match a nonprofit on ammado.

1102 Beneficiary does not accept donations.

Will be returned if the provided value matches a nonprofit that is not enabled to accept donations.

1104 Already invited.

Will be returned if the invitation has already been sent for this nonprofit or they are already a beneficiary of the fundraiser.

1105 Limit reached.

Will be returned if a standard fundraiser already has a maximum number of beneficiaries or if a nonprofit from the same country is already a beneficiary of a World Fundraiser.

The nonprofit identifier is the number (3+ digits) in the last component of the path of the permalink. You can find the permalink option in the "Share this" section on the nonprofit profile page (right-hand column). Examples:

signature (required)

Allowed values:
A SHA1 hash (uppercase hexadecimal string) of the fundraiser ID, nonprofit ID and your shared secret, using "." (dot) as a field separator character.
Validation error codes:

1901 Invalid signature.

Example:

  • Fundraiser ID: 112794
  • Invitee beneficiary ID: 950
  • Shared secret: wikil34k
  • Signature: SHA1("112794.950.wikil34k") = 3B764A41B541F030B6EB6527B576947D6BF0016A

Response format

Note: any response, other than a JSON object with success data and HTTP status 200 OK should be treated as a failure.

Success

The response content type will be application/json with a UTF-8 charset. The HTTP status code will be 200 OK.

The response JSON will contain a success property which is true:

{"success":true}

Validation failure

The response content type will be application/json with a UTF-8 charset. The HTTP status code will be 400 Bad Request.

The failure response JSON object will contain the following fields:

errorCodes
An array of error codes.

Sample request

The example assumes the shared secret to be wikil34k

curl -X POST \
	-d "apiKey=C41E20A0-E2B4-4F16-A414-401DBAC282BD" \
	-d "beneficiaryId=950" \
	-d "signature=3B764A41B541F030B6EB6527B576947D6BF0016A" \
	https://api.ammado.com/v1/fundraiser/112794/beneficiaries

Sample validation failure response

The following response would be received if the nonprofit ID provided is invalid and the signature is calculated incorrectly:

{"errorCodes":[1101,1901]}

/fundraiser/{id}/avatar endpoint

Parameter reference

apiKey (required)

Allowed values:
A string with your exact API key, as provided by ammado.

To use this endpoint, your API key needs to be associated with an ammado account, which will be the default moderator of the fundraiser.

To obtain an API key, please contact support@ammado.com with your donation requirements.

Passing an invalid API key will result in a 403 Forbidden.

avatar (required)

Allowed values:
A valid image in following format: gif, png, bmp, jpeg, jpg.
Validation error codes:

2801 File upload failed.

Will be returned when upload of file failed.

2802 File size is too big. Maximum allowed is 5MB.

Will be returned if the file size exceeded maximum allowed value.

2803 File format is not valid. Accepted file types are: gif, png, bmp, jpeg, jpg.

Will be returned if the file extension is not supported.

2804 File not found.

Will be returned if the file was not provided.

signature (required)

Allowed values:

A SHA1 hash (uppercase hexadecimal string) of the fundraiser ID, base64 encoded avatar file name and your shared secret, using "." (dot) as a field separator character.

Validation error codes:

1901 Invalid signature.

Example:

  • Fundraiser ID: 655
  • Avatar file name: company_logo.png
  • Shared secret: wikil34k
  • Signature: SHA1("655.Y29tcGFueV9sb2dvLnBuZw==.wikil34k") = D7025233A97781C72D9EC17B3F8669EC87794F87

Response format

Note: any response, other than a JSON object with success data and HTTP status 201 Created should be treated as a failure.

Success

The response content type will be application/json with a UTF-8 charset. The HTTP status code will be 201 Created.

The successfully uploaded avatar response JSON object will contain the following fields:

avatarUrl
A URL of the fundraiser's default size (64x64 px) avatar image.
avatarUrlLarge
A URL of the fundraiser's alternative large size (96x96 px) avatar image.

Validation failure

The response content type will be application/json with a UTF-8 charset. The HTTP status code will be 400 Bad Request.

The failure response JSON object will contain the following fields:

errorCodes
An array of error codes.

Sample request

The example assumes the shared secret to be wikil34k

curl 
	-F "apiKey=C41E20A0-E2B4-4F16-A414-401DBAC282BD" \
	-F "avatar=@/home/user1/Desktop/company_logo.png" \
	-F "signature=D7025233A97781C72D9EC17B3F8669EC87794F87" \
	https://api.ammado.com/v1/fundraiser/112794/avatar

Sample success response

Note: the sample is formatted for clarity - all unnecessary whitespace characters will be removed in the real response.

{
	"avatarUrl":"https://www.ammado.com/community/655/avatar",
	"avatarUrlLarge":"https://www.ammado.com/community/655/avatar/large"
}

Sample validation failure response

The following response would be received if the avatar image failed to upload.

{"errorCodes":[2801]}

/fundraiser/{id}/coverimage endpoint

Parameter reference

apiKey (required)

Allowed values:
A string with your exact API key, as provided by ammado.

To use this endpoint, your API key needs to be associated with an ammado account, which will be the default moderator of the fundraiser.

To obtain an API key, please contact support@ammado.com with your donation requirements.

Passing an invalid API key will result in a 403 Forbidden.

cover image (required)

Allowed values:
A valid image in following format: gif, png, bmp, jpeg, jpg.
Validation error codes:

2801 File upload failed.

Will be returned when upload of file failed.

2802 File size is too big. Maximum allowed is 5MB.

Will be returned if the file size exceeded maximum allowed value.

2803 File format is not valid. Accepted file types are: gif, png, bmp, jpeg, jpg.

Will be returned if the file extension is not supported.

2804 File not found.

Will be returned if the file was not provided.

signature (required)

Allowed values:

A SHA1 hash (uppercase hexadecimal string) of the fundraiser ID, base64 encoded cover image file name and your shared secret, using "." (dot) as a field separator character.

Validation error codes:

1901 Invalid signature.

Example:

  • Fundraiser ID: 655
  • Cover image file name: company_cover_image.png
  • Shared secret: wikil34k
  • Signature: SHA1("655.Y29tcGFueV9jb3Zlcl9pbWFnZS5wbmc=.wikil34k") = 0BB70139A984DD0B7E9395AC8989349B62F32A5E

Response format

Note: any response, other than a JSON object with success data and HTTP status 201 Created should be treated as a failure.

Success

The response content type will be application/json with a UTF-8 charset. The HTTP status code will be 201 Created.

The successfully uploaded cover image response JSON object will contain the following fields:

coverImageUrl
A URL of the fundraiser's cover image.

Validation failure

The response content type will be application/json with a UTF-8 charset. The HTTP status code will be 400 Bad Request.

The failure response JSON object will contain the following fields:

errorCodes
An array of error codes.

Sample request

The example assumes the shared secret to be wikil34k

curl 
	-F "apiKey=C41E20A0-E2B4-4F16-A414-401DBAC282BD" \
	-F "coverImage=@/home/user1/Desktop/coverImage.jpg" \
	-F "signature=0BB70139A984DD0B7E9395AC8989349B62F32A5E" \
	https://api.ammado.com/v1/fundraiser/112794/coverimage

Sample success response

Note: the sample is formatted for clarity - all unnecessary whitespace characters will be removed in the real response.

{
	"coverImageUrl":"https://www.ammado.com/community/655/coverimage"
}

Sample validation failure response

The following response would be received if the cover image failed to upload.

{"errorCodes":[2801]}

/beneficiary/{id} endpoint

Nonprofits and fundraisers registered on ammado can accept donations, donors can find and donate to them via their ammado profile, through the ammado Giving Widget embeded to their website or via ammado API. You can use this endpoint to retrieve nonprofit enlistment status with their country of registration and fundraiser status and progress.

You can read more about various beneficiary types and when they are applicable on ammadoDev blog.

Parameter reference

apiKey (required)

Allowed values:
A string with your exact API key, as provided by ammado.

To obtain an API key, please contact support@ammado.com with your donation requirements.

Passing an invalid API key will result in a 403 Forbidden.

localizedCurrencyCode (introduced in v1.19)

Allowed values:
A three letter string representing an ISO code of one of the supported currencies.

To get localizedRaisedAmount and localizedTargetAmount in different currency. This will be applied only on fundraisers.

Passing an invalid currency code will be ignored.

Response format

The response content type will be application/json with a UTF-8 charset. The response body will contain a JSON object with the details of the nonprofit or fundraiser:

beneficiaryId
ID number of the nonprofit/fundraiser (same as requested). This number can be used for donations using the /donate endpoint.
permalink
A URL of the profile page of the nonprofit/fundraiser. The permalink can also be used with /avatar suffix to return the nonprofit/fundraiser avatar. Optional params specified in URL can be used to retrieve avatar in different sizes e.g. https://www.ammado.com/nonprofit/120482/avatar/[medium][large][extralarge]. You can resize these images in CSS in your app.
beneficiaryType
A string with the entity type: either nonprofit or fundraiser.
beneficiaryName
The name of the nonprofit/fundraiser.
strapline (introduced in v1.16)
Nonprofit's/fundraiser's strapline.
categories (introduced in v1.16)
Array of fundraising category names.
acceptsDonations
A boolean value for nonprofit's enlistment/fundraising status.
streetAddress (only for nonprofits) (introduced in v1.19)
The street address of the nonprofit.
streetAddress2 (only for nonprofits) (introduced in v1.19)
Additional street address (if any) of the nonprofit.
city (only for nonprofits) (introduced in v1.19)
The city or town of the nonprofit.
postalZIPCode (only for nonprofits) (introduced in v1.19)
The postal code or ZIP code of the nonprofit.
country (only for nonprofits) (introduced in v1.16)
A two letter ISO country code of the nonprofit's country of residence - as displayed in contact info on nonprofit's profile page.
countryOfRegistration (only for nonprofits)
A two letter ISO country code of the nonprofit's country of registration. Can be helpful when creating fundraiser via /fundraiser endpoint with the fundraiserType parameter set to world - see the parameter's documentation for more info.
state (only for nonprofits) (introduced in v1.26)
A two letter ANSI state code (if any) of the nonprofit's state of residence.
nonprofitRegistrationNumber (only for nonprofits) (introduced in v1.20)
A string with the registration number of the nonprofit.
is501c3Certified (only for nonprofits) (introduced in v1.23)
A boolean value for a nonprofit's registration status in the United States.
publicEmailAddress (only for nonprofits) (introduced in v1.26)
The public email address (if any) of the nonprofit.
telephone (only for nonprofits) (introduced in v1.26)
The telephone number (if any) of the nonprofit.
fax (only for nonprofits) (introduced in v1.26)
The fax number (if any) of the nonprofit.
websiteURL (only for nonprofits) (introduced in v1.26)
The website URL address (if any) of the nonprofit.
currencyCode (only for fundraisers which had fundraising effort started)
A three letter ISO currency code of the target/raised amounts.
raisedAmount (only for fundraisers which had fundraising effort started)

A number using a dot "." as a decimal separator.

Note: this amount is approximate as exchange rates vary.

donationCount (only for fundraisers which had fundraising effort started) (introduced in v1.23)
A number that details how many donations were made to fundraiser.
targetAmount (only for fundraisers and only present when set)
A number using a dot "." as a decimal separator.
targetDate (only for fundraisers and only present when set) (introduced in v1.16)
A string with the ISO 8601 date: YYYY-MM-DD.
localizedCurrencyCode (only for fundraisers) (introduced in v1.19)
If requested by optional parameter localizedCurrencyCode and had fundraising effort started.
A three letter ISO currency code of the target/raised amounts in localized currency.
localizedRaisedAmount (only for fundraisers which had fundraising effort started) (introduced in v1.19)
If requested by optional parameter localizedCurrencyCode
Returned localized value is dependent of currency rates which are frequently changed.
A number using a dot "." as a decimal separator.
localizedTargetAmount (only for fundraisers) (introduced in v1.19)
If requested by optional parameter localizedCurrencyCode and only present when targetAmount is set.
Returned localized value is dependent of currency rates which are frequently changed.
A number using a dot "." as a decimal separator.

Note: new values may be added to the response object without increasing the major version number of the API.

Sample response - nonprofit information

Note: the sample is formatted for clarity - all unnecessary whitespace characters will be removed in the real response.

{
	"beneficiaryId" : 950,
	"permalink" : "https://www.ammado.com/nonprofit/950",
	"beneficiaryType" : "nonprofit",
	"beneficiaryName" : "Amnesty International",
	"strapline" : "Working to protect human rights worldwide",
	"categories" : ["Human Rights"],
	"acceptsDonations" : true,
	"streetAddress" : "1 Easton Street",
	"streetAddress2" : "",
	"city" : "London",
	"postalZIPCode" : "WC1X 0DW",
	"country" : "GB",
	"countryOfRegistration" : "GB",
	"state" : "",
	"nonprofitRegistrationNumber" : "1051681",
	"is501c3Certified" : false,
	"publicEmailAddress" : "contact@example.com",
	"telephone" : "+44 (0)20 7413 5500",
	"fax" : "",
	"websiteURL" : "www.example.com"
}

Sample response - fundraiser information

{
	"beneficiaryId" : 120976,
	"permalink" : "https://www.ammado.com/community/120976",
	"beneficiaryType" : "fundraiser",
	"beneficiaryName" : "Singapore to Kalimantan Outrigger Canoe Charity Expedition",
	"strapline" : "Canoe for life and support",
	"categories" : [ "Education" , "International Aid Agency" ],
	"acceptsDonations" : true,
	"currencyCode" : "SGD",
	"raisedAmount" : 15863.95000000,
	"donationCount" : 2022,
	"targetAmount" : 25000.00000000
}

Sample response - fundraiser information when localizedCurrencyCode requested

{
	"beneficiaryId" : 120976,
	"permalink" : "https://www.ammado.com/community/120976",
	"beneficiaryType" : "fundraiser",
	"beneficiaryName" : "Singapore to Kalimantan Outrigger Canoe Charity Expedition",
	"strapline" : "Canoe for life and support",
	"categories" : [ "Education" , "International Aid Agency" ],
	"acceptsDonations" : true,
	"currencyCode" : "SGD",
	"raisedAmount" : 15863.95000000,
	"donationCount" : 2022,
	"targetAmount" : 25000.00000000,
	"localizedCurrencyCode" : "HUF",
	"localizedRaisedAmount" : 2648713.13771665,
	"localizedTargetAmount" : 4174107.23325000
}

/search endpoint

ammado has thousands of nonprofits and fundraisers that can recieve donations. You can search them according to given parameters by making a GET request to the https://api.ammado.com/v1/search endpoint.

Parameter reference

apiKey (required)

Allowed values:
A string with your exact API key, as provided by ammado.

To obtain an API key, please contact support@ammado.com with your donation requirements.

Passing an invalid API key will result in a 403 Forbidden.

keyword

Allowed values:
A string with the searched name/keyword.
Default value:
Empty (i.e. no keyword).

This parameter can be used to perform a search for a nonprofit with a particular registration number.

nonprofitRegistrationNumber (only for nonprofits) (introduced in v1.20)

Allowed values:
A string with the searched nonprofit registration number.
Default value:
Empty (i.e. no nonprofit registration number).

This parameter can be used to perform a search for nonprofit with particular registration number.

is501c3Certified (only for nonprofits) (introduced in v1.23)

Allowed values:
true or false
Default value:
false

This parameter can be used to search only nonprofits that are currently registered as a 501(c)(3) nonprofit in the United States.

beneficiaryType

Allowed values:
A string with the entity type: either nonprofit or fundraiser.
Default value:
Empty (i.e. both nonprofit and fundraiser type beneficiaries will be returned).

This parameter can be used to find beneficiaries of specific type. If not provided, search will be performed for both entity types.

categoryCode

Allowed values:
A string with the fundraising category code: valid values can be retrieved from /categories endpoint.
Default value:
Empty (i.e. no category code).

This parameter can be used to find beneficiaries of specific fundraising category. If not provided, search will be independent of fundraising category.

country (only for nonprofits)

Allowed values:
A two letter ISO country code of the nonprofit's country of residence.
Default value:
Empty (i.e. no country).

This parameter can be used to search nonprofit from specific country.

state (only for nonprofits) (introduced in v1.18)

Allowed values:
A two letter ANSI state code of the nonprofit's state of residence.
Default value:
Empty (i.e. no state).

This parameter can be used to search nonprofit from specific state within a country specified by country parameter.

As of v1.18 the state parameter is applied only when country parameter value equals US.

pageNumber

Allowed values:
Valid numeric value.
Default value:
Empty (i.e. first results page will be returned).

This parameter specifies which page from the results is returned.

Response format

The response content type will be application/json with a UTF-8 charset. The response body will contain a JSON object with total number of results found, current page number (same as requested) and a set of search results (nonprofit or fundraiser entities) definition objects. Result are paged by 10 search results per page.

Result object fields:

totalCount
A number of results total count.
pageNumber
A number of current result page displayed.
results
An array with detail info for each search result (see below).

Search result object fields:

beneficiaryId
ID number of the nonprofit/fundraiser. This number can be used for donations using the /donate endpoint.
permalink
A URL of the profile page of the nonprofit/fundraiser. The permalink can also be used to return the nonprofit/fundraiser avatar in three sizes e.g. https://www.ammado.com/nonprofit/120482/avatar/[small][medium][large]. You can resize these images in CSS in your app.
beneficiaryType
A string with the entity type: either nonprofit or fundraiser.
beneficiaryName
The name of the nonprofit/fundraiser.
strapline
Nonprofit's/fundraiser's strapline.
categories
Array of fundraising category names.
streetAddress (only for nonprofits) (introduced in v1.26)
The street address of the nonprofit.
streetAddress2 (only for nonprofits) (introduced in v1.26)
Additional street address (if any) of the nonprofit.
city (only for nonprofits) (introduced in v1.26)
The city or town of the nonprofit.
postalZIPCode (only for nonprofits) (introduced in v1.26)
The postal code or ZIP code of the nonprofit.
country (only for nonprofits)
A two letter ISO country code of the nonprofit's country of residence - as displayed in contact info on nonprofit's profile page.
countryOfRegistration (only for nonprofits)
A two letter ISO country code of the nonprofit's country of registration. Can be helpful when creating fundraiser via /fundraiser endpoint with the fundraiserType parameter set to world - see the parameter's documentation for more info.
state (only for nonprofits) (introduced in v1.26)
A two letter ANSI state code (if any) of the nonprofit's state of residence.
nonprofitRegistrationNumber (only for nonprofits) (introduced in v1.20)
A string with the registration number of the nonprofit.
is501c3Certified (only for nonprofits) (introduced in v1.23)
A boolean value for a nonprofit's registration status in the United States.
publicEmailAddress (only for nonprofits) (introduced in v1.26)
The public email address (if any) of the nonprofit.
telephone (only for nonprofits) (introduced in v1.26)
The telephone number (if any) of the nonprofit.
fax (only for nonprofits) (introduced in v1.26)
The fax number (if any) of the nonprofit.
websiteURL (only for nonprofits) (introduced in v1.26)
The website URL address (if any) of the nonprofit.
currencyCode (only for fundraisers)
A three letter ISO currency code of the target/raised amounts.
raisedAmount (only fundraisers)

A number using a dot "." as a decimal separator.

Note: this amount is approximate as exchange rates vary.

targetAmount (only for fundraisers and only present when set)
A number using a dot "." as a decimal separator.
targetDate (only for fundraisers and only present when set)
A string with the ISO 8601 date: YYYY-MM-DD.

Sample response

Note: the sample is formatted for clarity - all unnecessary whitespace characters will be removed in the real response.

{
	"totalCount" : 2,
	"pageNumber" : 1,
	"results":
	{
		"120976" :
		{
			"beneficiaryId" : 120976,
			"permalink" : "https://www.ammado.com/community/120976",
			"beneficiaryType" : "fundraiser",
			"beneficiaryName" : "Singapore to Kalimantan Outrigger Canoe Charity Expedition",
			"strapline" : "Canoe for life and support",
			"categories" : [ "Education" , "International Aid Agency" ],
			"currencyCode" : "SGD",
			"raisedAmount" : 15863.95000000,
			"targetAmount" : 25000.00000000,
			"targetDate" : "2015-06-27",
		},
		"111390" :
		{
			"beneficiaryId" : 111390,
			"permalink" : "https://www.ammado.com/nonprofit/111390",
			"beneficiaryType" : "nonprofit",
			"beneficiaryName" : "Student Advisory Centre (Singapore)",
			"strapline" : "Help children from needy families’ meet their basic needs.",
			"categories" : ["Education"],
			"streetAddress" : "Blk 365",
			"streetAddress2" : "#01-503",
			"city" : "Singapore",
			"postalZIPCode" : "120365",
			"country" : "SG",
			"countryOfRegistration" : "SG",
			"state" : "",
			"nonprofitRegistrationNumber" : "200201465K",
			"is501c3Certified" : false,
			"publicEmailAddress" : "contact@example.com",
			"telephone" : "67770041",
			"fax" : "67770664",
			"websiteURL" : "www.example.com"
		}
	}
}

/categories endpoint

ammado has thousands of nonprofits and fundraisers that can recieve donations. For search and display purposes, these are labeled with fundraising categories which reflect the type of activity that nonprofit or fundraiser is most involved with. You can display those categories by making a GET request to the https://api.ammado.com/v1/categories endpoint and then use it as a search parameter for /search endpoint. endpoint.

Parameter reference

apiKey (required)

Allowed values:
A string with your exact API key, as provided by ammado.

To obtain an API key, please contact support@ammado.com with your donation requirements.

Passing an invalid API key will result in a 403 Forbidden.

Response format

The response content type will be application/json with a UTF-8 charset. The response body will contain a JSON object with a list of supported fundraising categories and it's codes, where category code will be used as a key and category definition object name will be its value.

Category definition fields:

categoryCode
The category code, can be used for search purposes.
categoryName
Full name of the category, in English.

Sample response

Note: the sample is formatted for clarity - all unnecessary whitespace characters will be removed in the real response.

{
	"categories" :
	{
		"Animals" :
		{
			"categoryCode" : "Animals",
			"categoryName" : "Animals"
		},
		"ChildYouth" :
		{
			"categoryCode" : "ChildYouth",
			"categoryName" : "Children and Youth"
		},
		"Community" :
		{
			"categoryCode" : "Community",
			"categoryName" : "Community Services"
		}
	}
}

Giving Widget setup endpoint

The ammado Giving Widget is an embeddable donation facility. Due to its simplicity and portability, it is possible to copy widget code and embed it on a different website. You can use this endpoint to prepare information to be passed into the Giving Widget and sign the requests to ensure that the donations made are coming via your website.

You can later use the /order/{guid} endpoint to check the status of these donations, as well as use that information for donation matching.

Parameter reference

apiKey (required)

Allowed values:
A string with your exact API key, as provided by ammado.

To obtain an API key, please contact support@ammado.com with your donation requirements.

Passing an invalid API key will result in a fatal error.

donorEmail

Allowed values:
Valid email address, up to 100 characters.
Validation error codes:

1402 Email address must be formatted correctly (for example jsmith@example.com).

Will be returned if the provided value does not pass the following regular expression test:

^[\._a-zA-Z0-9!#\$%&'\*\+\-/=\?\^`\{\|\}~]+@[_a-zA-Z0-9-]+(\.[_a-zA-Z0-9-]+)+$

1403 Email provided was too long (max 100 characters).

Will be returned if the value is longer than 100 (Unicode) characters.

You must provide a way for the donors to use their own email address for the donation.

donorFirstName

Allowed values:
String, up to 100 characters.
Validation error codes:

1501 Sorry, the first name you entered does not seem to be valid. Please enter a name between 1 and 100 characters long. Some characters may not be valid.

Invalid characters: < > $ @ # etc.

1502 First name too long (max 100 characters).

Will be returned if the value is longer than 100 (Unicode) characters.

The first and last name of the donor will appear on the nonprofit statement pages, if the donor does not select an option to donate anonymously during checkout.

donorLastName

Allowed values:
String, up to 100 characters.
Validation error codes:

1601 Sorry, the last name you entered does not seem to be valid. Please enter a name between 1 and 100 characters long. Some characters may not be valid.

Invalid characters: < > $ @ # etc.

1602 Last name too long (max 100 characters).

Will be returned if the value is longer than 100 (Unicode) characters.

The first and last name of the donor will appear on the nonprofit statement pages, if the donor does not select an option to donate anonymously during checkout.

extraInfo

Allowed values:
String, up to 255 characters.
Validation error codes:

2201 Extra information is too long (max 255 characters).

Will be returned if the value is longer than 255 (Unicode) characters.

This information will be stored together with the donation and may be retrieved for reporting purposes.

Response format

Note: any response, other than a JSON object with success data and HTTP status 201 Created should be treated as a failure. However, because the signed information is not required for donors to use the Giving Widget, you may provide them an option to donate without it.

Success

The response content type will be application/json with a UTF-8 charset. The HTTP status code will be 201 Created.

The response JSON will contain the following fields:

orderId
A string that needs to be passed into the Giving Widget with a signature. You can also use this identifier with the /order/{guid} endpoint to check the order status.
salt
A unique random alphanumeric string that will be used for the signature (see below).

Note that if the donor does not complete the checkout process, the order will be removed from the system and subsequent calls to the /order/{guid} endpoint may result in a 404 Not Found.

Validation failure

The response content type will be application/json with a UTF-8 charset. The HTTP status code will be 400 Bad Request.

The failure response JSON object will contain the following fields:

errorCodes
An array of error codes.

Passing the order and signature into the Giving Widget

To use the submitted information in the Giving Widget, you must append the following query parameters to the src URL of the iframe or the script (depending of which version of embed code you are using):

orderId
The exact value as returned in the JSON response.
signature

A SHA1 hash (uppercase hexadecimal string) of the order ID, salt and your shared secret, using "." (dot) as a field separator character.

Example:

  • Order ID: 2B622BF4-6DBB-4696-9A5A-A74E3A2FDCA3
  • Salt: j4s5I8Pu5j3ddM7h8S4MFW33848X72
  • Secret: wikil34k
  • Signature: SHA1("2B622BF4-6DBB-4696-9A5A-A74E3A2FDCA3.j4s5I8Pu5j3ddM7h8S4MFW33848X72.wikil34k") = 644892D515CEA5070C375EB9900DD5E046B20D1D

Note that if the secret is incorrect, or the widget URL does not match the endpoint URL, the information passed in will be silently ignored and the donation, if successful, will not be considered "authenticated" in reporting.

Sample request

curl -X POST \
	-d "apiKey=C41E20A0-E2B4-4F16-A414-401DBAC282BD" \
	-d "donorEmail=jsmith@example.com" \
	-d "donorFirstName=John" \
	-d "donorLastName=Smith" \
	-d "extraInfo=JS-0123456789" \
	https://api.ammado.com/v1/company/1247/givingwidget

Sample success response

Note: the sample is formatted for clarity - all unnecessary whitespace characters will be removed in the real response.

{
	"orderId":"2B622BF4-6DBB-4696-9A5A-A74E3A2FDCA3",
	"salt":"j4s5I8Pu5j3ddM7h8S4MFW33848X72"
}

Sample widget embed code with a signature

Assuming the successful response above with wikil34k as a shared secret the widget embed code may look as follows (appended parameters highlighted):

<div id="ammadoGivingWidget"></div><script type="text/javascript">var s = document.createElement('script');s.type='text/javascript';s.async=true;s.src='https://www.ammado.com/company/1247/givingwidget/embed.js?renderTo=ammadoGivingWidget&orderId=2B622BF4-6DBB-4696-9A5A-A74E3A2FDCA3&signature=644892D515CEA5070C375EB9900DD5E046B20D1D';var f = document.getElementsByTagName('script')[0];f.parentNode.insertBefore(s, f);</script>

Sample validation failure response

The following response would be received if the email address provided is invalid and first name contains invalid characters:

{"errorCodes":[1402,1501]}