ACH Check Transactions

Process ACH Electronic check transactions through our REST API.

Processing an ACH Check Example

This tutorial will outline how to process an ACH check transaction through our REST Api. To keep things simple, we use the same actions as credit cards ( CHARGE and REFUND ). In the ACH world, a charge is called a debit and a refund is called a credit.

Production Request

curl -X POST -u "login:password" -H "Accept: application/json" -H "X-PJ-Application-Key: YOUR_PRODUCTION_APP_KEY" \
    -d "achRoutingNumber=104000016" \
    -d "achAccountNumber=12345678" \
    -d "achAccountType=CHECKING" \
    -d "achType=PPD" \
    -d "amountBase=1.00" \
    "https://api.payjunction.com/transactions"

Response

{
  "transactionId" : 22979,
  "terminalId" : 10003,
  "action" : "REFUND",
  "achType" : "PPD",
  "amountBase" : "1.00",
  "amountTotal" : "1.00",
  "status" : "CAPTURE",
  "created" : "2012-03-03T05:15:00Z",
  "lastModified" : "2012-03-03T05:15:00Z",
  "response" : {
     "approved" : true,
    "code" : "00",
    "message" : "Approved"
  },
  "settlement" : {
    "settled" : false
  },
  "vault" : {
    "vaultId" : 14831,
    "customerId" : 12085,
    "type" : "ACH",
    "accountType" : "CHECKING",
    "lastFour" : "5678",
    "achRoutingNumber" : "104000016",
    "created" : "2012-02-28T03:15:45Z",
    "lastModified" : "2012-02-28T03:15:45Z"
  }
}

This is the most basic example of charging a checking account. Most developers only want to check if the check was approved or declined. See the highlighted “approved” boolean in the JSON response. Simply check this and continue coding your application.

ACH Transactions Don’t Check Available Balance

Unlike credit and debit transactions, ACH transactions don’t check the available balance at the time of the transaction. Just like paper checks, ACH transactions will reject a few days later for issues like insufficient funds. Rejected transactions can be managed in the Virtual Terminal.

ach-reject.png

How to Handle ACH Rejects

If you are going to code your own reject management then you will need to take into consideration the reject code for the transaction. There are three possible actions that can be taken:

  • Recharge the account using the same route & account number. This should only be done on R01, R09 and R18.
  • Update the route and/or account and recharge the account. This should only be done on R02, R03, R04, R05, R11, R12, R13, R17, R20, R28, R30, R31, R32, R34, R35, R36, R39, R51
  • Mark complete. No action taken.

Recharging the transaction will automatically mark the reject complete and remove it from the list.

If you have a response code that is not in the list above then the account should not be recharged. You can mark the reject complete (this will not recharge the account) to remove it from the list.

Recharging a Rejected Transaction

This will recharge the previous route, account and amount from the rejected transaction. You may optionally specify a reject fee to bill the customer. In this example, we include a reject fee of $15.00 which will be added to the rejected transaction amount.

Production Request

curl -X POST -u "login:password" -H "Accept: application/json" -H "X-PJ-Application-Key: YOUR_PRODUCTION_APP_KEY" \
    -d "action=CHARGE" \
    -d "transactionId=23383" \
    -d "amountReject=15.00" \
    "https://api.payjunction.com/transactions"

Response

