Sila API Docs | Sila Banking and Payments API

Welcome to the Sila API!

/issue_sila

Initiates an ACH Debit transaction on a specified bank account and issues SILAUSD tokens to the address belonging to the requested handle.

The /issue_sila endpoint starts the ACH Debit transaction of a user's linked bank account; once that transaction has officially settled, a process that takes about two business days to complete, the handle's blockchain address will be issued SILA tokens.

SILA tokens are pegged to the value of $0.01 USD. To request the debit of $795.43, for instance, you would request "amount": 79543.

Minimum transaction amounts for this endpoint are 1 SILA in sandbox, and 1 SILA in production.

Be aware that unless specified otherwise, the wallet to which tokens are issued is the one used to generate the usersignature header.

πŸ‘

/issue Timing

In SANDBOX, issuing Sila can take up to five minutes.

In PROD, issuing Sila will take a few business days, depending on when the request is issued. Read more about ACH timing here.

You can check the status of a transaction using the /get_transactions endpoint. You can also use webhooks to receive a notification when a transaction status is updated.

Requests

The request body at this endpoint is the /issue_sila JSON object.

Both authsignature and usersignature headers are required for this request.

The amount field is the amount of SILA tokens to issue, which is equivalent to a dollar amount x 100, or a number of cents. For example, to debit $1 from a user's account, you would request an amount of 100.

πŸ‘

Sandbox Failure State Testing

Standard and Same Day ACH: In the sandbox only, you can simulate an ACH return by sending any amount ending in 420, like 1420 ($14.20), 78420 ($784.20), or 420 ($4.20). This will always simulate an ACH return of type R01-Insufficient Funds

Instant ACH only: for testing instant ACH in sandbox, you can pass in the following amounts to test failures:

  • 37 ($0.37): Bank account not eligible (no fuzzy match was done)
  • 41 ($0.41): Transaction rejected (risk assessment failed)
    NOTE: Instant ACH is in closed beta. Your app must be registered with Sila to test this functionality.

πŸ‘

Sandbox businessUUID

For the purposes of testing /issue_sila in the Sandbox environment, you can use the business_uuid: a9f38290-ce34-42db-95ab-630ebba6084a.

For Instant ACH only: SMS notifications from this UUID will come from the company "Sila Test" and must be confirmed in order for the transaction to be processed.

The account_name field is the name of the handle's linked account from which to debit the equivalent dollar amount.

The optional descriptor field is a 100-character field used to describe the transaction on the end-user’s bank statement.

The optional business_uuid field identifies a business which has an approved "ACH name".

The optional processing_type field allows specifying either "STANDARD_ACH"to use the standard ACH schedule, "SAME_DAY_ACH" to use the same-day ACH schedule, or "INSTANT_ACH" to use the instant ACH schedule; by default, standard ACH will be used. See the ACH Processing Schedule for more details about the differences between standard ACH and same-day ACH schedules.

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.

πŸ“˜

Descriptors

Currently only the first 10 characters of the 100-character descriptor field will appear on the customer's statement. Default values are Debit or Credit and do not carry a surcharge. The use of a descriptor will incur an additional fee per transaction

πŸ“˜

ACH name

This is a 16 character field that appears on the end-user’s bank statement and reflects the company name responsible for the transaction. There is an additional application fee and process to approve the use of the company name.

POST /0.2/issue_sila HTTP/1.1
Host: sandbox.silamoney.com
authsignature: [GENERATED AUTHSIGNATURE HEX STRING HERE]
usersignature: [GENERATED USERSIGNATURE HEX STRING HERE]
Content-Type: application/json

{
  "header": {
    "created": 1234567890, 
    "app_handle": "handle.silamoney.eth", 
    "user_handle":"user.silamoney.eth", 
    "version": "0.2", 
    "crypto": "ETH", 
    "reference": "<your unique id>"
  }, 
  "message": "issue_msg",
  "amount": 1000,
  "account_name": "default",
  "descriptor": "optional transaction descriptor",
  "business_uuid": "UUID of a business with an approved ACH name",
  "processing_type": "STANDARD_ACH"
}

***

HTTP/1.1 200 OK

