API Reference

Usage

Web hooks can be configured for any account. If a web hooks is NOT configured, Trice will search for the account's parent account and distribute the web hook to the parent if the parent has a web hook configured.

If a web hook fails and the receiver does not respond with a 20X code, the web hook will be attempted again at the following cadence for up to 5 re-tries:

📘

Web Hook Re-try Schedule

re-tryseconds after original web hook
110
2100
31000
410000
5100000 (1.15 days)

1 web hook can be created of each type. Five different types of web hooks can be created:

  • rtp_transfer_inbound - triggers on all inbound transfer state changes listed below
  • rtp_transfer_outbound - triggers on all outbound transfer state changes listed below
  • fednow_transfer_inbound - triggers on all inbound transfer state changes listed below
  • fednow_transfer_outbound - triggers on all outbound transfer state changes listed below
  • rtp_rfp_outbound - triggers on all request for payment state changes listed below
  • rtp_rfp_inbound - triggers on all request for payment state changes listed below
  • rtp_rfp_presentment - triggers on all request for payment presentment state changes listed below
  • account - triggers on all status or hold_details changes for an account or on account creation if status returns on_hold
  • person - triggers on all status or hold_details changes for a person or on person creation if status returns on_hold
  • party - triggers on all status or hold_details changes for a party or on party creation if status returns on_hold
  • network_status - triggers on all status changes from the network. For FedNow, this is when routing numbers sign off or sign on to the network. For the RTP network, this is when participants sign off or sign on to the network. Participants in the RTP network frequently manage several routing numbers.
  • enrollment_balance - triggers on all enrollment_balance changes that result in less than the available_threshold limit that is configured in options for the designated enrollment. Balance changes from both topup and payout will not trigger this web hook.
  • default - if it is defined, it will trigger on any undefined web hook type

Trice will include the X-TRICE-WEBHOOK-TYPE header in the PUT which contains the web hook type associated with the web hook:

📘

Web Hook Type Header

X-TRICE-WEBHOOK-TYPE: rtp_transfer_inbound

Trice will include the X-TRICE-WEBHOOK-URI-ACCOUNT header in the PUT which contains the account id associated with the web hook URI being used:

📘

Web Hook URI Account Header

X-TRICE-WEBHOOK-URI-ACCOUNT: 669774a5-dbbc-481f-99ab-8c7c99d57766

Trice will include the X-TRICE-ACCOUNT header in the PUT which contains the account id associated with the web hook action:

📘

Web Hook Account Header

X-TRICE-ACCOUNT: 669774a5-dbbc-481f-99ab-8c7c99d57777

Trice will include the X-TRICE-SIGNATURE header in the PUT which contains a Base64 formatted HMAC-SHA256 signature of the PUT body content when sending a request to the web hook:

📘

Web Hook Signature Header

X-TRICE-SIGNATURE: qnq3xgpq5e5HuDGcASNNCHCoCi4qO9iSveSZ1yW0eZA=

Header value calculation:

Base64(
    HMAC-SHA256(
         YourSecretKey,
         X-TRICE-ACCOUNT_value+
         X-TRICE-WEBHOOK-URI-ACCOUNT_value+
         X-TRICE-WEBHOOK-TYPE_value+
         PUT_body_content
    )
  );

Your secret_key will only be returned in the POST to create the webhook. All subsequent GET calls will have the secret_key as null.

Web hooks will be Restful PUT to your defined web hook uri on status changes of these objects

  • RTP Transfer status
  • RTP RfP Presentment status
  • RTP RfP status

The PUT content will be the JSON object of the rtp_transfer if the web hook type is rtp_transfer_inbound or rtp_transfer_outbound.

The PUT content will be the JSON object of the rtp_rfp if the web hook type is rtp_rfp_outbound or rtp_rfp_inbound.

The PUT content will be the JSON object of the rtp_rfp_presentment if the web hook type is rtp_rfp_presentment.

State changes that trigger web hooks

Outbound and Inbound RTP transfers

For rtp_transfers, the following state changes will trigger a web hook:

  • rejected - final state
  • failed - final state
  • timed_out - final state
  • completed - final state, with the exception of returned
  • returned - final state

Outbound and Inbound FedNow transfers

For fednow_transfers, the following state changes will trigger a web hook:

  • rejected - final state
  • failed - final state
  • timed_out - final state
  • completed - final state, with the exception of returned
  • returned - final state

Outbound and Inbound RTP Request for Payment

For rtp_rfps, the following state changes will trigger a web hook:

  • rejected - final state
  • failed - final state
  • timed_out - final state
  • approved
  • paid - final state
  • declined - final state
  • expired - final state
  • canceled - final state
  • waiting

RTP Request for Payment Presentments

For rtp_rfp_presentments, the following status changes will trigger a web hook:

  • reviewed
  • approved - final status
  • denied - final status
  • on_hold

Account, Person, and Party

For account, person, party the following status changes will trigger a web hook:

  • on_hold - any change in status, including initial creation
  • hold_details - any updates, including initial creation

Network Status

For network_status the following status changes will trigger a web hook:

  • If a participant on the RTP network signs off or signs on
  • If a routing number on the FedNow networks signs off or signs on

Enrollment Balance

For enrollment_balance the following status changes will trigger a web hook:

  • If an enrollment balance changes and is less than the available_threshold that is configured for the enrollment_id that is configured in options
  • If the enrollment_id is omitted from options then any enrollment_id will trigger a web hook.
  • If the available_threshold is set to 0 then any balance change will trigger a web hook.