/cancel_transaction

Cancel a pending Issue and Redeem Sila transaction under certain circumstances

Introduction

Occasionally you or your end user may need to stop an Issue and Redeem Sila transaction from being submitted to us, and this endpoints allows you to do just that. However, there is a point in time beyond which a transaction cannot be canceled.Making use of our /get_transaction endpoint surfaces the point of no return.

What Transactions Can Be Canceled?

Issue and Redeem transactions can be canceled.
In the /get_transaction server response body if the values for the following two keys are NULL then the transaction can still be canceled with this endpoint.

...
"submitted": NULL,
"submitted_epoch": NULL,
...

If, however, these two keys have timestamps for their corresponding values it's too late to cancel the transactions either by API or any other means.

/redeem_sila request only will be canceled if ACH processing types is STANDARD_ACH or SAME_DAY_ACH.

/issue_sila request are submitted for final processing at 9:30am PT for SAME_DAY_ACH transactions and 5:30pm PT for STANDARD_ACH transactions Monday through Friday. You have up until those times to cancel any Issue Sila transactions.

🚧

Too late to cancel?

Should you find yourself in the situation where a transaction cannot be canceled via our API, it would be wise to reach out to Sila support. Know that having the end users's bank account cancel the transaction will result in an unauthorized return for you, and you should never advise your customer to do this. Reach out to Sila support instead.

Requests

The request body at this endpoint is the header_msg JSON object.

header.user_handle should have the registered handle to be verified.

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/cancel_transaction 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>"
  },
  "transaction_id": "80aea226-76a3-4b60-a629-25a2db572ec8"
}

***

HTTP/1.1 200 OK

{
  "success": true,
  "status": "SUCCESS",
  "response_time_ms": "171",
  "message": "Transaction 80aea226-76a3-4b60-a629-25a2db572ec8 has been canceled.",
  "reference": "<your unique id>"
}
const res = await sila.cancelTransaction(
  userHandle,
  userPrivateKey,
  transactionid,
);

// Success Response Object

console.log(res.statusCode); // 200
console.log(res.data.reference);
console.log(res.data.success); // true
console.log(res.data.status); // SUCCESS
console.log(res.data.message); // Transaction some-uuid-code has been canceled.
payload = {
    "user_handle": user_handle,
    "transaction_id": transaction_id
}

response = silasdk.Transaction.cancelTransaction(app, payload, eth_private_key)

# Success Response Object
{
    success: True,
    message: 'Transaction 80aea226-76a3-4b60-a629-25a2db572ec8 has been canceled.',
    reference: 'ref',
    status: 'SUCCESS',
    status_code: 200
}

# Failure Response Object
{
    status: 'FAILURE'
}
CancelTransactionMessage cancelMsg = CancelTransactionMessage.builder()
        .userHandle("user_handle")
        .userPrivateKey("user_private_key")
        .transactionId("some-uuid-code")
        .build();
ApiResponse response = api.cancelTransaction(cancelMsg);

// Success response
System.out.println(response.getStatusCode()); // 200
BaseResponse parsedResponse = (BaseResponse) response.getData();
System.out.println(parsedResponse.getReference());
System.out.println(parsedResponse.getSuccess()); // true
System.out.println(parsedResponse.getStatus()); // SUCCESS
System.out.println(parsedResponse.getMessage()); // Transaction some-uuid-code has been canceled
$userHandle = 'user.silamoney.eth';
$privateKey = 'some private key';
$transactionId = 'some-transac-id';
$response = $client->cancelTransaction($userHandle, $privateKey, $transactionId);

echo $response->getStatusCode(); // 200
echo $response->getData()->success; // TRUE
echo $response->getData()->status; // SUCCESS
echo $response->getData()->message; // Transaction some-transac-id has been canceled.
echo $response->getData()->reference; // Random number reference
ApiResponse<object> response = api.CancelTransaction(userHandle, privateKey, transactionId);

// Success Object Response
Console.WriteLine(response.StatusCode); // 200
var parsedResponse = (BaseResponse)response.Data;
Console.WriteLine(parsedResponse.Status); // SUCCESS
Console.WriteLine(parsedResponse.Success); // true
Console.WriteLine(parsedResponse.Message); // Transaction has been canceled
Console.WriteLine(parsedResponse.Reference); // some-uuid-code

👍

/cancel_transation - The Unhappy Path

In sandbox only: you can pass the below transaction_ids to prompt error responses as shown.

transaction_idStatus CodeSuccess AttributeMessage
aaaaaaaa-bbbb-cccc-8de5-a3be64670b71403falseWallet associated with transaction may be frozen.
bbbbbbbb-cccc-dddd-99ce-c45944174e0c403falseTransaction type does not support cancellation. Currently only "issue" transactions may be canceled.
cccccccc-dddd-eeee-a989-76560f827b42403falseTransaction already submitted to ACH network, no cancellation possible from this point.
dddddddd-eeee-ffff-9f23-097bb9bf748d404falseTransaction not found or is currently being processed.

Responses

Status Codesuccess AttributeDescription
200trueTransaction canceled
400falseBad request format - check validation_details for more information.
400falseInsufficient wallet balance.
403falseauthsignature or usersignature header was absent or incorrect.
403falseWallet associated with transaction may be frozen.
403falseTransaction type does not support cancellation. Currently only "issue" transactions may be canceled.
403falseTransaction already submitted to ACH network, no cancelation possible from this point.
403falseThe requested transaction "transaction uuid" was found but was of type "transaction type", and should be reversed, not canceled.
404falseTransaction not found or is currently being processed.