{
  "reference": "ref",
  "message": "Transaction submitted to the processing queue.",
  "success": true,
  "status": "SUCCESS",
  "response_time_ms": "171", 
  "transaction_id": "UUID of the submitted transaction",
  "descriptor": "optional transaction descriptor"
}
const res = await Sila.issueSila(
  amount,
  userHandle,
  walletPrivateKey,
  accountName,
  descriptor,
  businessUuid,
  processingType,
  cardName,
  sourceId,
  destinatiionId,
);
/*
Account Name is optional, OR "cardName": "your card name", never both. (defaults to 'default')
Descriptor is optional and sets the transaction description
BusinessUuid is optional and sets the ACH Name of the transaction
ProcessingType is optional and can be one of STANDARD_ACH or SAME_DAY_ACH or CARD
Card Name is Optional, OR "accountName": "default", never both.
sourceId: source account id to debit from (optional)
destinationId : destination account id for credit (optional)
*/

// Success Response Object

console.log(res.statusCode); // 200
console.log(res.data.reference); // Random reference number
console.log(res.data.success); // true
console.log(res.data.status); // SUCCESS
console.log(res.data.message); // Transaction submitted to processing queue
console.log(res.data.descriptor); // The transaction description set by you or blank if not set
console.log(res.data.transaction_id); // The transaction id
payload={
        "amount": 100000000000000000000000,                                        
        "user_handle":   "user.silamoney.eth",
        "descriptor": "Transaction Descriptor",
        "business_uuid": "UUID of a business with an approved ACH name",
        "account_name": "account name", # Either account_name or card_name or source_id
        "card_name": "card name", # Either account_name or card_name or source_id
        "source_id": "782bbd8c-ae27-4fb6-89e8-2675a1791382", # Either account_name or card_name or source_id
        "destination_id": "-782bbd8c-ae27-4fb6-89e8-2675a1791382", # Optional
        "processing_type": ProcessingTypes # Optional: Either .STANDARD_ACH or .SAME_DAY_ACH or INSTANT_SETTLEMENT
       }

Transaction.issueSila(silaApp,payload,user_private_key)

### Success Response Object
{
  reference: "ref",
  message: "Transaction submitted to the processing queue.",
  success: True,
  status: "SUCCESS",
  transaction_id: "UUID of the submitted transaction",
  descriptor: "optional transaction descriptor",
  status_code: 200
}

### Failure Response Object
{
    status: 'FAILURE'
}
AccountTransactionMessage issueMsg = AccountTransactionMessage.builder()
    .userHandle("user_handle")
    .userPrivateKey("user_private_key")
    .amount(100)
    .accountName("your_account_name")
    .descriptor("your custom descriptor") // Optional
    .businessUuid("some-business-uuid") // Optional
    .processingType(ProcessingTypeEnum.SAME_DAY) // Optional- SAME_DAY/STANDARD/INSTANT_ACH/CARD/INSTANT_SETTLEMENT
    .sourceId("source account id") // Optional
    .destinationId("destination account id") // Optional
    .build();
ApiResponse response = api.IssueSila(issueMsg);

// Success response
System.out.println(response.getStatusCode()); // 200
TransactionResponse parsedResponse = (TransactionResponse) response.getData();
System.out.println(parsedResponse.isSuccess());
System.out.println(parsedResponse.getReference()); // Random reference number
System.out.println(parsedResponse.getStatus()); // SUCCESS
System.out.println(parsedResponse.getMessage()); // Transaction submitted to processing queue.
System.out.println(parsedResponse.getTransactionId()); // Transaction id
System.out.println(parsedResponse.getDescriptor()); // The transaction descriptor (if was set)
use Silamoney\Client\Domain\AchType;

// Load your information
$userHandle = 'user.silamoney.eth';
$amount = 1000;
$accountName = 'Custom Account Name';
$userPrivateKey = 'some private key'; // Hex format
$descriptor = 'Transaction Descriptor'; // Optional
$businessUuid = 'you-business-uuid-code'; // Optional
$processingType = AchType::SAME_DAY(); // Optional. Currently supported values are STANDARD (default if not set) and SAME_DAY
$cardName = null;
$sourceId = "source id"; // optional
$destinationId = "destination id" //optional;

// Call the api
$response = $client->issueSila($userHandle, $amount, $accountName, $userPrivateKey, $descriptor, $businessUuid, $processingType, $cardName, $sourceId, $destinationId);

//Success 200

