ACH Transactions

POST an ACH Transaction

Previous Step: Create User, OAuth User, and Link with Bank Logins or Account/Routing for all parties in the transaction

API ENDPOINT

https://uat-api.synapsefi.com/v3.1/users/:user_id/nodes/:node_id/trans

PATH PARAMETER

user_id :
required
string

ID of sender (user)

node_id :
required
string

ID of sending node

BODY PARAMETER

to.type :
required
string

Receiving node type

to.id :
required
string

Receiving node ID

amount.amount :
required
double

Amount user wishes to send

amount.currency :
required
string

Currency of the transaction amount

extra.ip :
required
string

IP address of the user device while creating transaction

extra.asset :
string

Assign this value only in case of making a transaction to or from CRYPTO-US. Acceptable values are BTC and ETH

extra.same_day :
boolean false

Set this to true if you wish to settle the ACH on same day. Please note this would only work, if same day ACH has been enabled for your platform

extra.settlement_delay :
integer 0

Used to dynamically delay transaction settlements. The value will be added to the current settlement time.

extra.supp_id :
string

ID supplied to the transaction. Allows clients to track transactions based on specific events.

extra.group_id :
string

Group ID supplied to the transaction. Allows clients to track transactions based on specific events.

extra.note :
string

Memo tagged with the transaction. Commonly used for reference IDs. This will show up in the transaction addendum of a user's bank statement, though ultimately it is up to the user's bank to determine whether they will display it.

extra.process_on :
integer 0

When the transaction should be processed. The value is the delta value. Which means when 1 is supplied it means that the transaction will be processed tomorrow.

extra.other.attachments :
array of strings

Array of padded base64 of attachments

fees[fee ] :
double

Fee associated with the transaction

fees[note ] :
string

Reason for the fee

fees[to].id :
string

Node ID where the fee would be credited when the transaction settled. Fee node has to be DEPOSIT-US type always

EXAMPLE REQUEST

POST /v3.1/users/594e6da41acea2002e666987/nodes/594e6e6c12e17a002f2e39e4/trans HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-USER-IP: 127.0.0.1
X-SP-USER: oauth_fyBaT5kswdlme0xQI6gSCPYKDG1Zrv8Ftj9NboJc|e83cf6ddcf778e37bfe3d48fc78a6502062fc
Content-Type: application/json

{
  "to": {
    "type": "ACH-US",
    "id": "594e6e6c12e17a002f2e39e4"
  },
  "amount": {
    "amount": 20.1,
    "currency": "USD"
  },
  "extra": {
    "ip": "192.168.0.1"
  }
}
node_id = '594e606212e17a002f2e3251'
body = {
  "to": {
    "type": "ACH-US",
    "id": "594e6e6c12e17a002f2e39e4"
  },
  "amount": {
    "amount": 20.1,
    "currency": "USD"
  },
  "extra": {
    "ip": "192.168.0.1"
  }
}

user.create_trans(node_id, body)
const fromNodeID = '594e606212e17a002f2e3251';
const body = {
  "to": {
    "type": "ACH-US",
    "id": "594e6e6c12e17a002f2e39e4"
  },
  "amount": {
    "amount": 20.1,
    "currency": "USD"
  },
  "extra": {
    "ip": "192.168.0.1"
  }
};

user.createTransaction(fromNodeID, body);
from_node_id = “594e6e6c12e17a002f2e39e4”
body = {
  "to": {
    "type": "ACH-US",
    "id": "594e6e6c12e17a002f2e39e6"
  },
  "amount": {
    "amount": 20.1,
    "currency": "USD"
  },
  "extra": {
    "ip": "192.168.0.1"
  }
}

user.create_transaction(node_id: from_node_id ,payload: body)
$to = (object)[
   "type" => "ACH-US",
   "id" => 'to_node_id'
];
$amount = (object)[
   "amount" => 22.1,
   "currency" => "USD"
];
$extra = (object)[
   "ip" => "IP_address_of_user_device_while_creating_transaction"
];
$body = (object)[
   "to" => $to,
   "amount" => $amount,
   "extra" => $extra
];
$nodeid = '5c3d416f7b08ab0066ee8cae';
$trans = $user->create_trans($nodeid, $body);
nodeID := “594e6e6c12e17a002f2e39e4”
body := `{
  "to": {
    "type": "ACH-US",
    "id": "594e6e6c12e17a002f2e39e4"
  },
  "amount": {
    "amount": 20.1,
    "currency": "USD"
  },
  "extra": {
    "ip": "192.168.0.1"
  }
}`

