Skip to main content
Embedded Payments

Notification payload samples without OAuth

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

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

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

ACCOUNT_CLOSED

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

TRANSACTION_COMPLETED

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"
    }
}

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

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

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

Limit examples

THRESHOLD_LIMIT

For issued direct debits and balance management, you receive notifications based on preconfigured program-level limits set for each platform. Each platform has a maximum negative balance allowed across its program. There are three use cases for sending notifications:

  • Alert Percent: The lower-level limit that notifies the platform when it exceeds a specific percentage of its total negative balance allowance.
  • Restrict Percent: The upper-level limit, reached when the program limit is met. Transactions begin to fail at this point. The platform is responsible for working with users to address negative balances before reaching the maximum allowance.
  • Reset Percentages: Notifications triggered when platforms address negative balances. There are upper and lower reset percentages that send notifications once negative balances are resolved.
Threshold limit
Json
{
"header":   {
    "apiGatewayClientId" : "31590151",
    "callbackMessageType": "EMBEDDED_FINANCE_CLIENTS"
},
"payload":   {
    "eventId": "2039520235",
    "eventType": "THRESHOLD_LIMIT",  
    "resourceType":  "CLIENTS",
    "resourceObject": {
     "id": "100000234",
     "effectiveDate": "2024-09-09",
     "limitType": "AGGREGATE",
     "aggregateOverdrawn": {
              "amount": "-8000.00",
              "percent": "80",
              "maxAmount": "10000",
              "alertPercent": "80",
              "alertResetPercent": "70",
              "restrictPercent": "100",
              "restrictResetPercent": "90",
           }
       }
   }
}

The following provides a brief description of each field:

Threshold limit field description
Field                                             Description Notes
amount The current total negative balance for a platform's program. -
maxAmount The program-level maximum negative balance allowance. -
Percent The current percentage of the total program-level limit. amount divided by maxAmount
alertPercent The percentage of the maximum negative balance where you receive a warning. If set to 80 and the maximum negative balance is $10,000, you will receive a notification when your negative balance reaches $8,000, notifying that you are approaching towards the set negative balance limit.

alertResetPercent

 The percentage of the maximum negative balance where you receive a notification after addressing negative balances below the lower limit threshold. If set to 70 and the maximum negative balance is $10,000, you will receive a notification when your negative balance drops below $7,000. This serves as a prompt to address the negative balance.
restrictPercent The percentage of the maximum negative balance where you are notified that the program-level limit has been exceeded and transactions begin to fail. If set to 100 and the maximum negative balance is $10,000, transactions will fail when your negative balance reaches $10,000. At this point, you must address the negative balance before you can process additional transactions. 
restrictResetPercent The percentage of the maximum negative balance where you receive a notification after addressing negative balances below the upper limit threshold. If set to 90 and the maximum negative balance is $10,000, you will receive a notification when your negative balance drops below $9,000 after you have addressed the negative balance, but still remain at risk of approaching maxAmount.

Recipient examples

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"
  }
}

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"
  }
}

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. 

Recipient ready for validation expired
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"
  }
}

RECIPIENT_UPDATED

This notification tells you, as a sender of this ACH payment, that we updated the recipient's banking information after receiving a Notification of Change (NOC) transaction event.

The following provides a brief description of the updated fields:

recipient updated
Field Description
account The account values updated, such as routing number and account number (last four digits).
description This specifies the ACH transaction ID of the payment that received the NOC.
Json
{
  "header": {
    "apiGatewayClientId": "APIGW1234",
    "callbackMessageType": "EMBEDDED_FINANCE_RECIPIENTS",
    "eventId": 903
  },
  "payload": {
    "resourceType": "RECIPIENTS",
    "eventId": "903",
    "eventType": "RECIPIENT_UPDATED",
    "resourceObject": {
      "id": "d9dab78e-e366-4dde-ac9d-fb3f9d48437b",
      "clientId": "1000014667",
      "type": "RECIPIENT",
      "account": {
        "number": "9492",
        "routingInformation": [
          {
            "routingNumber": "541798298"
          }
        ]
      },
      "updatedAt": "2025-05-22T18:26:35.858220904Z",
      "description": "Received Notification Of Change on ACH transaction id - 1QaEnvTest9jkL0"
    }
  }
}