Push Notifications
Partners can choose to receive push notifications of certain application events. Push notifications are transmitted using the PAPI notificationStatusRequest object. Before getting push notifications, end points and authentication must be configured.
Authentication
In order to receive push notifications, authentication is required in both test and production environments. The following methods for authentication are supported:
- Basic authentication: Partner provides Elavon with the username, password, and URL endpoint.
- Token-based authentication: Partner provides Elavon with the token and URL endpoint.
- Plain authentication: Partner provides Elavon with the token and URL endpoint. This token is not converted to base64.
- OAuth2 authentication - password grant: Partner provides Elavon with the client ID, client Secret, username, password, authentication URL, and URL endpoint.
- OAuth2 authentication - client credentials grant: Partner provides Elavon with the client ID, client Secret, authentication URL, and URL endpoint. Partners can also specify a scope parameter which will be passed in the authentication header.
Elavon will need your SSL Certificate in order to send push notifications.
Types of Push Notifications
The notificationEvent property will define the type of event that occurred.
Tell Elavon which push notifications you’d like to receive.
| Push Notifications Schedule | Notification Event Name | Applicable To |
|---|---|---|
Sent when the application’s status changes (INPROGRESS, PEND, COMPLETE, DECLINED, WITHDRAWN, ERROR, or UNKNOWN). UNKNOWN status is returned when the downstream system responds with an unrecognized response. This typically does not happen. | BOARDING_STATUS | - Guided and Managed Flows - Payment Facilitators |
| Sent when - An account is created - Customer hasn’t created an account after 7 days or after 14 days | EMAIL_SENT | Guided Flow |
| Sent when customer inputs incorrect date of birth, phone number, or password for the account | REGISTRATION_ERROR | Guided Flow |
| Sent when a customer successfully creates an account | REGISTRATION_COMPLETED | Guided Flow |
| Sent when an applicant’s signature status changes | SIGNATURE_STATUS | Guided Flow |
| Sent when an application is received and boarded | APPLICATION_SUBMITTED | Guided Flow |
Additional Notes for Push Notifications
Push Notification parameters and profileCode need to be set up for any partner who wants push notifications.
If a partner has multiple profile codes (profileCode), then they need a notification configuration for each one.
Push notifications are only sent to partners, not to the end merchants.
Push notifications are not available in Stateless flow. Since Stateless flow does not track application state within the application, it is incapable of providing notifications representing state and events.
Push Notification Structure
The notificationStatusRequest object contains the following properties:
uniqueId: In Guided flow and Managed flow.clientId: In Guided flow and Managed flow.correlationId: In Guided flow and Managed flow when the original request contains the correlation ID.groupPacketId: In Guided flow.packetId: In Managed flow.notificationEvent: Present in Guided flow and Managed flow to indicate current state of merchant application progress.appStatus: In Guided flow and Managed flow.messages: In Guided flow. Indicates email template sent to merchant.signerStatus: In Guided flow.boardingStatusDetail: In Guided flow and Managed flow.boardingId: In Guided flow and Managed flow (AWB).merchantId: In Guided flow and Managed flow (MID).errorMessages: In Guided flow and Managed flow if error occurs.pendMessages: In Guided flow and Managed flow if app is pended.underwriterNotes: In Guided flow and Managed flow if app is pended.underwriterContacts: In Guided flow and Managed flow if app is pended.chainId: In Guided flow and Managed flow if app is pended.terminalIdInfo: In Guided flow and Managed flow. If applicable, terminal IDs and Converge Credentials are presented.
Here is the structure of notificationStatusRequest:
{
"type": "object",
"properties": {
"uniqueId": {
"type": "string"
},
"clientId": {
"type": "string"
},
"correlationId": {
"type": "string"
},
"groupPacketId": {
"type": "string"
},
"packetId": {
"type": "string"
},
"notificationEvent": {
"type": "string",
"enum": [
"EMAIL_SENT",
"REGISTRATION_ERROR",
"REGISTRATION_COMPLETED",
"SIGNATURE_STATUS",
"APPLICATION_SUBMITTED",
"BOARDING_STATUS"
]
},
"appStatus": {
"type": "string",
"enum": [
"DRAFT",
"SUBMITTED",
"COMPLETE",
"ERROR",
"WITHDRAWN",
"DECLINED"
]
},
"messages": {
"type": "array",
"items": {
"type": "string"
}
},
"signerStatus": {
"type": "array",
"items": {
"type": "object",
"properties": {
"signerId": {
"type": "string"
},
"signerStatus": {
"type": "string",
"enum": [
"DRAFT",
"ACCEPTED",
"SIGNED",
"DECLINED",
"EXPIRED"
]
}
}
}
},
"boardingStatusDetail": {
"type": "object",
"properties": {
"boardingStatus": {
"type": "string",
"enum": [
"UNKNOWN",
"COMPLETE",
"INPROGRESS",
"DECLINED",
"WITHDRAWN",
"ERROR",
"TIMED_OUT",
"PEND"
]
},
"boardingId": {
"type": "string"
},
"merchantId": {
"type": "string"
},
"errorMessages": {
"type": "array",
"items": {
"type": "string"
}
},
"pendMessages": {
"type": "array",
"items": {
"type": "string"
}
},
"underwriterNotes": {
"type": "array",
"items": {
"type": "string"
}
},
"underwriterContacts": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"chainId" : {
"type": "string"
},
"terminalIdInfo" : {
"type": "object",
"properties" : {
"error" : {
"type" : "string"
},
"welcomeUrl" : {
"type" : "string"
},
"virtualId" : {
"type" : "string"
},
"terminalBin" : {
"type" : "string"
},
"terminalIdDataMap": {
"type": "array",
"description": "Java map <String,Object> where string is key and object contains terminalId, userId, pin, and errorText.",
"items": {
"anyOf": [
{
"type": "object",
"examples": [
{
"keyString": [
{
"terminalId": "some terminalId",
"userId": "some userId",
"pin": "some pin",
"errorText": "some error text"
}
]
}
],
"properties": {
"keyString": {
"type": "array",
"description": "An explanation about the purpose of this instance.",
"items": {
"anyOf": [
{
"type": "object",
"description": "An explanation about the purpose of this instance.",
"properties": {
"terminalId": {
"type": "string",
},
"userId": {
"type": "string",
},
"pin": {
"type": "string",
},
"errorText": {
"type": "string",
}
}
}
]
}
}
}
}
]
}
}
}
}
}
}