Review Incoming Payments

TxB APIs allow Clients to receive Notifications when a third party attempts to debit or credit their TxB deposit accounts. Clients may subsequently approve or reject these incoming payments, based on their preferences and policies. Today, TxB supports notifications for incoming US ACH payments only.

Step by Step Guide

Step 1 - Fetch available notifications

Before you can manage a notification, you must first poll TxB to get the current list of eligible notifications.

GET /v1/notifications will return all notifications which have been created today. Clients can use query parameters to get other time periods or to manage pagination. This query returns:

[
  {
    "notificationId": 123,
    "notificationType": "INCOMING_PAYMENT",
    "creationTime": "2021-10-11T11:20:00.000Z",
    "expirationTime": "2021-10-13T00:00:00.000Z",
    "availableActions": [
        "APPROVE",
        "REJECT"
    ],
    "notificationStatus": "PENDING_ACTION",
    "notificationData" {

    // Details of an incoming ACH debit request

        "valueDate": "2021-10-12",
        "transactionType": "ACH Debit Payment",
        "debitOrCredit": "Debit",
        "amount": 59000.01,
        "amountCurrency": "USD",
        "remittanceInfo": [
            "Some important addenda information to pass along",
            "Addenda info running into multiple lines"
        ],
        "idNumber": "12345678",
        "gsUniquePaymentId": "gsuniqudid33",
        "debtorAccount": {
            "accountHolderName": "ACME Test Co, LLC",
            ...
        },
        "creditorAccount": {...},
        "railSpecificInfo": {
            "rail": "ACH",
            "ACHInfo": {
                "secCode": "CCD",
                "companyName": "acme's supplier ach name",
                "companyId": "886692877",
                "companyEntryDescription": "SUPPLIER PAYMENT",
                "companyDescriptiveDate": "OCT 12"
            }
        }
  }
]

Step 2 - Decide whether to allow the payment

Now, it is up to the Client to determine how they want to proceed with this payment. Some Clients will apply simple heuristics (e.g., if the payment is less than $100,000 and the creditor is one a list of favored suppliers, then allow it) while others will want to create their own maker / checker system to approve each payment. In each notification, the expirationTime will indicate the deadline by which all decisions are made. If the Client does not take an action, then TxB will apply the default behavior that was selected by the Client at the time of onboarding.

Step 3 - Take action on the notification

In this example, we will assume that this supplier is in good standing and the Client recently approved an invoice of the amount being requested. As such, we decide to accept the payment and allow it to proceed.

POST /v1/notifications/actions

with a request body of:

[
  {
    "notificationId": 123,
    "requestedAction": "APPROVE"
  }
]

which will generate a response from TxB of:

[
  {
    "notificationId": 123,
    "requestedAction": "APPROVE",
    "notificationStatus": "APPROVED"
  }
]

Step 4 - Verify the debit

An optional last step in the process is to re-fetch the transactionReport for this TxB deposit account. This report will typically update within a couple hours after a notification action.