API References
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
decisionString
Yes
Supply
PASS if you intend to let the transaction go through. Otherwise supply FAIL.funding_nodes.node_idString
No
Node ID where the supplied amount should be funded from.
funding_nodes.amountNumber
No
The amount that needs to be taken out of the supplied node id.
funding_nodes.assetString
No
If the funding node is
CRYPTO-US, this field can be used to supply the asset you wish to liquidate to honor the transaction. This field directly impacts the extra.asset field of the funding transaction. See more details in Transactions Extra Schema.total_amountNumber
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 exactamountto be pulled from each node and ensure that the overall transaction'stotal_amountfield 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_idfor 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 else the transaction will follow the default path of decisioning.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