The Ingo Money SDK provides opportunities for asynchronous events that can be used to generate push notifications and other messaging for the customer.
Ingo Money Webhooks for our SDK partners provide data relevant to a variety of customer scenarios. They are typically used to generate:
These actions are sent in addition to any email or other types of notifications that Ingo normally sends out. We provide these events to augment your data and customer experience.
Ingo does not send Push notifications directly to partner applications primarily due to security and app vendor constraints. Rather, we push events to your server, and you are then free to handle them however you would prefer.
As an example, a event for a customer may be handled in the following way:
1) Customer generates a transaction on their iPhone.
2) Ingo approves the transaction.
3) Ingo Server sends a webhook to SDK Partner’s server detailing the load information.
4) SDK Partner’s server sends a Push Notification to Urban Airship or some other third party notification service.
5) Urban Airship delivers the notification to Apple.
6) Apple delivers the notification to the device.
7) The device displays the notification in or out of your application.
As another example, you might be interested in understanding how many transactions are created by your customers. Ingo webhooks facilitate that. This might manifest itself in the following way:
1) Customer generates a transaction on their phone.
2) Ingo Server sends a webhook to SDK Partner’s server detailing the transaction creation.
3) SDK Partner’s server stores the data in a data warehouse for future analysis.
The diagram below delineates the most common usage scenario for Ingo Notifications.
[PLACEHOLDER]
Partners are responsible for generating an appropriate listener for notifications. This is done as a publically exposed HTTP(s) Post handler. If there are security credentials, they must be present on the URL. Ingo does not support alternative security mechanisms at this time.
For each notification, Ingo will attempt a POST to the URL provided (by you). All request information is sent to the POST handler as JSON data. The content can be read and handled according to the needs of the partner. Please refer to the sample code section for some simple code snippets written in c# and php that illustrate data extraction.
Your Post Handler MUST be registered with Ingo when you turn on this service. Separate post handlers can be used in our UAT and production environments for your testing. We recommend, at a minimum, you handle and log each webhook sent to you. Registering your post handler(s) is simply a matter of delivering the appropriate URL(s) to your Ingo Project Manager or the Ingo Technical Lead. Once delivered, Ingo will ensure that webhooks are delivered to that address.
Event data is returned in JSON format. Your application should determine the value of each type of event and whether or not to pass it on to the consumer. For example, the transaction created event may not be suitable to pass along to the customer, but the decline event is imperative.
All data are sent as strings. All amounts are in pennies. All dates are represented as GMT-0 UTC. A blank value or missing key indicates no data for that element. NotificationType is always present and a lack of NotificationType should be considered an error.
| Field Name | Description |
|---|---|
| FirstName | Simply the customer’s first name. E.g., “Jane” |
| LastName | Simply the customer’s first name. E.g., “Doe” |
| CustomerEmailAddress | The primary email address of the Ingo Money account. E.g., emailaddress@gmail.com |
| CustomerId | Unique identifier (GUID) for a specific customer. E.g, “49e8cc02-d644- 4025 - a7a5-b30d9baea2a9” |
| TransactionId | Unique identifier (GUID) for a specific transaction. E.g, “dd107f4c-8cc5-47cc- 8654 - 01d0a5858fba” |
| KeyedAmount | The specified check amount (in cents). E.g., 10000 |
| LoadAmount | The amount (in cents) that will be loaded to a card after fees are subtracted. E.g., 9500 |
| Fee | The fee (in cents) that will be charged for the transaction. E.g., 500 |
| FeeDeltaInCents | The difference (in cents) between Ingo assessed fees and the partner assessed SDK fees. E.g. 100 |
| IsPpg | Denotes if the check presented is a Pre-Printed Government Check type. E.g., true |
| PromoCode | The promotion code name entered. E.g., “PROMO123” |
| PromoType | Denotes promotion code type presented. [ “Addon Amount”, "Campaign Addon Amount", "FriendBuy Campaign Addon Amount"] |
| PromoAmount | Denotes the promotion code amount value in dollars and cents. E.g., 5. |
| CardId | Unique identifier (GUID) for a specific card. E.g, “c594e285-1ffb-425f-abf8-d5dcff94bbcb” |
| CardNickName | The nickname assigned to the applicable card. E.g. “Primary Card” |
| LastFourOfCard | The last four digits of the customer’s card account. E.g., “1111” |
| CardBinNumber | The BIN of the customers card account. E.g., “411111” |
| FundingDestinationIdentifier | Unique identifier (GUID) denoting the partner funding destination. E.g, “ef 109 f4c-8cc5-47cc-8654-01d0a5858fba” |
| CheckSubmissionDate | The date and time the check was loaded into the Ingo Network. E.g, “05/22/2014 17:22:09” |
| FundsAvailableDate | The date and time funds will be loaded onto the customer’s card. E.g, “05/22/2014 17:22:09” |
| NotificationId | Unique identifier (GUID) for this specific notification. E.g, “ef 109 f4c-8cc5-47cc- 8654 - 01d0a5858fba” |
| NotificationType | The type (numeric) of notification that is being sent. E.g., 9 |
| NotificationTypeDescription | The type (text) of notification that is being sent. E.g., “In Minutes Transaction” |
| TransactionType | The type (numeric) of transaction. E.g., 1 |
| TransactionTypeDescription | The type (text) of transaction. E.g., “In Minutes” |
| TransactionStatus | The status (numeric) of the transaction. E.g., 3 |
| TransactionStatusDescription | The status (text) of the transaction. E.g., “Completed” |
| CancelledBy | The identification (numeric) of who or what cancelled the transaction. |
| CancelledByDescription | This field specifies who or what canceled the transaction. E.g., “None” |
| DeclineReason | This specifies a reason that the transaction was declined. E.g., “Transaction Amount Greater Than Max Allowed Transaction Amount“ |
| DeclineCode | This code maps to the DeclineReason. E.g., “99909” |
Note: Possible values for the PromoType are below. Items in bold are the most pertinent to SDK Partners.
Note: Possible values for the notification types/descriptions are below.
Note: Possible values for the transaction types/descriptions are:
Note: Possible values for the transaction statuses/descriptions are:
Note: Possible values for the CancelledByDescription field are below. Items in bold are the most pertinent to SDK Partners.
Note: There is a large decline code master list. This list is updated regularly and currently outside of the scope of the integration. In general, no programmatic actions should be taken based on the contents of these fields.
| Notification Type Value | Notification Type Description | Keys Used |
|---|---|---|
| 7 | Transaction Declined – Sent when an in minutes or in days transaction is declined in the approval loop. Transactions can either be declined at approval – e.g., the check doesn’t meet our standards, or at load time in the case of an in days transaction that declines due to return. | FirstName; LastName; CustomerEmailAddress; KeyedAmount; LoadAmount; Fee; LastFourOfCard; CardBinNumber; CheckSubmissionDate; FundsAvailableDate; NotificationType; NotificationTypeDescription; TransactionType; TransactionTypeDescription; TransactionStatus; TransactionStatusDescription; CancelledByDescription; DeclineReason; DeclineCode; CustomerId; CardId; TransactionId |
Sample JSON
{
"FirstName": "Sunil",
"LastName": "Cardoz",
"CustomerEmailAddress": "sunil.abhale@aurionpro.com",
"KeyedAmount": 100000,
"LoadAmount": 0,
"Fee": 100000,
"LastFourOfCard": "0696",
"CardBinNumber": "471620",
"CheckSubmissionDate": "",
"FundsAvailableDate": "",
"NotificationType": 7,
"NotificationTypeDescription": "TransactionDeclined",
"TransactionType": 0,
"TransactionTypeDescription": "Unknown",
"TransactionStatus": 8,
"TransactionStatusDescription": "Declined",
"CancelledByDescription": "Velocity",
"DeclineReason": "Transaction AmountGreater Than Max Allowed Transaction Amount",
"DeclineCode": "99909",
"CustomerId": "49e8cc02-d644-4025-a7a5-b30d9baea2a9",
"CardId": "c594e285-1ffb-425 f-abf8-d5dcff94bbcb",
"TransactionId": "dd107f4c-8cc5-47cc- 8654 - 01d0a5858fba"
}
| Notification Type Value | Notification Type Description | Keys Used |
|---|---|---|
| 9 | In Minutes Transaction –vsent whenever a new In Minutes transaction is generated. | FirstName; LastName; CustomerEmailAddress; KeyedAmount; LoadAmount; Fee; LastFourOfCard; CardBinNumber; CheckSubmissionDate; FundsAvailableDate; NotificationType; NotificationTypeDescription; TransactionType; TransactionTypeDescription; TransactionStatus; TransactionStatusDescription; CancelledByDescription; CustomerId; CardId; TransactionId |
Sample JSON
{
"FirstName": "Sunil",
"LastName": "Cardoz",
"CustomerEmailAddress ": "sunil.abhale @aurionpro.com ",
"KeyedAmount ": 14400,
"LoadAmount ": 13900,
"Fee": 500,
"LastFourOfCard": "0696",
"CardBinNumber ": "471620 ",
"CheckSubmissionDate ": "06 / 16 /10: 03: 34 ",
"FundsAvailableDate ": "06 / 16 / 10: 03: 34 ",
"NotificationType ": 9,
"NotificationTypeDescription ": "In Minutes Transaction ",
"TransactionType ": 1,
"TransactionTypeDescription ": "InMinutes ",
"TransactionStatus ": 10,
"TransactionStatusDescription ": "In Review ",
"CancelledByDescription ": "None ",
"DeclineReason ": "",
"DeclineCode ": "",
"CustomerId ": "49e8cc02-d644-4025-a7a5-b30d9baea2a9 ",
"CardId ": "c594e285-1ffb-425f-abf8-d5dcff94bbcb ",
"TransactionId ": "dd107f4c-8cc5-47cc-8654-01d0a5858fba"
}
| Notification Type Value | Notification Type Description | Keys Used |
|---|---|---|
| 10 | In Days Transaction – sent whenever a new In Days transaction is generated. | FirstName; LastName; CustomerEmailAddress; KeyedAmount; LoadAmount; Fee; LastFourOfCard; CardBinNumber;; CheckSubmissionDate; FundsAvailableDate; NotificationType; NotificationTypeDescription; TransactionType; TransactionTypeDescription; TransactionStatus; TransactionStatusDescription; CancelledByDescription; CustomerId; CardId; TransactionId |
Sample JSON
{
"FirstName": "Sunil",
"LastName": "Cardoz",
"CustomerEmailAddress": "sunil.abhale@aurionpro.com",
"KeyedAmount": 14400,
"LoadAmount": 13900,
"Fee": 0,
"LastFourOfCard": "0696",
"CardBinNumber": "471620",
"CheckSubmissionDate": "06/16/10:03:34",
"FundsAvailableDate": "06/26/10:03:34",
"NotificationType": 10,
"NotificationTypeDescription": "In Days Transaction",
"TransactionType": 2,
"TransactionTypeDescription": "In Days",
"TransactionStatus": 10,
"TransactionStatusDescription": "In Review",
"CancelledByDescription": "None",
"DeclineReason": "",
"DeclineCode": "",
"CustomerId": "49e8cc02-d644-4025-a7a5-b30d9baea2a9",
"CardId": "c594e285-1ffb-425f-abf8-d5dcff94bbcb",
"TransactionId": "dd107f4c-8cc5-47cc- 8654 - 01d0a5858fba"
}
| Notification Type Value | Notification Type Description | Keys Used |
|---|---|---|
| 11 | Cancel Transaction – occurs if a user or the system cancels a transaction. Users can cancel or decline the fees. The system cancels transactions if they timeout (e.g., the customer abandons with no action). | FirstName; LastName; CustomerEmailAddress; KeyedAmount; LoadAmount; Fee; LastFourOfCard; CardBinNumber; CheckSubmissionDate; FundsAvailableDate; NotificationType; NotificationTypeDescription; TransactionType; TransactionTypeDescription; TransactionStatus; TransactionStatusDescription; CancelledByDescription; CustomerId; CardId; TransactionId |
Sample JSON
{
"FirstName": "Sunil",
"LastName": "Cardoz",
"CustomerEmailAddress": "sunil.abhale@aurionpro.com",
"KeyedAmount": 35000,
"LoadAmount": 0,
"Fee": 35000,
"LastFourOfCard": "",
"CardBinNumber": "",
"CheckSubmissionDate": "",
"FundsAvailableDate": "",
"NotificationType": 11,
"NotificationTypeDescription": "Cancel Transaction",
"TransactionType": 0,
"TransactionTypeDescription": "Unknown",
"TransactionStatus": 5,
"TransactionStatusDescription": "Cancelled",
"CancelledByDescription": "User",
"DeclineReason": "",
"DeclineCode": "",
"CustomerId": "49e8cc02-d644-4025-a7a5-b30d9baea2a9",
"CardId": "c594e285-1ffb-425f-abf8-d5dcff94bbcb",
"TransactionId": "dd107f4c-8cc5-47cc- 8654 - 01d0a5858fba"
}
| Notification Type Value | Notification Type Description | Keys Used |
|---|---|---|
| 16 | Transaction Returned – Occurs if the check is returned. This is post approval and, in the case of an In Minutes transaction, post card load. This notification does not signify the return of funds from the customer’s card. | FirstName; LastName; CustomerEmailAddress; KeyedAmount; LoadAmount; Fee; LastFourOfCard; CardBinNumber; CheckSubmissionDate; FundsAvailableDate; NotificationType; NotificationTypeDescription; TransactionType; TransactionTypeDescription; TransactionStatus; TransactionStatusDescription; CancelledByDescription; CustomerId; CardId; TransactionId |
Sample JSON
{
"FirstName": "Sunil",
"LastName": "Cardoz",
"CustomerEmailAddress": "sunil.abhale@aurionpro.com",
"KeyedAmount": 20000,
"LoadAmount": 19500,
"Fee": 500,
"LastFourOfCard": "0696",
"CardBinNumber": "471620",
"CheckSubmissionDate": "06/16/12:32:03",
"FundsAvailableDate": "06/16/12:32:03",
"NotificationType": 16,
"NotificationTypeDescription": "TransactionReturned",
"TransactionType": 1,
"TransactionTypeDescription": "In Minutes",
"TransactionStatus": 6,
"TransactionStatusDescription": "Returned",
"CancelledByDescription": "None",
"DeclineReason": "",
"DeclineCode": "",
"CustomerId": "49e8cc02-d644- 4025 - a7a5-b30d9baea2a9",
"CardId": "c594e285-1ffb-425f-abf8-d5dcff94bbcb",
"TransactionId": "dd107f4c-8cc5-47cc- 8654 - 01d0a5858fba"
}
| Notification Type Value | Notification Type Description | Keys Used |
|---|---|---|
| 24 | Transaction Funded – this is the final approval of a funded transaction. This is post funds being loaded to the card. | FirstName; LastName; CustomerEmailAddress; KeyedAmount; LoadAmount; Fee; LastFourOfCard; CardBinNumber; CheckSubmissionDate; FundsAvailableDate; NotificationType; NotificationTypeDescription; TransactionType; TransactionTypeDescription; TransactionStatus; TransactionStatusDescription; CancelledByDescription; CustomerId; CardId; TransactionId |
Sample JSON
{
"FirstName": "Sunil",
"LastName": "Cardoz",
"CustomerEmailAddress": "sunil.abhale@aurionpro.com",
"KeyedAmount": 14400,
"LoadAmount": 13900,
"Fee": 500,
"LastFourOfCard": "0696",
"CardBinNumber": "471620",
"CheckSubmissionDate": "06/16/10:03:34",
"FundsAvailableDate": "06/16/10:03:34",
"NotificationType": 24,
"NotificationTypeDescription": "Transaction Funded",
"TransactionType": 1,
"TransactionTypeDescription": "In Minutes",
"TransactionStatus": 3,
"TransactionStatusDescription": "Completed",
"CancelledByDescription": "None",
"DeclineReason": "",
"DeclineCode": "",
"CustomerId": "49e8cc02-d644-4025-a7a5-b30d9baea2a9",
"CardId": "c594e285-1ffb-425f-abf8-d5dcff94bbcb",
"TransactionId": "dd107f4c-8cc5-47cc-8654-01d0a5858fba"
}
| Notification Type Value | Notification Type Description | Keys Used |
|---|---|---|
| 25 | Transaction Funding Failure - Occurs if the transaction fails to load. This is post approval. This is considered an edge case, but can occur in the case where customer’s card exceeds balances or is closed ahead of funding. | FirstName; LastName; CustomerEmailAddress; KeyedAmount; LoadAmount; Fee; LastFourOfCard; CardBinNumber; CheckSubmissionDate; FundsAvailableDate; NotificationType; NotificationTypeDescription; TransactionType; TransactionTypeDescription; TransactionStatus; TransactionStatusDescription; CancelledByDescription; CustomerId; CardId; TransactionId |
Sample JSON
{
"FirstName": "Sunil",
"LastName": "Cardoz",
"CustomerEmailAddress": "sunil.abhale@aurionpro.com",
"KeyedAmount": 10000,
"LoadAmount": 9500,
"Fee": 500,
"LastFourOfCard": "0696",
"CardBinNumber": "471620",
"CheckSubmissionDate": "06/16/12:28:05",
"FundsAvailableDate": "06/16/12:28:05",
"NotificationType": 25,
"NotificationTypeDescription": "Transaction Funding Failure",
"TransactionType": 1,
"TransactionTypeDescription": "In Minutes",
"TransactionStatus": 7,
"TransactionStatusDescription": "Load Failed",
"CancelledByDescription": "None",
"DeclineReason": "",
"DeclineCode": "",
"CustomerId": "49e8cc02-d644-4025-a7a5-b30d9baea2a9",
"CardId": "c594e285-1ffb-425f-abf8-d5dcff94bbcb",
"TransactionId": "dd107f4c-8cc5-47cc-8654-01d0a5858fba"
}
| Notification Type Value | Notification Type Description | Keys Used |
|---|---|---|
| 26 | Check Franking Required – sent if the transaction is required to be franked. This will occur for certain transaction types that require a voided check capture ahead of card load. This is post approval, pre card load. | FirstName; LastName; CustomerEmailAddress; KeyedAmount; LoadAmount; Fee; LastFourOfCard; CardBinNumber; CheckSubmissionDate; FundsAvailableDate; NotificationType; NotificationTypeDescription; TransactionType; TransactionTypeDescription; TransactionStatus; TransactionStatusDescription; CancelledByDescription; CustomerId; CardId; TransactionId |
Sample JSON
{
"FirstName": "Sunil",
"LastName": "Cardoz",
"CustomerEmailAddress": "sunil.abhale@aurionpro.com",
"KeyedAmount": 14400,
"LoadAmount": 13900,
"Fee": 500,
"LastFourOfCard": "0696",
"CardBinNumber": "471620",
"CheckSubmissionDate": "06/16/10:03:34",
"FundsAvailableDate": "06/16/10:03:34",
"NotificationType": 26,
"NotificationTypeDescription": "Check Franking Required",
"TransactionType": 1,
"TransactionTypeDescription": "In Minutes",
"TransactionStatus": 12,
"TransactionStatusDescription": "Check Franking Pending",
"CancelledByDescription": "None",
"DeclineReason": "",
"DeclineCode": "",
"CustomerId": "49e8cc02-d644-4025-a7a5-b30d9baea2a9",
"CardId": "c594e285-1ffb-425f-abf8-d5dcff94bbcb",
"TransactionId": "dd107f4c-8cc5-47cc-8654-01d0a5858fba"
}
< % @ WebHandler Language = "C#"
Class = "WaitingForANotification" % >
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Web;
using Newtonsoft.Json;
public class WaitingForANotification: IHttpHandler {
public void ProcessRequest(HttpContext context) {
if (context.Request.InputStream.Length > 0) {
using(var reader = new StreamReader(context.Request.InputStream)) {
var rawJsonNotificationData = reader.ReadToEnd();
if (!string.IsNullOrWhiteSpace(rawJsonNotificationData)) {
var keyValueDeserializedData =
JsonConvert.DeserializeObject < IDictionary < string,
string >> (rawJsonNotificationData);
var parsedPartnerNotificationData =
keyValueDeserializedData.ToDictionary(dataElement => dataElement.Key,
dataElement => dataElement.Value);
//TODO : DO whatever is required once the notification is received
//This sample simply writes the Dictionary data back to the response stream
context.Response.Write(JsonConvert.SerializeObject(parsedPartnerNotificationD ata));
context.Response.ContentType = "application/json";
context.Response.End();
}
}
}
WriteEmptyResponse(context);
}
private static void WriteEmptyResponse(HttpContext context) {
context.Response.Write("No notification data");
context.Response.ContentType = "application/json";
context.Response.End();
}
public bool IsReusable {
get {
return false;
}
}
}
$notificationType = $_POST[‘NotificationType’];
$customerIdentifier = $_POST[‘CustomerIdentifier’];
$customerEmailAddress = $_POST[‘CustomerEmailAddress’]