data, err := user.CreateTransaction(nodeID, body)

EXAMPLE RESPONSE

{
  "_id": "5b57d2b4b75379005e3d60cf",
  "_links": {
    "self": {
      "href": "https://uat-api.synapsefi.com/v3.1/users/5b57d065c9f52d0059a50e63/nodes/5b57d07ef605a000497f0409/trans/5b57d2b4b75379005e3d60cf"
    }
  },
  "_v": 2,
  "amount": {
    "amount": 20.1,
    "currency": "USD"
  },
  "client": {
    "id": "589a9ffc86c2736412ce7ea4",
    "name": "TEST TEST MEESH"
  },
  "extra": {
    "created_on": 1532482228415,
    "ip": "192.168.0.1",
    "latlon": "0,0",
    "note": "Test transaction",
    "process_on": 1532482228415,
    "same_day": false,
    "supp_id": "1122444"
  },
  "fees": [
    {
      "fee": 0.0,
      "note": "Facilitator Fee",
      "to": {
        "id": "None"
      }
    }
  ],
  "from": {
    "id": "5b57d07ef605a000497f0409",
    "meta": {},
    "nickname": "SynapsePay Test Checking Account - 8901",
    "type": "ACH-US",
    "user": {
      "_id": "5b57d065c9f52d0059a50e63",
      "legal_names": []
    }
  },
  "recent_status": {
    "date": 1532482228415,
    "note": "Transaction Created.",
    "status": "CREATED",
    "status_id": "1"
  },
  "timeline": [
    {
      "date": 1532482228415,
      "note": "Transaction Created.",
      "status": "CREATED",
      "status_id": "1"
    }
  ],
  "to": {
    "id": "5b57d07ef605a000497f0409",
    "meta": {},
    "nickname": "",
    "type": "ACH-US",
    "user": {
      "_id": "",
      "legal_names": []
    }
  }
}

ACH Cutoff Times

Payments are submitted for processing every business day (Monday - Friday). Payments are not submitted on weekends or bank holidays.

Transaction Type
Cutoff Time
Settlement Time

Same Day ACH

9AM PT

4PM PT (approximately)

Next Day ACH

4PM PT

11AM PT (approximately)

Example Timeline

Here is an example of a returned ACH debit. Not all transactions will follow this exact timeline, so please do not build your logic off these times. Instead, monitor transaction status and account balance.

DESCRIPTION
TIME
TRANSACTION STATUS
STATUS_ID

User creates a transaction

Day 1, 10AM PT

CREATED

1

Transaction is submitted to our partner bank ("ODFI") at the appropriate cutoff time, assuming the transaction was not queued or canceled.

Day 1, 4:00PM PT

PROCESSING-DEBIT

2

User's bank ("RDFI") picks up the ACH request.

Day 2, 11:00AM PT

PROCESSING-CREDIT

3

We mark the transaction as settled

Day 2, 11:05AM PT

SETTLED

4

We receive a return from the user's bank stating that the funds were not actually debited/credited. See ACH Return Codes to understand these timelines.

Day 4, 3:00PM PT

RETURNED

6

Don't see a transaction posted at your bank?

Different banks post transactions at different times, so a user may not see their transaction marked as settled at the exact time that we mark a transaction as settled.

Transaction Status

The following are different types of transaction statuses for an ACH transaction.

STATUS
STATUS_ID
Comment

QUEUED-BY-SYNAPSE

-1

Transaction queued by Synapse

QUEUED-BY-RECEIVER

0

Transaction queued by Client

CREATED

1

Transaction Created

PROCESSING-DEBIT

2

Processing Debit

PROCESSING-CREDIT

3

Processing Credit

SETTLED

