Overview
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.
Security
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
Request
<CreateCheckEx xmlns="https://gateway.acheck21.com/GlobalGateway/"> <Username>string</Username> <Password>string</Password> <ClientID>string</ClientID> <ClientTag>Conditional - string</ClientTag> <IndividualName>string</IndividualName> <CheckNumber>string</CheckNumber> <TransitNumber>string</TransitNumber> <DDANumber>string</DDANumber> <AccountType>Checking or Savings</AccountType> <CheckAmount>string</CheckAmount> <EntryClass>TEL, PPD, ARC, RCK, CCD, WEB, BOC, POP, C21</EntryClass> <FrontImage>Base64-encoded TIFF G4 image @200bpi</FrontImage> <RearImage>Base64-encoded TIFF G4 image @200bpi</RearImage> <MICR>Optional – string</MICR> <PostingDate>Optional – string</PostingDate> <Addenda> <Addendum>Optional - string</Addendum> </Addenda>
<ExtraFields>
<ExtraCheckField>
<FieldName>string</FieldName>
<FieldValue>string</FieldValue>
</ExtraCheckField>
<ExtraCheckField>
<FieldName>string</FieldName>
<FieldValue>string</FieldValue>
</ExtraCheckField>
</ExtraFields> </CreateCheckEx>
Response
<CreateCheckResponse xmlns="https://gateway.acheck21.com/GlobalGateway/">
<CreateCheckResult> <Code>int</Code> <Message>string</Message> <CheckID>integer</CheckID> </CreateCheckResult>
</CreateCheckResponse>
REST Service
| URL | https://gateway.acheck21.com/GlobalGateway/REST/check |
| VERB | POST |
| 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) |
Notes
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.
Comments