Webhooks

As the Avenu API platform matures we will be implementing more and more Webhooks. As we release webhooks they will be added here, and announced in the Changelog.

Setup

1. Contact Avenu Support

Reach out to Avenu support via email, slack, or through the Partner Portal with a request to start receiving webhook notifications. The first thing we'll need is the URL to which you'd like the webhook notifications sent. Once we have received your URL, we'll implement the configuration in Avenu and securely provide you with a secretKey. Note that your URL should be configured to receive POST notifications. Examples of the payload format for notifications can be found below. It should respond with 2xx for success and 4xx for failures. At this time, notifications are not resent for failures.

2. Use the secretKey in your implementation to receive webhooks

When a webhook notification is sent, Avenu generates a hash value of the webhook data payload using the shared secretKey. This hash value is sent as a custom header "X-Signature". Avenu generates this hash value using HmacAlgorithms.HMAC_SHA_256 algorithm of HmacUtils.

From your end when the webhook notification is received, your application using the webhook data payload and the shared secret key calculates the signature using the same algorithm (HmacAlgorithms.HMAC_SHA_256) that Avenu used (See code example below). Then the calculated signature is used to verify the "X-Signature" header value.

public PaymentWebhookResponse processNotification(String key, String signature, String json, WebhookPaymentNotificationPayload notification) {
  // Check signature
  log.debug("Checking signature: {} with key: {}", signature, key);
  final String expectedSignature = signValue(key, json);
  if (expectedSignature == null) {
    return new PaymentWebhookResponse(false, "Bad signing key! Got: " + key);
  } else if (!expectedSignature.equalsIgnoreCase(signature)) {
    log.error("Bad signature using key: \"{}\"! Expecting: {}", key, expectedSignature);
    return new PaymentWebhookResponse(false, "Bad signature! Expecting: " + expectedSignature);
  }
  return new PaymentWebhookResponse(true, toResponseStatus(notification));
}
private String signValue(String key, String value) {
  try {
    return hmac.get(key, () -> new HmacUtils(HMAC_SHA_256, key)).hmacHex(value);
  } catch (Exception e) {
    log.error("Could not generate HMAC-SHA256 signature", e);
    return null;
  }
}

3. Test receiving webhook notifications

Once you're ready, create a test transaction and check your logs for receiving the notification. Please reach out to Avenu support if you run into any issues.

Payments

When payment status changes occur to any of the following payment types an update will be sent to the client's application:

ACH - Payment to/from an ACH account
Avenu - Payment between Avenu customers
Debit_Card_Fund - Denotes a debit card funding
ACH_TRANSFER - Denotes a payment created through the client/v1/transfer endpoint
TRANSFER_REFUND - Denotes a payment created through the client/v1/transferrefund endpoint

Available statuses are:

PENDING - A payment has been created and is waiting settlement. Current Balance has been updated
FAILED - A payment has not been created and is in a failed state
SETTLED - A created payment has been settled and Available Balance has been updated
DECLINED - A payment has been declined
CANCELED - A created payment has been canceled

Payment Status Webhook Notification Examples

Payment start webhook notification

{
  "type": "payment",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "customer": {
        "accountNumber" : "12345"
    },
    "transaction": {        
        "id": "12345abc",
        "type": "ACH",
        "status": "PENDING",
        "transactionResponse": {
            "type": "PAYMENT",
            "description": "Payment transaction initiated",
            "dateUpdated": "2021-12-07T00:21:40.670058Z"
        }        
    }
  }
}

Payment authorization approved notification (debit fund)

{
  "type": "payment",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "customer": {
        "accountNumber" : "12345"
    },
    "transaction": {        
        "id": "12345abc",
        "type": "DEBIT_CARD_FUND",
        "status": "PENDING",
        "transactionResponse": {
            "type": "AUTHORIZED",
            "description": "Transaction Accepted",
            "dateUpdated": "2021-12-07T00:21:40.670058Z"
        }        
    }
  }
}

Payment authorization declined notification (debit fund)

{
  "type": "payment",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "customer": {
        "accountNumber" : "12345"
    },
    "transaction": {        
        "id": "12345abc",
        "type": "DEBIT_CARD_FUND",
        "status": "CANCELLED",
        "transactionResponse": {
            "type": "TRANSACTION",
            "description": "Transaction Declined, full address does not match",
            "dateUpdated": "2021-12-07T00:21:40.670058Z"
        }        
    }
  }
}

Payment capture approved notification (debit fund)

{
  "type": "payment",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "customer": {
        "accountNumber" : "12345"
    },
    "transaction": {        
        "id": "12345abc",
        "type": "DEBIT_CARD_FUND",
        "status": "PENDING",
        "transactionResponse": {
            "type": "CAPTURED",
            "description": "Transaction Accepted",
            "dateUpdated": "2021-12-07T00:21:40.670058Z"
        }        
    }
  }
}

Payment capture declined notification (debit fund)

{
  "type": "payment",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "customer": {
        "accountNumber" : "12345"
    },
    "transaction": {        
        "id": "12345abc",
        "type": "DEBIT_CARD_FUND",
        "status": "CANCELLED",
        "transactionResponse": {
            "type": "TRANSACTION",
            "description": "Transaction Declined",
            "dateUpdated": "2021-12-07T00:21:40.670058Z"
        }        
    }
  }
}

Payment sub-ledger update notification (PENDING)

{
  "type": "payment",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "customer": {
        "accountNumber" : "12345"
    },
    "transaction": {        
        "id": "12345abc",
        "type": "DEBIT_CARD_FUND",
        "status": "PENDING",
        "transactionResponse": {
            "type": "TRANSACTION",
            "description": "Transaction updated",
            "dateUpdated": "2021-12-07T00:21:40.670058Z"
        }        
    }
  }
}

Payment sub-ledger update notification (SETTLED)

{
  "type": "payment",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "customer": {
        "accountNumber" : "12345"
    },
    "transaction": {        
        "id": "12345abc",
        "type": "DEBIT_CARD_FUND",
        "status": "SETTLED",
        "transactionResponse": {
            "type": "TRANSACTION",
            "description": "Transaction updated",
            "dateUpdated": "2021-12-07T00:21:40.670058Z"
        }        
    }
  }
}

Payment account name verification failed notification (ACH)

{
  "type": "payment",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "customer": {
        "accountNumber" : "12345"
    },
    "transaction": {        
        "id": "12345abc",
        "type": "ACH",
        "status": "CANCELLED",
        "transactionResponse": {
            "type": "TRANSACTION",
            "description": "surnameMatch NO,givenNameMatch NO",
            "dateUpdated": "2021-12-07T00:21:40.670058Z"
        }        
    }
  }
}

Payment fraud check failed notification

{
  "type": "payment",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "customer": {
        "accountNumber" : "12345"
    },
    "transaction": {        
        "id": "12345abc",
        "type": "ACH",
        "status": "CANCELLED",
        "transactionResponse": {
            "type": "TRANSACTION",
            "description": "Transaction got declined. Please contact a system administrator.",
            "dateUpdated": "2021-12-07T00:21:40.670058Z"
        }        
    }
  }
}