4

Transaction Settled

CANCELED

5

Transaction Canceled

RETURNED

6

Transaction Returned

Queued and Canceled Transactions

Visit our Transaction Codes resource for the full list of reasons a transaction can be queued or canceled.

To cancel a transaction yourself, DELETE transaction. Only transactions with a CREATED or QUEUED status can be canceled. Once a transaction is processing or settled you are unable to cancel it.

Returned Transactions

Transactions may be marked as returned after a transaction has settled. Below are the possible return codes and the corresponding timeframes within which a return may occur.

Code
Description
Timeframe

R01

Insufficient Funds. Available balance is not sufficient to cover the amount of the debit entry.

2 Banking Days (“48 hours”)

R02

Account Closed. Previously active amount has been closed by the customer of RDFI.

2 Banking Days (“48 hours”)

R03

No Account/Unable to Locate Account. Account number does not correspond to the individual identified in the entry, or the account number designated is not an open account.

2 Banking Days (“48 hours”)

R04

Invalid Account Number

2 Banking Days (“48 hours”)

R06

Returned Per ODFI's Request

Not defined, determined by ODFI and RDFI

R07

Authorization Revoked by Customer

60 Calendar Days

R08

Payment Stopped

2 Banking Days (“48 hours”)

R09

Uncollected Funds. Collected funds are not sufficient for payment of the debit entry.

2 Banking Days (“48 hours”)

R10

Customer Advises Not Authorized

60 Calendar Days

R11

Check Safekeeping Entry Return

2 Banking Days (“48 hours”)

R12

Branch Sold To Another DFI

2 Banking Days (“48 hours”)

R13

RDFI Not Qualified to Participate

2 Banking Days (“48 hours”)

R14

Account Holder Deceased

2 Banking Days (“48 hours”)

R16

Account Frozen. Funds in bank account are unavailable due to action by RDFI or legal order

2 Banking Days (“48 hours”)

R17

File Record Edit Criteria

2 Banking Days (“48 hours”)

R20

Non-Transaction Account. Entry destined for non-payment bank account defined by reg. This means the account either does not have ACH enabled, or has maxed out the monthly quota for ACH transactions.

2 Banking Days (“48 hours”)

R21

Invalid Company Identification

2 Banking Days (“48 hours”)

R22

Invalid Individual ID Number

2 Banking Days (“48 hours”)

R23

Credit Refused by Receiver. Receiver returned entry because minimum or exact amount not remitted, bank account is subject to litigation, or payment represents an overpayment, originator is not known to receiver or receiver has not authorized this credit entry to this bank account

2 Banking Days (“48 hours”)

R24

Duplicate Entry

2 Banking Days (“48 hours”)

R29

Corporate Customer Advises Not Authorized

2 Banking Days (“48 hours”)

R31

Permissible Return Entry. RDFI has been notified by the ODFI that it agrees to accept the return entry.

2 Banking Days (“48 hours”)

R33

Return of XCK Entry

60 Calendar Days

R34

Limited participation DFI

2 Banking Days (“48 hours”)

Testing Returns in Sandbox:
While testing, RequestBin is an excellent tool to help you test out web-hooks for these scenarios. Please remember, in practice ACH returns do not occur in real-time.

Amount
Return

222.22

R01 -- Insufficient Funds

333.33

R08 -- Payment Stopped

444.44

R10 -- Customer Advises Not Authorized

555.55

R03 -- No Account/Unable to Locate Account

Subscribe to Webhooks

We recommend that you subscribe to webhooks to stay updated on the status of transactions.

Transaction Fees

By default, we deduct transaction fees from the transaction. To send the recipient 100% of the funds, designate the account you want to debit fees from.

Or take an additional fee for yourself and designate the DEPOSIT-US node you want to send fees to.

Idempotent Requests

POST calls support idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a transaction fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single charge is created.

To perform an idempotent request, attach a unique key to any POST request made to the API via the X-SP-IDEMPOTENCY-KEY: <key> header.

Idempotency keys expire after 24 hours.

ACH Transactions


POST an ACH Transaction

Suggested Edits are limited on API Reference Pages

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