Skip to main content

Notification payload samples

Take a look at these payload examples relating to available notifications in Embedded Payments. 

Onboarding examples

Client status - New client

Client Status - NEW
Json
{
    "eventId":"903",
    "eventType":"CLIENT_ONBOARDING",
    "resourceType":"CLIENTS",
    "resource":"{\"id\":\"3000005555\",\"status\":\"NEW\",\"hasOutstandingInformation\":false,\"customerIdentityStatus\":\"NEW\"}"
}

Client status - Review in progress

Json
{
    "eventId":"904",
    "eventType":"CLIENT_ONBOARDING",
    "resourceType":"CLIENTS",
    "resource":"{\"id\":\"3000005555\",\"status\":\"REVIEW_IN_PROGRESS\",\"hasOutstandingInformation\":false,\"customerIdentityStatus\":\"REVIEW_IN_PROGRESS\"}"
}

Client status - Information requested

Client Status - INFORMATION_REQUESTED
Json
{
    "eventId":"905",
    "eventType":"CLIENT_ONBOARDING",
    "resourceType":"CLIENTS",
    "resource":"{\"id\":\"3000005555\",\"status\":\"INFORMATION_REQUESTED\",\"hasOutstandingInformation\":true,\"customerIdentityStatus\":\"INFORMATION_REQUESTED\"}"
}

Client status - Approved

Client Status - APPROVED
Json
{
    "eventId":"906",
    "eventType":"CLIENT_ONBOARDING",
    "resourceType":"CLIENTS",
    "resource":"{\"id\":\"3000005555\",\"status\":\"APPROVED\",\"hasOutstandingInformation\":false,\"customerIdentityStatus\":\"APPROVED\"}"
}

Account examples

ACCOUNT_CREATED

Json
{
    "eventId":"5120",
    "eventType":"ACCOUNT_CREATED",
    "resourceType":"ACCOUNTS",
    "resource":"{\"id\":\"9c7798a8643a40068cb4d12d97ab68f5\",\"clientId\":\"1000020694\",\"type\":\"LIMITED_DDA\",\"label\":\"Taxes6871\",\"state\":\"OPEN\",\"createdAt\":\"2024-06-17T14:04:22.963402108Z\",\"paymentRoutingInformation\":{\"accountNumber\":\"20000059586871\",\"country\":\"US\",\"routingInformation\":[{\"type\":\"ABA\",\"value\":\"028000024\"}]}}",
    "resourceObject": {
      "id": "9c7798a8643a40068cb4d12d97ab68f5",
      "clientId": "1000020694",
      "type": "LIMITED_DDA",
      "label": "Taxes6871",
      "state": "OPEN",
      "createdAt": "2024-06-17T14:04:22.963402108Z",
      "paymentRoutingInformation": {
        "accountNumber": "20000059586871",
        "country": "US",
        "routingInformation": [{
          "type": "ABA",
          "value": "028000024"
        }]
      }
    }
}

Event type - ACCOUNT_CLOSED

Json
{
      "eventId":"2268",
      "eventType":"ACCOUNT_CLOSED",
      "resourceType":"ACCOUNTS",
      "resource":"{\"id\":\"14bbc55243d24e589c1eca6b723254df\",\"clientId\":\"1000020694\",\"type\":\"LIMITED_DDA\",\"label\":\"Taxes5834\",\"state\":\"CLOSED\",\"createdAt\":\"2024-04-30T11:06:17.170896Z\",\"paymentRoutingInformation\":{\"accountNumber\":\"20000058715834\",\"country\":\"US\",\"routingInformation\":[{\"type\":\"ABA\",\"value\":\"028000024\"}]}}",
      "resourceObject": {
         "id": "14bbc55243d24e589c1eca6b723254df",
         "clientId": "1000020694",
         "type": "LIMITED_DDA",
         "label": "Taxes5834",
         "state": "CLOSED",
         "createdAt": "2024-04-30T11:06:17.170896Z",
         "paymentRoutingInformation": {
            "accountNumber": "20000058715834",
            "country": "US",
            "routingInformation": [{
               "type": "ABA",
               "value": "028000024"
            }]
         }
      }
}

Transactions examples

Event type - TRANSACTION_COMPLETED

Example TRANSACTION_COMPLETED
Json
{
    "eventId": "5119",
    "eventType": "TRANSACTION_COMPLETED",
    "resourceType": "TRANSACTIONS",
    "resource": "{\"id\":\"3ZJUCLKH3c1sIWk\",\"clientId\": \"1000010400\",\"transactionReferenceId\": \"2hjsa998931301jkj\",\"type\":\"ACH\",\"debtorAccountId\":\"d5aaf0db11e747daa2d955806f6eb14e\",\"recipientId\": \"d9dab78e-e366-4dde-ac9d-fb3f9d48437b\",\"amount\":\"20.88\",\"currency\":\"USD\",\"status\":\"COMPLETED\",\"paymentDate\":\"2024-04-23\",\"ledgerBalance\":\"10.00\"}",
    "resourceObject": {
      "id": "3ZJUCLKH3c1sIWk",
      "clientId": "1000010400",
      "transactionReferenceId": "2hjsa998931301jkj",
      "type": "ACH",
      "debtorAccountId": "d5aaf0db11e747daa2d955806f6eb14e",
      "recipientId": "d9dab78e-e366-4dde-ac9d-fb3f9d48437b",
      "amount": "20.88",
      "currency": "USD",
      "status": "COMPLETED",
      "paymentDate": "2024-04-23",
      "ledgerBalance": "10.00"
    }
}

