/transact
All-in-one endpoint for all transaction types and processing types.
This request triggers the issuance or remittance of funds with various options to customize how the payment is sent.
This doc has been updated with Priority specifications.
Standard options (included by default):
- Standard and Same Day ACH
- Wire (push only)
Other available options:
- ACHNow
- Transactions automatically cascade from fastest available option to next fastest available option instead of immediately failing.
- Functionality contractually bundled with the two below payment rails.
- RTP and FedNow
- Our supported instant payment rail options. Contractually bundled with ACHNow cascading functionality.
- Transactions can be sent via one of these rails without ACHNow cascading functionality if needed.
- Card (CKO integration, pull only)
SDKs
Only accessible through HTTP requests - the SDKs are not being updated to support this endpoint.
RfP (Request for Payment) Notifications & Timing
Please be aware that RfP notifications come from end users' respective banking institutions and are NOT within Sila's control. We cannot guarantee the timing of RfP transactions. Transactions will expire in 4 hours after initial transaction creation if the user receiving funds does not approve or deny the request.
We recommend advising your end users to verify their notifications are set up correctly with their respective banking institution.
If your end users are having trouble with receiving notifications, please reach out to the end user's banking institution.
Wires
Sila currently supports pushing funds out of wallets into linked bank accounts via wire. We are looking into supporting incoming wires with Priority as well.
Pre-requisites
- We must have the wire routing number for the bank account - to confirm this exists, call
/get_accounts
and check thewire_routing_number
value in the response.
To send with /transact
Set the route
value to wire
.
Testing RTP and FedNow instant rails in Sandbox
Because a specific routing number needs to be used to test RTP and FedNow rails, bank accounts must be linked manually in Sandbox.
Manual linking in Production is available only with explicit permission from Sila.
See the manual account linking doc here for more details.
Request
RTP and FedNow
Currently:
- RTP is available for both push and pull transactions (Sila wallet <> bank account)
- FedNow is only available for push transactions (Sila wallet > bank account)
Requirements
- Source of funds and destination for those funds are both required for transacting.
- Either the source or the destination must be a Sila-associated or Sila-linked account or wallet.
- Use
route
for specific route options like standard and Same Day ACH, card, and RTP.- Your app must be enabled for our Checkout integration or RTP and FedNow to make use of these features.
- NOTE: Because the default behavior is
fastest
, it is STRONGLY recommended that if you wish to use Standard ACH that you specify this in theroute
field.
- Use
route_selection_behavior
for ACHNow and behavior (fastest or cheapest) selections. - If neither a
route
orroute_selection_behavior
are provided, the request will default toroute_selection_behavior
=fastest
. Please see How Payment Route is Determined chart below for more. route
androute_selection_behavior
are mutually exclusive. Provide one or the other, NOT both, which will result in a 400 error.- The difference between
route_selection_behavior = ACHNow
androute_selection_behavior = fastest
: ACHNow will trigger a cascading behavior - trying the fastest route, then next fastest, and so on.fastest
will try the fastest route available, but will not cascade down to try the next fastest if that fails.
Transaction Amount in Decimal Units
Please be aware that the amount value for this endpoint is in decimal units, just like /issue and /redeem.
EX:
Transaction for $10 USD
/transact amount value = 1000
Authorization / Authentication
Apps using Access Token Authorization
Use a valid access token in an Authorization: Bearer request header.
See Authenticating with an Access Token for more details.
NOTE: Sila will support existing customers with ECDSA apps. New customers implementing ACHNow must use the JWT access token.
POST /0.2/transact HTTP/1.1
sandbox.silamoney.com
Content-Type: application/json
Authorization: Bearer [GENERATED JWT TOKEN HERE]
{
"header": {
"created": 1234567890, //required
"app_handle": "app_handle", // required
"user_handle":"user_handle", // required
"version": "0.2", // optional
"reference": "<your unique id>" // optional
},
"amount": 1000, //required
"source_id": "<ID to uniquely identify where funds are originating from>", // required
"destination_id": "<ID to uniquely identify the destination of funds>", // required
"route": "<how you want payment sent>", // required for card transactions
"route_selection_behavior": "fastest or cheapest", // optional, ACHNow only
"description": "transaction descriptor", // optional
"transaction_idempotency_id": "<UUID to uniquely identify a transaction for idempotency>", // optional
"transaction_idempotency_identifier": "<character string of any length to uniquely identify the transaction to prevent duplication>", // optional
"customer_reference": "customer chosen reference string", // optional
"ach_attributes": { // for ACH transactions, optional
"ach_descriptor": "ach descriptor in the NACHA file", // optional
"sec_code": "3-character SEC code" // optional
}
}
***
HTTP/1.1 200 OK
{
"reference": "<your unique id>",
"sila_reference_id": "sila_assigned_id",
"message": "Transaction submitted to the processing queue.",
"success": true,
"status": "SUCCESS",
"response_time_ms": "171",
"transaction_id": "UUID of the submitted transaction",
"itinerary_selected": "payement method used to move funds",
"description": "optional description for the transaction"
}
Request Attributes
Key | Type | Description |
---|---|---|
header | JSON object | Required. Required keys: created - Unix epoch timestamp in seconds. Must not be future-dated and must not be dated more than 5 minutes in the past.app_handle - your app handleuser_handle - the user_handle for the entity sending funds (source)Optional keys: reference : String. Can be any value for your own reference. If not provided, one will be assigned.version : Cannot be null if key is present. Valid values: 0.2, v0.2, V0.2 |
amount | integer | Required. Amount, in decimal units (ie, $10.00 in USD is 1000). Amount must be $10 USD or below for test transactions in Sandbox environment. |
source_id | string | Required. Payment instrument id where the funds are originate from. Must belong to the user_handle provided in the body header. Can be found with /get_payment_methods. |
destination_id | string | Required. Payment instrument id where the funds are sent to. Can be found with /get_payment_methods. |
route | string | Required for card transactions. Optional otherwise. Strongly recommended if you wish to use Standard ACH. What route you want the payment sent by. Valid options: ach (standard ACH)same_day_ach card (for CKO integration)rtp fednow (only for push, wallet > bank account)internal (for wallet > wallet transfers)wire (push only)If not supplied, default will be route_selection_behavior = fastest . |
route_selection_behavior | string | Optional. Based on attribute provided, route will be determined for the customer on the backend. fastest cheapest ACHNow (case sensitive)real_time_only - checks RTP and FedNow, but doesn't cascade further under any circumstancesIf not supplied, will default to fastest . |
description | string | Optional. Description sent to the receiver. Max 100 characters. Wires will use the first 40 characters. ACH uses first 10 characters. |
transaction_idempotency_id | UUID | Optional. UUID to uniquely identify the transaction to make it idempotent. If transaction is submitted multiple times with the same amount, source, destination, and transaction_idempotency_id, it will only be processed once. |
transaction_idempotency_identifier | String | Optional. If provided, it will be the sole determinant of uniqueness. |
ACH-Specific Attributes
Key | Type | Description |
---|---|---|
ach_descriptor | string | Optional. Max 10 characters. Description for receiver, passed along in the NACHA file |
sec_code | string | Optional. 3 character limit. Specify the SEC code you wish to use. |
Responses
Status Code | Success Attribute | Description | error_code |
---|---|---|---|
200 | true | ||
403 | false | The fields provided would result in a transaction that cannot be processed. For example, a standard ACH transaction that would arrive on the same day. | TX_NOT_POSSIBLE |
400 | false | The fields provided are invalid. | |
400 | false | The mock error header provided does not apply to the transaction being submitted | |
403 | false | App has not been enabled for ACHNow use. |
selected_itinerary
terminology
selected_itinerary
terminology- ach_issue: bank account -> user wallet via ACH ("ACH pull")
- ach_redeem: user wallet -> bank account via ACH ("ACH push")
- ledger_to_ledger: user wallet -> user wallet
- card_cko: debit card -> user wallet
- same_day_ach_pull: identical to ach_issue, but is sent to the Federal Reserve via one of multiple cutoff windows rather that in a single batch at the end of business day.
- same_day_ach_push: identical to ach_redeem, but is sent to the Federal Reserve via one of multiple cutoff windwos rather that in a single batch at the end of business day.
- rtp_pull: bank account -> user wallet via the RTP network
- rtp_push: user wallet -> bank_account via the RTP network
- fednow_push - bank account -> user wallet via the FedNow network
How is the Payment Route Determined?
Below is a table that can be used to help determine which payment route will be used in which case.
The "->" represents a fall back, if the method to the left of the arrow is not configured then the method to the right of the arrow will be used.
Source Type | Destination Type | Route Selection Behavior | Route Selection | Resulting Transaction Itinerary |
---|---|---|---|---|
Sila Wallet | Sila Wallet | fastest | ledger to leger | |
Sila Wallet | Sila Wallet | cheapest | ledger to ledger | |
Sila Wallet | Sila Wallet | internal | ledger to ledger | |
Bank Account | Sila Wallet | fastest | RTP if possible → Same Day ACH | |
Bank Account | Sila Wallet | cheapest | Standard ACH | |
Bank Account | Sila Wallet | rtp | RTP | |
Bank Account | Sila Wallet | same_day_ach | Same Day ACH | |
Bank Account | Sila Wallet | ach | Standard ACH | |
Sila Wallet | Bank Account | fastest | RTP if possible → Same Day ACH | |
Sila Wallet | Bank Account | cheapest | Standard ACH | |
Sila Wallet | Bank Account | rtp | RTP | |
Sila Wallet | Bank Account | same_day_ach | Same Day ACH | |
Sila Wallet | Bank Account | ach | Standard ACH |
Payment routes in order of speed (fastest to slowest):
- RTP (instant)
- Same Day ACH (1 day)
- Standard ACH (approx. 3 days)
Payment routes in order of cost (cheapest to most expensive):
- Standard ACH
- Same Day ACH
- RTP
Mocking Errors
You can set the Sila-Mock-Error
header in a request in order to mock an error in Sandbox. The error mocked will be based on the value of the header. Please see the table below for the which values mock which errors:
Sila-Mock-Error value | Description |
---|---|
aws-sqs-timeout | Mocks an AWS timeout, as if AWS sqs was not functioning correctly. |
rtp-ignore-limit | Ignores the limit on RTP transactions. |
app-not-ach-enabled | App is not enabled for ACH transactions. |
incomplete-ach-acpar-data | App is missing setup information needed to transact. |
Note that if the header does not apply to the transaction information provided, a 400 error will be returned.
Updated 18 days ago