/transact
Our newest endpoint for transacting. Must be used to make use of our new ACHNow product, or use instant rails.
This request triggers the issuance or remittance of funds with various options to customize how the payment is sent. With this endpoint, you can send payments either as regular ACH transactions, or via ACHNow. Other custom options include if the payment should be sent via the fastest or cheapest route, and if ACH payments should be sent via Instant Settlement or Same Day.
Accessibility
Only accessible through HTTP requests.
We are not updating SDKs to support this endpoint.
Your app must be enabled by Sila to use RTP or ACHNow.
To Use ACHNow
You must use this endpoint to use ACHNow. /issue_sila and /redeem_sila will not use this feature.
For now, this endpoint can be used to move funds between Sila Wallets, Virtual Accounts, and linked bank accounts, but will be opened up to accepting many different payment instrument options as the source or the destination.
Sending an ACH transaction via Instant Settlement
When an ACH payment is sent via Instant Settlement, the Sila-side location is credited or debited immediately. Because we are not yet able to control the routes themselves, the transaction may not land in the outside account until later.
If you would like the payment to land as soon as possible to the outside account, we recommend making use of the Same Day ACH method.
Request
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_selection
for non-ACHNow transactions (options for standard and sameday ACH, instant settlement, card, and RTP).- Your app must be enabled for instant settlement, the Checkout integration, or RTP to make use of those 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_selection
field.
- Use
route_selection_behavior
for ACHNow transactions (fastest or cheapest). - If neither a
route_selection
orroute_selection_behavior
are provided, the request will default toroute_selection_behavior
=fastest
. Please see How Payment Route is Determined chart below for more.
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
ACHNow Amount in Sandbox
If testing ACHNow in Sandbox, the amount MUST be $10.00 or less, or you will receive a 400 error.
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.
Apps using ECDSA Authentication
Both authsignature
and usersignature
headers are required for this request. The usersignature header should be generated with a keypair registered to the user (either registered from the /register endpoint or the /register_wallet endpoint).
See the section on ECDSA Authentication for more detail about ECDSA signature generation.
Note - We recently renamed the field auth_handle
to app_handle
. For backward compatibility, auth_handle
is still valid but has been removed from our documentation.
POST /0.2/transact HTTP/1.1
sandbox.silamoney.com
Content-Type: application/json
// if using OAuth2
Authorization: Bearer [GENERATED JWT TOKEN HERE]
// if using ECDSA
authsignature: [GENERATED AUTHSIGNATURE HEX STRING HERE]
usersignature: [GENERATED USERSIGNATURE HEX STRING HERE]
{
"header": {
"created": 1234567890, //required
"app_handle": "handle.silamoney.eth", //required
"user_handle":"user.silamoney.eth", //required
"version": "0.2",
"crypto": "ETH",
"reference": "<your unique id>"
},
"sardine_session_key": "<session key provided to Sardine>", //optional for Stearns
"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_selection": "<how you want payment sent>", //optional for non-ACHNow
"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
"customer_reference": "customer chosen reference string", //optional
"ach_attributes": { //optional for ach transactions
"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>",
"message": "Transaction submitted to the processing queue.",
"success": true,
"status": "SUCCESS",
"response_time_ms": "171",
"transaction_id": "UUID of the submitted transaction",
"route_selected": "payement method used to move funds",
"description": "optional description for the transaction"
}
Request Attributes
Key | Type | Description |
---|---|---|
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. |
destination_id | string | Required. Payment instrument id where the funds are sent to. |
route_selection | string | Optional, but strongly recommended, for non-ACHNow transactions. DO NOT USE WITH ACHNOW. What route you want the payment sent by. Valid options: ach (standard ACH) same_day_ach instant_settlement card (for CKO integration) rtp internal (for wallet > wallet transfers) If not supplied, default will be route_selection_behavior = fastest . |
route_selection_behavior | string | Optional. ACHNow transactions ONLY. DO NOT USE FOR NON-ACHNOW. fastest or cheapest If not supplied, will default to fastest. |
description | string | Optional. |
transaction_idempotency_id | string | Optional. UUID to uniquely identify the transaction to make it idempotent. If transaction is submitted multiple times with the same transaction_idempotency_id, it will only be processed once. |
customer_reference | string | Optional. Unique ID, used to group a series of transactions together under one ID |
ACH-Specific Attributes
Key | Type | Description |
---|---|---|
ach_descriptor | string | Required. Max 10 characters. Description for receiver, will be 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 |
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 | instant_settlement → rtp → sameday ach → standard ach | |
Bank Account | Sila Wallet | cheapest | standard ach | |
Bank Account | Sila Wallet | instant_settlement | instant_settlement | |
Bank Account | Sila Wallet | rtp | rtp | |
Bank Account | Sila Wallet | same_day_ach | sameday ach | |
Bank Account | Sila Wallet | ach | standard ach | |
Sila Wallet | Bank Account | fastest | rtp → sameday ach → standard ach | |
Sila Wallet | Bank Account | cheapest | standard ach | |
Sila Wallet | Bank Account | rtp | rtp | |
Sila Wallet | Bank Account | same_day_ach | sameday ach | |
Sila Wallet | Bank Account | ach | standard ach |
Payment routes in order of speed (fastest to slowest):
- Instant Settlement (instant)
- RTP (instant)
- Sameday ACH (1 day)
- Standard ACH (approx. 3 days)
Payment routes in order of cost (cheapest to most expensive):
- Standard ACH
- Sameday ACH
- RTP
- Instant Settlement
Please note that Instant Settlement is only valid for transactions from a bank account to a Sila Wallet.
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. |
ach-return-r<return code digits> | Mocks a standard ach return with the specified return code. Example: ach_return_r05 mocks an R05 return |
ach-late-return-r<return code digits> | Mocks a late dated ach return with the specified return code. Example: ach_late_return_r16 mocks an R16 return |
insufficent-funds | Mocks a insufficient funds error. |
delay-<time amt><time units> | Mocks a delay in processing the transaction due to a service outage. Exmaple: delay-10m mocks a 10 minute processing delay. delay-10d mocks a 10 day delay |
rtp-failure | Mocks a failure during an RTP transaction |
rtp-bank-not-supported | Mocks the associated bank being unable to perform RTP transactions |
reserve-wallet-warning | Causes the response to return the reserve wallet low warning response |
reserve-wallet-nsf | Mocks the reserve wallet not having enough funds for the transaction |
limit-exceeded | Mocks the fund limit for the endpoint being exceeded |
rtp-bank-debit-unsupported | Mocks the associated bank being unable to accept RTP debits (RTP RfPs / RTP Pulls) |
rtp-bank-credit-unsupported | Mocks the associated bank being unable to accept RTP credits (RTP pushes) |
Note that if the header does not apply to the transaction information provided, a 400 error will be returned.
Updated 4 days ago