Event type - TRANSACTION_COMPLETED RETURN

In some cases when you send an ACH payment, the payment can be returned by the receiving party's bank. This means that the ACH payment has technically completed, but will be returned after a period of time.

In this eventuality, you receive two notifications:

  1. When you send the payment, you receive a TRANSACTION_COMPLETED event to show that the ACH payment has been successfully sent.
  2. When the ACH return is received from the receiving party's bank, you will receive a second TRANSACTION_COMPLETED event with type: "RETURN". ACH returns are typically received within 2 banking days, but may be up to 60 days later.

You can see in the below payload:

  • type: "RETURN" - which means the transaction is a return of the original payment into your account.
  • originatingId - the transaction ID of the original transaction.
  • originatingTransactionType - the type of payment originally requested.
  • transactionReferenceId - the transactionReferenceId of payment originally requested.

If this repeatedly happens, or happens because your recipient's account has closed, you need to remove this recipient and add a new one for your client. ACH Return:

ACH Return
Json
{
    "eventId": "5120",
    "eventType": "TRANSACTION_COMPLETED",
    "resourceType": "TRANSACTIONS",
    "resource": "{\"id\":\"89JUCLKH3c1sIWk\",\"clientId\":\"1000010400\",\"type\":\"RETURN\",\"amount\":\"20.88\",\"currency\":\"USD\",\"status\":\"COMPLETED\",\"paymentDate\":\"2024-04-25\",\"transactionReferenceId\": \"2hjsa998931301jkj\",\"originatingId\":\"3ZJUCLKH3c1sIWk\",\"originatingTransactionType\":\"ACH_PAYOUT\",\"creditorAccountId\":\"d5aaf0db11e747daa2d955806f6eb14e\",\"memo\":\"ORIG CO NAME:JPMC C1 ORIG ID:1115241202  TRACE#:02100002112497667 EED:111112 IND ID:3ZJUCLKH3c1sIWk IND NAME:JPMC C1 R02 - ACCOUNT CLOSED O RIGIN# 1123897186 ACH RETURN BLK# 012  TRN: 11129037667TC\",\"ledgerBalance\":\"30.88\"}",
    "resourceObject": {
      "id": "89JUCLKH3c1sIWk",
      "clientId": "1000010400",
      "type": "RETURN",
      "amount": "20.88",
      "currency": "USD",
      "status": "COMPLETED",
      "paymentDate": "2024-04-25",
      "transactionReferenceId": "2hjsa998931301jkj",
      "originatingId": "3ZJUCLKH3c1sIWk",
      "originatingTransactionType": "ACH_PAYOUT",
      "creditorAccountId": "d5aaf0db11e747daa2d955806f6eb14e",
      "memo": "ORIG CO NAME:JPMC C1 ORIG ID:1115241202  TRACE#:02100002112497667 EED:111112 IND ID:3ZJUCLKH3c1sIWk IND NAME:JPMC C1 R02 - ACCOUNT CLOSED O RIGIN# 1123897186 ACH RETURN BLK# 012  TRN: 11129037667TC",
      "ledgerBalance": "30.88"
    },
    "error": {
      "title": "Returned Payment",
      "context": [
        {
        "code": "11007",
        "message": "Account number specified has been closed on the bank books"
        }
      ]
    }
}

Event type - TRANSACTION_FAILED_ACH

TRANSACTION_FAILED ACH
Json
{
    "eventId": "5121",
    "eventType": "TRANSACTION_FAILED",
    "resourceType": "TRANSACTIONS",
    "resource": "{\"id\":\"DF23CLKH3c1sHJG\",\"clientId\":\"1000010400\",\"type\":\"ACH\",\"amount\":\"11.23\",\"currency\":\"USD\",\"status\":\"REJECTED\",\"paymentDate\":\"2024-04-23\",\"transactionReferenceId\": \"Ajsa99893130er45\",\"debtorAccountId\":\"d5aaf0db11e747daa2d955806f6eb14e\",\"recipientId\": \"d9dab78e-e366-4dde-ac9d-fb3f9d48437b\",\"ledgerBalance\": \"10.00\"}",
    "resourceObject": {
      "id": "DF23CLKH3c1sHJG",
      "clientId": "1000010400",
      "type": "ACH",
      "amount": "11.23",
      "currency": "USD",
      "status": "REJECTED",
      "paymentDate": "2024-04-23",
      "transactionReferenceId": "Ajsa99893130er45",
      "debtorAccountId": "d5aaf0db11e747daa2d955806f6eb14e",
      "recipientId": "d9dab78e-e366-4dde-ac9d-fb3f9d48437b",
      "ledgerBalance": "10"
    },
    "error": {
      "title": "Rejected Payment",
      "context": [
        {
          "code": "11016",
          "message": "Amount of funds available to cover specified message amount is insufficient"
        }
      ]
    }
}