echo $response->getStatusCode(); // 200
echo $response->getData()->getReference(); // Random reference number
echo $response->getData()->getStatus(); // SUCCESS
echo $response->getData()->getMessage(); // Transaction submitted to processing queue.
echo $response->getData()->getDescriptor(); // Transaction Descriptor.
echo $response->getData()->getTransactionId(); // The transaction id.
string userHandle = "your-user-handle";
int amount = 1000;
string walletPrivateKey = "0x...";
string accountName = "your_account_nickname"; // optional
string descriptor = "optional transaction descriptor"; // optional
string businessUuid = "UUID of a business with an approved ACH name"; // optional
ProcessingType processingType = ProcessingType.Sameday; // optional
string cardName = "your_card_name"; // optional
string sourceId = "UUID of virtual account - represents the source - NEW!";  // optional
string destinationId = "UUID of virtual account - represents the destination - NEW!"; // optional

ApiResponse<object> response = api.IssueSila(userHandle, amount, walletPrivateKey, accountName, descriptor, businessUuid, processingType, cardName, sourceId, destinationId);

// Success Object Response

Console.WriteLine(response.StatusCode); // 200
Console.WriteLine(((TransactionResponse)response.Data).Reference); // Random reference number
Console.WriteLine(((TransactionResponse)response.Data).Status); // SUCCESS
Console.WriteLine(((TransactionResponse)response.Data).Message); // Transaction submitted to processing queue.
Console.WriteLine(((TransactionResponse)response.Data).Descriptor); // optional transaction descriptor
Console.WriteLine(((TransactionResponse)response.Data).TransactionId); // UUID of the submitted transaction

Key

Type

Description

header

JSON object

Required. Requires these keys in JSON format: created, app_handle, user_handle. See the /check_handle endpoint for the complete list of fields in this object.

amount

Integer

Required. Min Length 1, Max digits 35 Example: 1000
Max value: 10000000
Please contact Sila to increase.

account_name

String

Optional. Max Length 40. Name of the linked account to debit from that is the source of funds. Example: default

descriptor

String

Optional. Max Length 100
Note that only the first 10 characters show on the resulting bank statement. Example: transaction descriptor

business_uuid

String

Optional. UUID of a business with an approved ACH name.
The format should be a UUID string.
Example: 5167160d-9d12-4fa8-a8cd-302507782de0

processing_type

String

Optional. Choice field.
Examples: STANDARD_ACH, SAME_DAY_ACH, INSTANT_ACH, INSTANT_SETTLEMENT

source_id

String

Optional. Payment method ID that is the source of funds. These can be viewed using /get_payment_methods. This can be used as an alternative to account_name

destination_id

String

Optional. Payment method ID that is the destination of the funds. If not provided, the wallet in the usersignature of the header will be credited
Example: 5167160d-9d12-4fa8-a8cd-302507782de0

Note that either source_id or account_name must be specified as the source of funds.

Responses

Status Code

success Attribute

Description

error_code

200

true

Issuance process started.

Key not present in response.

400

false

Bad request format - check validation_details for more information.

Key not present in response.

401

false

authsignature or usersignature header was absent or incorrect.

Key not present in response.

403

false

Instant ACH failure: User not verified with INSTANT-ACH KYC level

INSTANT_ACH_INSUFFICIENT_KYC

403

false

Instant ACH failure: No business_uuid/ACH company name specified in request

INSTANT_ACH_NO_COMPANY_NAME

403

false

Instant ACH failure: Requested amount exceeded configured maximum

INSTANT_ACH_MAX_AMOUNT

403

false

Instant ACH failure: Bank account institution is not supported for Instant ACH

INSTANT_ACH_INSTITUTION_NOT_SUPPORTED

403

false

Instant ACH failure: App is not configured to be able to use Instant ACH

INSTANT_ACH_NOT_CONFIG

403

false

Instant Settlement failure: Instant Settlement is disabled for the application being used

INSTANT_SETTLEMENT_NOT_ENABLED

403

false

Instant Settlement failure: The transaction amount issued is more than minimum Reserve Wallet balance.

TRANSACTION_AMOUNT_HIGHER_THAN_MINIMUM_CRW_BALANCE

403

false

Instant Settlement failure: Application Reserve Wallet does not have sufficient balance, contact admin

INSUFFICIENT_RESERVE_WALLET_BALANCE

403

false

Failure with message "Bank account is not supported for WEB debits." due to the linked bank account having a web_debit_verified value of false where the app is configured to use the WEB SEC Code.

Key not present in response.

For transaction statuses, see: https://docs.silamoney.com/docs/issue-status-diagram

Updated 3 days ago


/issue_sila


Initiates an ACH Debit transaction on a specified bank account and issues SILAUSD tokens to the address belonging to the requested handle.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.