Transaction Decisioning
Since all Subnet transactions are not originated through your platform, developers like to have higher level of control on transactions settling into user accounts. Especially withdrawals.
For that reason, we enable higher level of control on Subnet withdrawals, to address three needs:
    1.
    Ability to Pass/Fail a transaction based some custom criteria built on your side.
    2.
    Ability to Fund the withdrawal through another account at the time of transaction decisioning, not before.
    3.
    If the network allows, only approve a transaction partially.

Set up

Transaction decisioning a webhook request response flow. To enable an endpoint to receive webhooks when a Subnet withdrawal transaction is received, create a subscription with TRANS|POST|JIT scope. So something like this:
1
{
2
"scope": [
3
"TRANS|POST|JIT"
4
],
5
"url": "https://webhook.site/f765c7b8-4a73-4407-89e7-e1a6794004e8"
6
}
Copied!
On top of that, we would recommend building your custom transaction logic (e.g. restrict by transaction type, merchant profile, MCC, or other logic). Please review Meta Schema of RDFI ACH and Meta Schema of Card Transactions to find all the information we return.

Decisioning

To be able to decision a transaction, you need to respond in the following format:
Field
Type
Required
Description
decision
String
Yes
Supply PASS if you intend to let the transaction go through. Otherwise supply FAIL.
funding_nodes.node_id
String
No
Node ID where the supplied amount should be funded from.
funding_nodes.amount
Number
No
The amount that needs to be taken out of the supplied node id.
total_amount
Number
No
Total amount approved for the transaction. Can be lower than the amount on transaction if partial approval is allowed.
Upon receiving a withdrawal subnet transaction, we will notify you via the TRANS|POST|JIT webhook url. Your response will indicate to us whether to allow ("decision": "PASS") or deny ("decision": "FAIL") the transaction.
If the transaction is approved, then funds can be pulled directly from the account that the subnet sits on top of.
If using Partial Approval, the response will need to also supply the partially approved transaction's total_amount. If a transaction can be partially approved, you will see to.meta.partial_approval_allowed set to True. Go to Meta Schema of Card Transactions to learn more.
Alternatively, if you wish to fund the transaction from an account other than the account the subnet sits on top of, then you can pull funds directly from one or more funding nodes (either user or platform accounts) specified in the response.
    If funding for the transaction comes from multiple accounts (listed in the funding_nodes[] array supplied in the response), then you must both specify the exact amount to be pulled from each node and ensure that the overall transaction's total_amount field equals the sum of the amounts pulled from each funding node. If both of these criteria are not met, the transaction will silently fail.
    Please also note that providing an invalid node_id for any of the listed funding nodes will also cause the transaction to silently fail.

Testing

To be able to test Transaction Decisioning on UAT, you will need to be able to create fake subnet withdrawal transactions. For card subnets, you can do that with Virtual Terminal. While for account number subnets, you can do that with Dummy Transactions API calls.

Important Considerations

Following are some things to be mindful of while building with Transaction Decisioning:

Timely Response Considerations

Upon being notified of a new transaction request by the TRANS|POST|JIT webhook you will need to perform your custom transaction logic, provide funding (if using Instant Auth), and provide a response within 1.00 seconds, or the transaction will be declined.

Negative Balance Considerations

Funding from other nodes does not perform balance checks on the nodes due to the timely response considerations mentioned above (i.e. response required within 1.00s), meaning that use of this feature with a funding node that has insufficient funds to cover a transaction will make that node's balance go negative.
It is your responsibility to both perform periodic balance checks and to maintain an estimate of funding node balances to avoid this (i.e. to have a reasonable expectation that a funding node can cover a transaction before allowing it).

Debit Card Cashback Considerations

Consider how to handle transactions with a debit card cashback component (e.g. from a user who took a cash disbursement along with their purchase at a retail register). This information should be provided in the webhook's transaction request notification (e.g. "type": "PURCHASE_WITH_CASH_DISBURSEMENT" with sub_amounts[] array containing "amount_type": "AMOUNT_CASH"). You can either approve the full transaction amount, provide Partial Approval only for the purchased goods, or deny the transaction.

KYC Considerations

We will perform basic account and user KYC checks (e.g. making sure the user has SEND-AND-RECEIVE permissions and that the user watchlists flag is not a MATCH) prior to ever issuing a request from the TRANS|POST|JIT webhook. This means that you should not receive requests from users who are unable to transact.
Last modified 3mo ago