/check_instant_ach

Pre-check if a user(entity) qualifies for Instant ACH

This endpoint allows running checks at an entity level to confirm the end user would meet the requirements to have an instant ACH transaction run before they actually have to attempt a transaction.

📘

Before attempting an instant ACH transaction...

When running this check before attempting an instant ACH transaction, you should not only check this response for whether the end user qualifies or not, but you should also check that the maximum amount in this response exceeds the amount of the instant ACH transaction you will be attempting.

Requests

The account_name key is optional. Its string value of the existing bank account name.
if not provided, “default” will be used.

You also need to pass a kyc_level key into the request body if you have a specific KYC to check instant ach approvel for your entity. It's Optional.
if not provided, “INSTANT-ACH” will be used.

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/check_instant_ach 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, 
    "app_handle": "handle.silamoney.eth", 
    "user_handle":"user.silamoney.eth", 
    "version": "0.2", 
    "crypto": "ETH", 
    "reference": "<your unique id>"
  }, 
  "account_name": "Account Name",
  "kyc_level": "<KYC-LEVEL>" #optional
}

***

HTTP/1.1 200 OK

{
  "success": True,
  "maximum_amount": 100.00,
  "message": "Entity qualifies for Instant ACH.",
  "reference": "<your unique id>",
  "status": "SUCCESS",
  "response_time_ms": "171"
}

HTTP/1.1 200 OK

{
  "success": False,
  "message": "Entity does not qualify for instant ACH due to insufficient funds.",
  "reference": "<your unique id>",
  "status": "FAILED",
  "qualification_details": { 
    "kyc_level": "Entity has not passed INSTANT-ACH KYC level.",
    "sms_opt_in": "Entity has not opted into SMS notifications.",
    "plaid_products": "Bank account does not support both balance and transactions Plaid products.",   
    "ach_returns" : "Entity has recent returns."
  }
}
//kyc_level : optional field  
//Adding new additional value for kyc_level:  INSTANT-ACHV2

const res = await sila.checkInstantAch(
    { account_name: 'account name', kyc_level:"Kyc level" },
    userHandle,
    userPrivateKey
);


// Success Response Object
console.log(res.statusCode); // 200
console.log(res.data.reference); // Random reference number
console.log(res.data.status); // SUCCESS
console.log(res.data.message); // User has passed ID verification
payload = {
    "user_handle": 'user handle',
    "account_name": "account name",
    "kyc_level": "INSTANT-ACH"     #optional

}

response = silasdk.User.check_instant_ach(app, payload, 'user private key')

response['success']
response['message']
response['reference']
response['status']
ApiResponse response = api.checkInstantAch("account name", "user handle",
        "user private key","kyc level");

CheckInstantAchResponse parsedResponse = (CheckInstantAchResponse) response.getData();

parsedResponse.getStatus();
parsedResponse.getMessage();
parsedResponse.getReference();
parsedResponse.getSuccess();
parsedResponse.getMaximum_amount();
parsedResponse.getQualificationDetails();//message for Entity does not qualify for iACH
userHandle = 'user.silamoney.eth';
$userPrivateKey = 'some private key'; // Hex format
$accountName = 'some bank account name'; // Optional
$kycLevel = 'INSTANT-ACHV2';

$response = $client->checkInstantACH($userHandle, $userPrivateKey, $accountName, $kycLevel);

// Success 200
echo $response->getStatusCode(); // 200
echo $response->getData()->reference; // Random reference number
echo $response->getData()->status; // SUCCESS
echo $response->getData()->message; // Entity qualifies for instant ACH.
echo $response->getData()->qualification_details["sms_opt_in"];
var response = api.CheckInstantACH(
userHandle: "user handle",
userPrivateKey: "user private key",
accountName: "account name",
kycLevel: "INSTANT-ACH" // optional field
);

var parsedResponse = (CheckInstantACHResponse)response.Data;

parsedResponse.Message;
parsedResponse.Reference;
parsedResponse.Status;
parsedResponse.Success;
parsedResponse.MaximumAmount;
parsedResponse.QualificationDetails.SmsOptIn; //message Entity does not qualify for iACH
KeyTypeDescription
headerJSON objectRequired. 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.
account_nameStringOptional. Min length 1, Max length 40, Example: Custom Account Name
If not provided, “default” will be used.
kyc_levelStringOptional. The kyc_level field is used to request to check kyc level eligible for an entity.
bank_account_idStringOptional. Use the bank_account_id UUID found in /get_payment_methods to specify which account you are selecting. Used when end user has multiple accounts with the same account name.

Responses

The success attribute is a JSON key sent in the response body.

Status Codesuccess AttributeMessageDescription
200trueEntity qualifies for Instant ACH.The end user qualifies for an Instant ACH up to the maximum_amount.
200trueEntity qualifies for Instant ACH with maximum_amount='BALANCE_CHECK_ERROR'The end user's linked account is experiencing an error. Review Plaid_error_type and error_code for more details.
200falseEntity does not qualify for instant ACH due to insufficient funds.The end user does not have enough funds in their linked account.
200false"kyc_level": "Entity has not passed INSTANT-ACH KYC level."The end users has not passed a the required KYC level for Instant ACH.
200false"sms_opt_in": "Entity has not opted into SMS notifications."The end user has failed to opt in, or has opted out, of SMS.
200false"plaid_products": "Bank account does not support both balance and transactions Plaid products."The account linked by the end user does not support required Plaid products.
200false"ach_returns" : "Entity has recent returns."End users can not use Instant ACH if they have received returns recently
400falseBad request format.Bad request format.
400falseMultiple accounts found for the provided nickname. Please specify an account uuid.End user has linked payment methods with the same account name. Use /get_payment_methods to find the bank_account_id UUID of the account you want to us
401falseAuth signature is absent or derived address does not belong to app_handle.Bad request format.
404falseNo bank account for user with name found.Bad request format.

Additional error responses can be found here https://docs.silamoney.com/docs/check_instant_ach-errors