Event type - TRANSACTION_CHANGE_REQUESTED

TRANSACTION_CHANGE_REQUESTED is a Notification of Change (NOC) event for transactions. It notifies you, as the sender of an ACH payment, that you must correct or change information related to the recipient’s bank account. In Embedded Payments, this means you must add your client's linked account details again with the corrected values provided in the NOC.

This does not mean the transaction has failed. In most cases, the transaction referred to in the notification has been successful, but the updated details must be added before long, or transactions to this account may start to fail.

You can see in the below payload:

  • correctedValues - the values that need to be changed. For example, routing information, account number, or individual name.
  • transactionReferenceId - the transactionReferenceId of the payment for which the NOC has been received.
  • message - within the context object, the message tells you the reason for the NOC notification.
Transaction change requested
Json
{
    "eventId": "5124",
    "eventType": "TRANSACTION_CHANGE_REQUESTED",
    "resourceType": "TRANSACTIONS",
    "resources": {
      "id": "xgt1JePlO8tIxck",
      "transactionReferenceId": "oIctbxQ2pujoc8yc",
      "clientId": "1000010400",
      "recipientId": "d9dab78e-e366-4dde-ac9d-fb3f9d48437b",
      "changeDetails": {
        "title": "Clearing Notification of Change",
        "context": [
          {
            "code": "11401",
            "message": "Incorrect RTN and Account Number",
            "correctedValues": [
              {
                "value": "541798298",
                "field": "account.routingInformation.routingNumber"
              },
              {
                "value": "0182119492",
                "field": "account.accountNumber"
              }
            ]
          }
        ]
      }
    }
}

Recipient examples

Event type - RECIPIENT_READY_FOR_VALIDATION

For Linked Account recipient types. If your client must go through the validation process involving microdeposits, this notification tells you that the small deposits have been made and your client can check their linked account and verify the amounts that have been received.

Recipient ready for validation
Json
{
  "eventId": "817",
  "eventType": "RECIPIENT_READY_FOR_VALIDATION",
  "resourceType": "RECIPIENTS",
  "resource": "{\"id\":\"d9dab78e-e366-4dde-ac9d-fb3f9d48437b\",\"type\":\"LINKED_ACCOUNT\",\"status\":\"READY_FOR_VALIDATION\"}",
  "resourceObject": {
    "id": "d9dab78e-e366-4dde-ac9d-fb3f9d48437b",
    "type": "LINKED_ACCOUNT",
    "status": "READY_FOR_VALIDATION"
  }
}

Event type - RECIPIENT_READY_FOR_VALIDATION_REMINDER

For Linked Account recipient types. If your client must go through the validation process involving microdeposits, this notification reminds you that 17 days have passed since the validation process began, and the chance to verify the small deposits will soon expire. If 20 days pass, the validation process must be started again. 

Recipient ready for validation reminder
Json
{
  "eventId": "817",
  "eventType": "RECIPIENT_READY_FOR_VALIDATION_REMINDER",
  "resourceType": "RECIPIENTS",
  "resource": "{\"id\":\"d9dab78e-e366-4dde-ac9d-fb3f9d48437b\",\"type\":\"LINKED_ACCOUNT\",\"status\":\"READY_FOR_VALIDATION_REMINDER\"}",
  "resourceObject": {
    "id": "d9dab78e-e366-4dde-ac9d-fb3f9d48437b",
    "type": "LINKED_ACCOUNT",
    "status": "READY_FOR_VALIDATION_REMINDER"
  }
}

Event type - RECIPIENT_READY_FOR_VALIDATION_EXPIRED

For Linked Account recipient types. If your client must go through the validation process involving microdeposits, this notification tells you that the window of time for validation has closed, and you must repeat the process of adding the linked account to validate again. 

Json
{
  "eventId": "817",
  "eventType": "RECIPIENT_READY_FOR_VALIDATION_EXPIRED",
  "resourceType": "RECIPIENTS",
  "resource": "{\"id\":\"d9dab78e-e366-4dde-ac9d-fb3f9d48437b\",\"type\":\"LINKED_ACCOUNT\",\"status\":\"INACTIVE\"}",
  "resourceObject": {
    "id": "d9dab78e-e366-4dde-ac9d-fb3f9d48437b",
    "type": "LINKED_ACCOUNT",
    "status": "INACTIVE"
  }
}