Web Service: CreateCheckEx

Ryan Ackley -


Create a new transaction in the system with custom metadata fields. This service can be used to create a check with or without images.  This service is almost identical to the CreateCheck service with the difference being the addition of custom fields. 


The user must have the Gateway.E-Check role (for transactions without images) or the Gateway.Check21 role (for transactions with images that are sent C21 as the EntryClass) and the ClientID must be in the Client Tree for the authenticated user.


SOAP Service


<CreateCheckEx xmlns="https://gateway.acheck21.com/GlobalGateway/">
    <ClientTag>Conditional - string</ClientTag>
    <AccountType>Checking or Savings</AccountType>
    <FrontImage>Base64-encoded TIFF G4 image @200bpi</FrontImage>
    <RearImage>Base64-encoded TIFF G4 image @200bpi</RearImage>
    <MICR>Optional – string</MICR>
    <PostingDate>Optional – string</PostingDate>
        <Addendum>Optional - string</Addendum>
</ExtraFields> </CreateCheckEx>



<CreateCheckResponse xmlns="https://gateway.acheck21.com/GlobalGateway/">
<CreateCheckResult>      <Code>int</Code>     <Message>string</Message>      <CheckID>integer</CheckID> </CreateCheckResult>


REST Service

URL https://gateway.acheck21.com/GlobalGateway/REST/check
Form Contents The form must contain elements corresponding to the ClientID, ClientTag, IndividualName, CheckNumber, TransitNumber, DDANumber, AccountType, CheckAmount, and EntryClass elements in the XML, unless sending a raw MICR line, in which case the MICR field must be present in lieu of the components. These form elements must have the same names as in the XML. If sending a BOC, ARC, or Check21 transaction, the images must either be in Base64-encoded strings with the appropriate names in the form, or as attachments with the correct name in a multi-part form. If sending a posting date or addenda, these elements will be represented in appropriately-named form elements. Transactions with images must not have ClientTag set as this field is set by the Global Gateway for specialized handling.
Response <uri>uri-to-new-check</uri>


Possible values for <Code>

Code HTTP Status Code Description
 0 204 No error
10000 401 Not authorized
10003 403 Base64 string not valid
10005 400 Parameter error
10006 401 Client not authorized
10011 403 Duplicate item
10012 403 Transaction exceeds client transaction limit
10013 403 Check amount causes daily total to exceed daily limit
10014 403 Check amount causes monthly total to exceed monthly limit
10015 403 RDFI not qualified to participate
10016 403 Corporate customer advises not authorized
10017 403 Check not previously authorized
10019 400 Error in addenda sent
10020 403 Addenda not supported for entry class
10022 403 Aux On-Us detected in MICR line for ACH item (ineligible)


The ClientTag and IndividualName fields are optional, the rest of the fields must be provided. No checking is done to verify that the TransitNumber or DDANumber fields are legal values, only that the TransitNumber is the correct length (9 characters) and internally consistent (that the check digit is correct). The DDA number is limited to 15 characters, the check number to 15 characters.

If the AccountType is not provided, the system assumes Checking.

The CheckAmount field must be numeric, have no more than 2 digits after the decimal place, and no dollar sign or internal commas and not be equal to $0.00. The ClientTag, if provided, can have any format needed by the caller. The service does not require or check that the value be unique. ClientTag must not be used in the event images are to be sent.

To send a credit, the CheckAmount should be negative. This triggers an ACH transaction code of either 22 or 32.

If sending a raw MICR line, the value will be accepted only if it conforms to an acceptable format, and if the transit number meets the criteria above for the TransitNumber field. Note that sending a raw MICR precludes sending values for TransitNumber, DDANumber, and CheckNumber. If both are sent, error code 10005 will be returned.

The 10006 return code indicates that the client is not authorized to submit transactions of the type indicated by the EntryClassCd.

The C21 EntryClassCd can only be used for Check21 transactions. This will later be converted to a 937 type for later reporting access.

The PostingDate is optional. If not provided, the check will be posted the next time the client’s e-checks are batched. If not empty, it cannot specify a date in the past. The format of the PostingDate is mm/dd/yyyy.

At this time, addenda records are only supported for PPD transactions. There can only be a single addendum, and it can contain no more than 80 characters. ACHeck21 does no validation of the contents of the addendum, that is the responsibility of the sender. Of course, the addendum is optional even for PPD transactions.

The CheckID (or URI) returned is a unique identifier for the new check. It can be used in successive calls to retrieve information about the document. The identifier will remain valid for the lifetime of the document within the ACHeck21 system.


Check 21 Notes
Images will be decoded and their format verified. No IQA checking will be done, that is the responsibility of the sender. Both front and rear images must be sent. Errors in the image files will result in error code 10003.

The AccountType field is not required for Check21 transactions. If sent, it will be changed to Checking automatically.

The EntryClassCd must be C21 for Check21 transactions. This will be reassigned to 937 later automatically. C21 is used as various financial institutions may use a format other than X9.37 but is still considered a Check21 based transaction.

Have more questions? Submit a request