Developer Guide Menu

Electronic Check Processing

To request an Electronic check payment, use the CyberSourceREST API Reference.

Handling Customer Account Information

Merchant-Provided Data
Service:
  • Payment
Processors:
  • Chase Paymentech Solutions
  • CyberSource ACH Service
  • RBS WorldPay Atlanta
  • TeleCheck
Merchant-provided data handling requires you to collect the customer’s account information and provide it in your service request. The required fields are:
  • paymentInformation.bank.account.number
  • paymentInformation.bank.account.type
  • paymentInformation.bank.routingNumber
POST https://<url_prefix>/pts/v2/payments
Request payload
{ "clientReferenceInformation": { "code": "TC50171_3" }, "processingInformation": { "commerceIndicator": "internet" }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "postalCode": "94105", "locality": "san francisco", "administrativeArea": "CA", "country": "US", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100", "currency": "USD" } },
"paymentInformation": { "bank": { "account": { "number": "4100", "type": "C" }, "routingNumber": "071923284"
} } }
You must modify your web site to collect the account information. Retain the account information for future transactions, such as credits.
Customers might not know how to use their printed checks to find the bank routing number and the bank account number. Consider using a graphic like this on your web site:

Figure:

Check Showing Routing Number and Account Number
The following events occur when you request a payment:
  1. Your customer places an order.
  2. You request an electronic check payment (
    /pts/v2/payments
    ).
  3. In your request, you provide the customer’s account information.
  4. CyberSource sends the customer’s account information and other information about the transaction to the check processor.
  5. The payment processor validates the information and screens for fraud.
    The processor does not contact the customer’s bank to verify the existence of the customer’s account; it only makes sure that the information provided by the customer is reasonable and that the account is not a known source of fraud.
    Depending on which processor you use, if there are problems with the account that prevent the transaction from being completed, the processor might charge you a returned check fee.
  6. The payment processor sends a response to CyberSource indicating whether or not the payment will be processed.
  7. CyberSource sends a response to you.
  8. You display an appropriate message to your customer.
  9. The processor sends the request for clearing.
Notifications of Change (NOCs)
Services:
  • Credit
  • Payment
Processors:
  • CyberSource ACH Service
  • RBS WorldPay Atlanta
A Notification of Change (NOC) is a notice from a customer’s bank indicating that an electronic check transaction included incorrect customer or payment information. The customer’s bank:
  1. Corrects the information.
  2. Posts the transaction to the customer’s bank account.
  3. Notifies you that payment information needs to be updated.
Each NOC includes a code that specifies what needs to be changed. You are responsible for taking the appropriate action when you receive a NOC.
You must correct all relevant records before submitting additional electronic check transactions for the customer. If you are using Payment Tokenization or Recurring Billing, you must update the information in your subscriptions or customer profiles.
To get information about the NOCs for your transactions:
  1. Create a PGP key pair as described in .
  2. Log in to the Business Center and under Reports, view the NOC Report.
You can also talk to your bank about getting a report that includes NOCs. NOC codes are described in "NOC Codes."

Optional Features for Payments

For information about optional features such as subscriptions and deferred payments, see "Optional Features."

Verification and Validation

Even if an account passes validation and verification tests, the transaction can be rejected at the time of settlement. The bank from which the check is drawn does not participate in the verification or validation process. Therefore, an account can pass the verification and validation tests, and the transaction can still be rejected for insufficient funds or an invalid account number.
The following table indicates the types of verification and validation supported for each processor.

Table:

Types of Verification and Validation
Payment Processor
Validation
ACH Verification
Guarantees
Paymentech Verification
Chase Paymentech Solutions
Yes
No
No
Yes
CyberSource ACH Service
No
Yes
No
No
TeleCheck
Yes
No
Yes
No
RBS
No
Yes
No
No
Validation
Service:
  • Payment
Processors:
  • Chase Paymentech Solutions
  • TeleCheck

NOTE

For the CyberSource ACH Service, validation is included in the ACH verification functionality, which happens automatically when you call the payment or credit services.
Chase Paymentech Solutions and TeleCheck

NOTE

For the TeleCheck service, contact CyberSource Customer Support for information about validation.
Validation consists of format tests, bank routing number tests, and a comparison with the check processing partner’s internal negative file. Set the
processingInformation.bankTransferOptions.fraudScreeningLevel
 field to 
