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, endpoints 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.

Push Notifications Trigger Time

In EU, it can take up to 15 minutes for the Partner to receive the notification once the action has occurred downstream. This timeframe for notifications depends on downstream actions and when they occur, not when the application submission occurs.

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.

Additional Notes for Push Notifications

• Authentication parameters and profileCode need to be set up for any partner who wants push notifications.

• One profileCode can be configured with one endpoint URL. If a partner has multiple profile codes (profileCode), then they need a notification configuration for each code.

• 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:

• 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: 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.

• merchantId: In Guided flow and Managed flow.

• 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",
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    }
                ]
            }
        }
      }
    }
  }
}

❮ Back to Third-Party Document SigningNext: Error Messages ❯