{
  "transactionId" : 23395,
  "terminalId" : 10003,
  "action" : "CHARGE",
  "achType" : "CCD",
  "amountBase" : "4.00",
  "amountReject" : "15.00",
  "amountTotal" : "19.00",
  "status" : "CAPTURE",
  "created" : "2012-03-03T05:59:29Z",
  "lastModified" : "2012-03-03T05:59:29Z",
  "response" : {
    "approved" : true,
    "code" : "00",
    "message" : "Approved"
  },
  "settlement" : {
    "settled" : false
  },
  "vault" : {
    "vaultId" : 15131,
    "customerId" : 12309,
    "type" : "ACH",
    "accountType" : "CHECKING",
    "lastFour" : "9012",
    "achRoutingNumber" : "121000358",
    "created" : "2012-03-03T05:42:19Z",
    "lastModified" : "2012-03-03T05:42:19Z"
  },
  "billing" : {
    "firstName" : "Irene",
    "lastName" : "Harris",
    "email" : "in.felis@Suspendissenon.com",
    "phone" : "(943) 899-6594",
    "address" : {
      "address" : "Ap #558-3225 Vulputate Ave",
      "city" : "Lower Burrell",
      "state" : "WI",
      "zip" : "02286"
    }
  }

Updating & Recharging a Rejected Transaction

For specific reject codes you will want to update the account and recharge. For example, a R04 indicates that there was an invalid account number. In this case you want to update the account then recharge. You may optionally specify a reject fee to bill the customer. In this example, we added a reject fee of $15.00 which will be added to the rejected transaction amount.

Production Request

curl -X POST -u "login:password" -H "Accept: application/json" -H "X-PJ-Application-Key: YOUR_PRODUCTION_APP_KEY" \
    -d "action=CHARGE" \
    -d "transactionId=23393" \
    -d "achRoutingNumber=104000016" \
    -d "achAccountNumber=11114444" \
    -d "achAccountType=CHECKING" \
    -d "achType=PPD" \
    -d "amountReject=15.00" \
    "https://api.payjunction.com/transactions"

Response

{
  "transactionId" : 23397,
  "terminalId" : 10003,
  "action" : "CHARGE",
  "achType" : "PPD",
  "amountBase" : "62.00",
  "amountReject" : "15.00",
  "amountTotal" : "77.00",
  "status" : "CAPTURE",
  "created" : "2012-03-03T06:08:11Z",
  "lastModified" : "2012-03-03T06:08:11Z",
  "response" : {
    "approved" : true,
    "code" : "00",
    "message" : "Approved"
  },
  "settlement" : {
    "settled" : false
  },
  "vault" : {
    "vaultId" : 15201,
    "customerId" : 12125,
    "type" : "ACH",
    "accountType" : "CHECKING",
    "lastFour" : "4444",
    "achRoutingNumber" : "104000016",
    "created" : "2012-03-03T06:08:11Z",
    "lastModified" : "2012-03-03T06:08:11Z"
  },
  "billing" : {
    "firstName" : "Lyle",
    "lastName" : "Moss",
    "email" : "a.aliquet.vel@ac.org",
    "phone" : "(561) 834-5850",
    "address" : {
      "address" : "P.O. Box 532 368 Mollis Street",
      "city" : "Port Orford",
      "state" : "NC",
      "zip" : "62278"
    }
  }
}

Note that we did not send the achRoutingNumber, so the routing number for the referenced transactionId was used.

Marking a Rejected Transaction Complete

In the case where no more action should be taken, then you may want to remove it from your reject list after you have dealt with it. For example, if a customer makes a payment with a credit card instead. In this case, marking the transaction complete will not recharge the transaction; it will only remove it from the reject list.

Production Request

curl -X PUT -u "login:password" -H "Accept: application/json" -H "X-PJ-Application-Key: YOUR_PRODUCTION_APP_KEY" \
    -d "complete=true" \
    "https://api.payjunction.com/transactions/23391"

Response

{
  "transactionId" : 23391,
  "terminalId" : 10003,
  "action" : "CHARGE",
  "achType" : "CCD",
  "amountBase" : "86.00",
  "amountTotal" : "86.00",
  "status" : "REJECT",
  "created" : "2012-03-10T12:30:00Z",
  "lastModified" : "2012-03-03T06:16:07Z",
  "response" : {
    "approved" : false,
    "code" : "R05",
    "message" : "UNAUTH DR TO CONSUMER ACCT USING IMPROPER SEC"
  },
  "reject" : {
    "rejectId" : 23369,
     "complete" : true
  },
  "settlement" : {
    "settled" : true,
    "settlementId" : 10007
  },
  "vault" : {
    "vaultId" : 15189,
    "customerId" : 12241,
    "type" : "ACH",
    "accountType" : "SAVINGS",
    "lastFour" : "2103",
    "achRoutingNumber" : "121000248",
    "created" : "2012-03-03T05:42:29Z",
    "lastModified" : "2012-03-03T05:42:29Z"
  },
  "billing" : {
    "firstName" : "Daquan",
    "lastName" : "Melton",
    "email" : "dapibus@egetlacusMauris.edu",
    "phone" : "(384) 716-1302",
    "address" : {
      "address" : "490-4280 Aenean Avenue",
      "city" : "Muskegon",
      "state" : "Hawaii",
      "zip" : "59556"
    }
  }
}
The transaction info will echo back indicating the update was successful.

Related Articles & Resources

Transaction REST API specification

ACH Definitions & Codes

Developer sandbox and test account