1
 to request validation with your payment request.
POST https://<url_prefix>/pts/v2/payments
Request Payload
{ "clientReferenceInformation": { "code": "TC50171_3" }, "processingInformation": { "commerceIndicator": "internet", "processingInformation":{ "bankTransferOptions": { "fraud":{ "screeningLevel":"1" } } } }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "postalCode": "94105", "locality": "san francisco", "administrativeArea": "CA", "country": "US", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100", "currency": "USD" } }, "paymentInformation": { "bank": { "account": { "number": "4100", "type": "C" }, "routingNumber": "071923284" } } }
ACH Verification
Services:
  • Credit
  • Payment
Processors:
  • CyberSource ACH Service
  • RBS WorldPay Atlanta
ACH verification is performed automatically for all payment and credit requests for the CyberSource ACH Service and RBS WorldPay Atlanta. ACH verification:
  1. Validates the format and structure of the customer’s bank account number. If the account number needs to be corrected, and if a corrected account number is available, CyberSource returns the corrected account number to you in one of these fields:
    • paymentInformation.bank.account.correctedAccountNumber
    • paymentInformation.bank.account.correctedAccountNumber
  2. Verifies that the customer’s routing number is a valid routing number and valid for electronic transactions. If the routing number needs to be corrected, and if a corrected routing number is available, CyberSource returns the corrected routing number to you in one of these fields:
    • paymentInformation.bank.correctedRoutingNumber
    • paymentInformation.bank.correctedRoutingNumber

    NOTE

    If a corrected account number or corrected routing number is returned to you, you can use the value to update the information in your system. You do not need to update the information for the current transaction because CyberSource updates the information before sending the transaction request to your bank.
  3. Returns verification codes to you whether or not the account number or routing number was corrected. These verification codes indicate the results of the ACH verification. One of these verification codes is a mapped value and is returned in one of these fields:
    • processorInformation.ACHVerification.resultCode
    • processorInformation.ACHVerification.resultCode
    The other verification code is a raw value and is returned in one of these fields:
    • processorInformation.ACHVerification.resultCodeRaw
    • processorInformation.ACHVerification.resultCodeRaw
Guarantees
Service:
  • Payment
Processor:
  • TeleCheck

NOTE

Contact TeleCheck for information about check guarantees.
Paymentech Verification
Service:
  • Payment
Processor:
  • Chase Paymentech Solutions
Paymentech verification compares the transaction information with an external negative file to identify accounts that have a history of bad checks or that were closed for cause. Paymentech verification is available only for transactions in U.S. dollars. Set the
processingInformation.bankTransferOptions.fraudScreeningLevel
 field to 
2
 to request Paymentech verification with your payment request.
POST https://<url_prefix>/pts/v2/payments/
Request Payload
{ "clientReferenceInformation": { "code": "TC50171_3" }, "processingInformation": { "commerceIndicator": "internet", "processingInformation":{ "bankTransferOptions": { "fraud":{ "screeningLevel":"2" } } } }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "postalCode": "94105", "locality": "san francisco", "administrativeArea": "CA", "country": "US", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100", "currency": "USD" } }, "paymentInformation": { "bank": { "account": { "number": "4100", "type": "C" }, "routingNumber": "071923284" } } }

Requesting a Credit

To request an electronic check payment, use the CyberSource REST API Reference (
/pts/v2/credits
) for standalone credits and (
/pts/v2/payments/{id}/refunds
) for follow-on credits.

Standalone Credits and Follow-On Credits

There are two kinds of credits:
  • Standalone (
    /pts/v2/credits
    )—all processors except TeleCheck support this feature. You need to include all customer billing and account information because CyberSource does not retrieve anything from the database.
  • Follow-on (
    /pts/v2/payments/{id}/refunds
    )—all processors support this feature. Send the credit request with the resource ID from the payment response. CyberSource uses this value to retrieve all customer billing and account information that you sent with the payment so that you do not have to send it again with the credit.

NOTE

CyberSource stores the payment information for 60 days, so you must process follow-on credits within 60 days of the payment request. If the 60 days have passed or if you are not sure whether 60 days have passed, use a standalone credit and provide all customer billing and account information.

Deciding Which Kind of Credit to Request

  • All processors except TeleCheck: if you are sending the credit request within 60 days of the payment request, send a follow-on credit so that you are not required to provide all customer information. If you are sending the credit request more than 60 days after the payment request, send a standalone credit.
  • TeleCheck: you must send the credit request within 60 days of the payment request. The credit request must be a follow-on credit, which means you do not need to provide all customer information. CyberSource retrieves all required information from the database, including the identifier that the processor uses to link the credit to the payment. By linking the credit to the payment, the processor can prohibit a credit amount that exceeds the payment amount.
Standalone Credits
A standalone credit does not link the credit to a previous payment request. Do not send the 
id
 field in the credit request; the request must include the fields for the customer’s billing and account information in the request (
/pts/v2/credits
).
POST https://<url_prefix>/pts/v2/credits
Request Payload
{ "clientReferenceInformation": { "code": "TC50171_3" }, "processingInformation": { "commerceIndicator": "internet" }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "postalCode": "94105", "locality": "san francisco", "administrativeArea": "CA", "country": "US", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100", "currency": "USD" } }, "paymentInformation": { "bank": { "account": { "number": "4100", "type": "C" }, "routingNumber": "071923284" } } }
Follow-On Credits
A follow-on credit uses the resource ID from a previous request (
/pts/v2/payments
) to link the credit to the payment. Send the resource ID value in the 
id
 field. CyberSource uses this value to look up the customer’s billing and account information from the original payment; you are not required to include these fields in the request (
/pts/v2/payments/{id}/refunds
).
POST https://<url_prefix>/pts/v2/payments/{id}/refunds
Request Payload
{ "clientReferenceInformation": { "code": "TC50171_3" }, "processingInformation": { "commerceIndicator": "internet" }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "postalCode": "94105", "locality": "san francisco", "administrativeArea": "CA", "country": "US", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100", "currency": "USD" } }, "paymentInformation": { "bank": { "account": { "number": "4100", "type": "C" }, "routingNumber": "071923284" } } }

NOTE

A follow-on credit must be for a payment request that included a payment in which the 
processingInformation.bankTransferOptions.paymentCategoryCode
 field is set to
0
 or 
2
. A follow-on credit cannot be for a payment request in which the 
processingInformation.bankTransferOptions.paymentCategoryCode
 field is set to
1
.

NOTE

If you combine a request for a follow-on credit with a request for another service, you must provide the customer’s billing and account information.

Optional Features for Credits

For information about optional features such as merchant descriptors and multiple partial credits, see "Optional Features."

Voids

A void cancels an electronic check payment or credit request that you have submitted to CyberSource. A transaction can be voided only if CyberSource has not already submitted the payment or credit information to your processor. CyberSource usually submits transaction information to your processor each day, so the period for successfully performing a void is relatively short. CyberSource declines your void request if the payment or credit information was already sent to the processor. You cannot undo a void, and you cannot perform a follow-on credit for a payment that has been voided.

Requesting a Void

To request a void for an electronic check payment or credit, use the REST API resource (
/pts/v2/payments/{id}/voids
/pts/v2/credits/{id}/voids
, or 
/pts/v2/payments/{id}/refunds
).
A void is a follow-on transaction that uses the resource ID returned from a previous request (
/pts/v2/payments
/pts/v2/credits
, or 
/pts/v2/payments/{id}/refunds
) to link the void to the payment or credit. Send the resource ID value in 
/pts/v2/payments/{id}/voids
/pts/v2/credits/{id}/voids
, or 
/pts/v2/payments/{id}/refunds
. CyberSource uses this value to look up the customer’s billing and account information from the original payment or credit, which means that you are not required to include these fields in the above void request.
POST https://<url_prefix>/pts/v2/payments/{id}/voids
Request Payload
{ "clientReferenceInformation": { "code": "test_void" } }
POST https://<url_prefix>/pts/v2/credits/{id}/voids
Request Payload
{ "clientReferenceInformation": { "code": "test_void" } }
POST https://<url_prefix>/pts/v2/refunds/{id}/voids
Request Payload
{ "clientReferenceInformation": { "code": "test_void" } }
Top