CreditAble API programmer's reference

1.0 Introduction

The submission of the request and the return of the results are separated into two calls so that the user application may submit its request and carry on with other activity if it is necessary to do so. It may then request the return of results. The call for results will wait for the response if it has not yet arrived, so it may also be called immediately after requesting the authorisation.

2.0 API calls

Introduction

All parameters described as "char *" are null-terminated ASCII strings, this applies both to values supplied by the programmer and results returned to him. All parameters should be supplied left justified with no leading spaces.

The programmer must ensure that there is sufficient space available for the maximum size of all returned strings as the API cannot check this and will return the values regardless of the actual size of the strings.

Some versions of the API can also be used to access more than one server during the run ( see section 4 ). References to CA30_handle apply to these versions only and should be ignored by programmers using the standard versions. If you have not been made specifically aware that you are using a version with multiple servers then you are using the single server version.

Please note that for all calls a negative return value indicates an error, but that zero or greater means success.

Not all the result codes specified in the description of the functions will be returned by all versions of the API. Programmers should select those for which specific recovery actions (such as repeating the call) can sensibly be taken. All other negative results should be treated as general failure and appropriate action taken. Results which can only occur when targetting multiple servers are marked with a double asterisk (**).

2.1 Making a link to the CreditAble server gateway

This function establishes initial contact with the local authorisation server. It checks that the service is available and allows the service to perform any initialisations required.
 

Parameter Name	Type	Description
config_name	char *	The name of the client's configuration file

Results

Note:

The previous recommendation was to use the same file as the server or a copy of it.  This is no longer the case and the client's configuration file should always be a separate file and be set up specially for this purpose.

The length of the name of the file must not exceed 40 characters.

2.2 Requesting an authorisation.

This function hands a request for authorisation of a transaction to the server and returns immediately.
 

Parameter Name	Type	Description
card_number	char *	The magnetic track or the keyed card-number
issue_number	char *	The issue number for keyed data
expiry_date	char *	The expiry date for keyed data
amount	char *	The amount of the transaction
message_type	char *	The transaction type
auth_type	char *	The authorisation type
auth_code	char *	The authorisation code
merchant_number	char *	The merchant number or till id
extended_data	char *	An extended data field, defaults to user reference
start_date	char *	The start date for keyed data

Results

Note:

The maximum size of the data which may supplied to the call for each of the parameters is as follows:
 

Data Item	Maximum Size
card-number	19
card_issue	2
card_expiry_date	4
amount	11
message_type	2
auth_type	1
auth_code	9
merchant_number	15
extended_data	20(See Notes)
card_start_date	4

The expiry date and start date should be in the format MMYY.

The amount must be in the smallest or only local currency unit (e.g. pence, lire, pfennigs) with no decimal point. It should be left justified (followed by spaces) or right justified (with leading zeroes).

The message_type must indicate the type of transaction
 

sale	20
refund	61
cheque guarantee	02
cash back	04

The server will adjust the codes as necessary, for example to allow for either keyed or swiped data.

The authorisation type (auth_type) is used for two parallel purposes:

1. To inform the server whether the current request is a "manual authorisation".  That means that it is recording the result of an authorisation code obtained by phone from the bank in order to obtain payment. There may or may not have been a previous, unsuccessful, normal electronic authorisation for this transaction.

2. To inform the server of special types of authorisation, usually to override the default configuration of the server.

The normal value is a space which means that the server's default values for both aspects will be used.  Since the special types of authorisation may also require a voice authorisation there are "Voice authorisation Equivalents" for all of these.

The value 'M' is for a voice authorisation (see 1 above) and like space will allow the server's default for the type of authorisation to be used.

In order to format the request message to the bank, the server needs to know whether the card was swiped or keyed and if keyed whether the card holder was present at the point of sale or not.  The program can deduce whether the card was swiped or not by the format of the card-details presented to it, but needs assistance to decide whether the card-holder was present.  All servers will be set up to default to one or the other.

Till systems will be set up to default to card-holder present, but Mail Order/Telephone Order systems will default to Card-holder Not Present (CNP).  In both cases it can happen that some transactions will occur with the opposite position, so the values 'P' (treat the transaction as Card-holder present even though the server defaults to CNP) and 'K' (treat the transaction as CNP even though the server defaults to CP) may be supplied for these transactions.

The last value 'C' is used to mark "continuous authority" transactions and must be supplied with every transaction of this type.

The values for auth type are summarised in the following table:
 

Value	Voice Auth Equivalent	Type of Authorisation request
Space	'M'	card data swiped or keyed
'P'	'V'	data keyed - customer present
'K'	'X'	data keyed - customer NOT present
'C'	'Y'	data keyed - continuous authority

If an auth_type from the second column is used (voice authorisation), then the field auth_code must contain the authorisation code obtained by the voice call.

The extended_data parameter defaults to a text reference field which is preserved in the CreditAble server audit file, and returned in the retrieve call (see below). The length of this reference user data is limited to 20 characters, but the the data supplied in the parameter may be longer if additional fields are present, see following.

Special types of authorisation

In each case the type of authorisation is specified with a different message type, and additional data is included within the "user reference" field.  Any data in the extended_data parameter after the first comma (if any) will be ignored unless the message type is for cheque guarantee or sale with cash-back.
 

Sale with Cashback.

For Cash Back the user reference should be followed by the amount of cash required with no zeros or spaces or any other punctuation and separated from the user reference by a comma. Example:

SMITH/4711,4500 (SMITH/4711 is the reference, the cashback amount is £45.00)

The amount of cash back, just like the transaction amount in the call, must be in the lowest denomination of the currency ( eg pence for Sterling)  Note that the cash-back amount must be added to the primary transaction amount by the caller of the routine.  The transaction amount must always therefore be greater than the cash-back amount.

The message type must be set to 04.  There is no explicit message type for a cash-back refund, so the normal (61) message type should be used and the total transaction amount, including Cashback refunded.

It is the responsibility of the programmer to ensure that cash-back is only used on card-schemes that support it ( Switch, Solo, Visa Debit - formerly Delta ) and to adhere to the upper limit for the cash-back amount ( usually £50.00 ).  This will be validated by the server as well.
 

Cheque Guarantee processing

For cheque guarantee the parameter string is a list of comma separated variable (csv) items as follows :-
 

user reference	Any characters up to 20. (Must be in quotes if it contains a comma.)
bank sort code	six digit bank sort code from the cheque
account number	up to 10 digits as printed on the cheque
cheque number	six digits as printed on the cheque
type of transaction	Business or Personal single character B or P.
type of enquiry	Guarantee or Appraisal single letter G or A.

example :-

"sale number 1,210",560018,15413999,001213,B,G

The user reference (sale number 1,210) contains a comma so is enclosed in quotes.

The sort code is 560018, the account is 15413999 and the cheque number is 001213. It is a Business cheque and a guarantee is required.

2.3 Retrieving the result

This function retrieves the response to a previously issued request.
 

Parameter Name	Type	Description
card_number	char *	The card number returned for confirmation
amount	char *	The amount is returned for confirmation
resp_code	char *	The response code from the issuer
auth_code	char *	The authorisation code
auth_mess	char *	The message containing the authorisation outcome
phone	char *	The phone number to be rung for a referral
mess_date	char *	The message date
user_ref	char *	The user reference field
mess_num	char *	The message number in the APACS request
terminal_id	char *	The number of the terminal used for the call
wait_time	int	The time to wait for a response in seconds

Results

Notes:

If the wait_time is supplied as zero then control returns immediately to the calling program. If an authorisation response had already been received then it will be supplied, otherwise no data will be inserted into the parameters and the result CA30_NO_DATA returned.

If wait_time is greater than zero, then control will only return immediately if a response is already present. Otherwise the fun-ction will wait for up to the given number of seconds, returning as soon as a result is received or responding with CA30_NO_DATA if the limit is passed without reply from the Server.

A response of CA30_NO_DATA means a future call may return the response. The user should guard against the small but finite chance that this could be after the next request has been sent, leading to the processing in error of a reply to the wrong request.

With the exception of the wait_time all parameters are for the return of the results and must allow for the following maximum data lengths (including string terminator)
 

Data Item	Maximum length
card-number	21
amount	12
resp_code	3
authcode	10
auth_message	81
ref_phone	17
mess_date	5
user_key	21
mess_number	5
terminal_id	9

All fields must be present. On return each field will contain data from the response as a null-terminated string.

Both dates are in YYMM form, the start date will only be returned if the card has one.

The response code categorises the result of the authorisation call.  See messages returned by CreditAble for a full description.

2.4 Closing the link to the Server Gateway

This call will close the link to the server, it should always be called before the link is re-initialised.
 

Parameter Name	Type	Description
None

Results

2.5 Cancelling the Request

This call is no longer available as it is not compatible with remote server operation.

3.0 Remote use of the API

The previous contents of this section are now redundant.
 

4.0 Multi-server remote use of CreditAble.

4.1 The handle

There are two ways of accessing this value.  Which method is used depends on the language used to create the program and the way in which the API is presented. When we later say "set a value into CA30_handle", then either method can be used as appropriate.
 

4.1.1 Using an external

extern int CA30_handle;

This variable can be used both to retrieve the value for the connection and to set it for later calls.
 

4.1.2 Using a function call

Where the API is presented as a Windows DLL and is being used for example from a Visual Basic program, it is not possible to access external variables defined in the DLL.  Instead, these users must use the call
 

int set_CA30_handle(CA30_handle)
 
 

Parameter Name	Type	Description
CA30_handle	Int	The value of the handle for the next call

Results

After a successful call the value returned will be the value supplied in the call.

Note that setting the external or using the call are equivalent, so the call must be used before init_CA30_link, request_CA30_auth and close_CA30_link to set the value in exactly the same circumstances as the external variable would be set. It is not necessary to have a call to retrieve the value, since the two calls which set it (init_CA30_link and retrieve_CA30_auth) also return its value if the function is successful.
 

4.1.3 Use the of handle in single channel configurations

4.2 Establishing multiple connections

Before calling init_CA30_link again CA30_handle must be set to -99 as an indication that the second (or subsequent) call to init_CA30_link when there is already a link open is deliberate.  If this is not done then the error code -65 ( already connected) will be returned. It is permissible to set the handle to -99 on the first call as it will be ignored, this may make programming the link simpler.

A new value will be returned in CA30_handle which must also be stored and used for future calls to the second server. The handle will also be returned as the return value of the call. Note that zero is a valid handle(Valid handles run from 0 to one less than the maximum allowed.  The current maximum number of servers is 8) and that this value will always be returned from the very first call to the function.
 

4.3 Using multiple connections

The processing of the handle in retrieve_CA30_auth is quite different, because of the way that the routine works.  The function always returns the first available response from any of the servers.  The routine informs the caller of the server from which the response was sent by setting the handle into CA30_handle and returning its value as the result of the call to the function.  The setting of the handle on entry to the function is ignored.

Note that the facilities described here require the use of the CreditAble DLL build 2.10 ( build date 17/04/03) or later.
 
 

5.0 Additional facilities for users of the Windows DLL

Note that the call cancel_CA30_request has been withdrawn.

5.1 Additional routines

This function resets the DLL for use by a program. Although the DLL is a single-user system and may only be called by a single instance at a time, it is possible that it will NOT be unloaded between sessions, for example during testing.

It is therefore essential for any program that uses the DLL to call this routine once only in any one session during program initialisation, to ensure that the DLL is properly initialised.
 
 
 

Parameter Name	Type	Description
None

Results

FILE * open_trace_file(char * file_name,int trace_mode)

int close_trace_file(int trace_mode)

By using these routines you can use the same journal file for both your application, and the CreditAble DLL. The trace mode integer determines just what items are traced by the DLL as follows (all values are additive)

0x02 TRACE_COMMS
0x04 TRACE_DATA
0x08 TRACE_MODULES
0x10 TRACE_EVENTS
0x20 TRACE_FILES
0x40 TRACE_CONNECTIONS
0x100 TRACE_TO_SCREEN
0x400 TRACE_WIN

5.2 External variables

5.2.1 External variables supplying information to the DLL

This variable is a pointer to a 3-character USER-ID. This may be set by the calling program when the DLL is being used on a network to connect to a CreditAble server and serves to distinguish this workstation from all others. The user program must establish the user id and set it up for use by the DLL. It will be used to personalise journal files ( which may be in the same directory on a networked drive) and to identify the calling station to the server.

int far _pascal _export CA30_program_mode;

This is a bit-mapped integer which may be used to control the volume of diagnostic output. Setting it to zero will reduce the amount to a minimum, and setting it to 255 will give the maximum output.

FILE * far _pascal _export CA30_jnl_fd;

The calling program may take charge of the diagnostic journal file. If it does so, then it may pass the stream pointer to the DLL for use for output. If this value is not declared and set in the outer program, the the DLL will open its own journal file.

5.2.2 External variables retrieving information from the DLL (not for TCP/ip)

This variable may be used to obtain the Channel Number on which the workstation is connected to the server. It should not ever be changed by the caller of the DLL.

int far _pascal _export CA30_session_no;

This variable may be used to obtain the current session number of the CreditAble server. It should not ever be changed by the caller of the DLL.
 
 

6 Using the CreditAble client DLL from Visual Basic & Access

Also all the function names will need to be in capitals thoughout eg REQUEST_CA30_AUTH().

Please note that use with Access 2.0. is NOT supported.
 
 

7. Local Functions in the DLL

Note that these functions are performed entirely in the DLL.  No data is sent to the server.  This means of course that the client does NOT have to be linked to the server and therefore these calls may be made before the call to init_CA30_link.

7.1 Local validation of a card without going to the Server Gateway

As with the auth request, a swiped card track 2 may be supplied instead of the card number and in this case the issue number, expiry date and start date are never needed.

Return of the data from a swiped card

With the current issue of the software, a swiped track 2 will be analysed and the data returned in the following fields:
 

card_number	the card number (replacing the track 2 data !!!)
card_issue	the issue number or blanks
card_expiry_date	the expiry date (mmyy)
start_date	the start date (mmyy) or blanks

To request the return of this data the card issue field should be set to "??".

The data will only be returned if both the above conditions are true, and only if the strings for the dates are both exactly 4 characters plus terminator long.

If the card failed the validation in any way (i.e. the value returned from the function is not zero), then the issue number field will be left at "??" and no values will be returned.

The following error codes will be returned in the field card-issue
:

Error code	Reason
E1	the pointer card expiry date was supplied as NULL in the call
E2	the pointer card start date was supplied as NULL in the call
E3	the string in the in the users memory pointed at by card_expiry_dateis not exactly 4 characters plus terminator
E4	the string in the in the users memory pointed at by card_expiry_dateis not exactly 4 characters plus terminator

These are all programming errors in the calling program and cannot be triggered by the data supplied in the call!

The fields amount, message_type, auth_type, auth_code, merchant_number and user_ref

are not checked, however they may be referred to and MUST be presented as correctly terminated strings (one space for all values will work well)

The routine will return zero to indicate success and a negative number to indicate the following errors:-

card not accepted -68
card expiry date exceeded -69
luhn check(s) fail -71
card found in hot card file -72
card size invalid -73
invalid character found in card/track2 -74
card number length wrong -75
invalid service code -76
card not found in IIN table -77
card must be checked on-line -78
unidentifiable card -80
issue number invalid -81
card not yet valid -82

The following table shows what would have happened if the same details had been submitted for authorisation proper.  The returned message would have had a response code of 30 and the message shown in the second column.  The last column indicates the cause/rectification of the error.
 
 
 

Error	Server response message	The cause of failure.
-68	Card not accepted	The card is present in the iin table, but the card scheme is coded as "-" to reject this card explicitly.
-69	The Card has expired	The expiry month/year is less than the current month/year
-71	Card Number invalid. Please check	The card number has an invalid luhn check digit.
-72	Retain Card and ring Auth Centre NOW	The card and issue number are present in the hot card file.
-73	Invalid card format	The card number is longer than 19 digits
-74	Invalid character(s).	A non-numeric character was found in the card-number
-75	Invalid PAN length	The length of the card number does not match that prescribed in the iin table.
-76	Card not allowed at this terminal	The details in the track2 data prescribe rejection
-77	Card description not found in iin table.	As it says!
-78		The swiped details force the card to go online. If relying on local validation the card must be rejected. Note that this return value in local_CA30_validation does not have an equivalent error text from the server, since the action of the server is to force an on-line authorisation whatever the floor limit.
-80	Card number not in any data set	There is no issuer data for this card in the data sets. This error cannot occur in local_CA30_validation
-81	Invalid issue number length	Either the issue number should have been supplied and it was not, or else it was greater than 9 and should have been a single digit.
-82	Card start date in the future	The iin data says that the card must have a start date and there is none or else it is later than this month..

7.2 Establishing card properties

int identify_CA30_card(card_number,pan_length,issue_no_length,start_date,scheme_letter,scheme_name,processing_requirement)
 
 

Parameter Name	Type	Direction	Description
card_number	char *	Input	The card number (track 2 or keyed PAN)(see Note 1)
pan_length	char *	Output	The amount is returned for confirmation
issue_no_length	char *	Output	The response code from the issuer
start_date	char *	Output	The authorisation code
scheme_letter	char *	Output	The message containing the authorisation outcome
scheme_name	char *	Output	The phone number to be rung for a referral
processing_requirement	char *	Output	The message date

Notes

1. No checks are made on the card number, the routine simply ignores all leading non-digits ( expected to be a ; if a track2 is supplied) and takes the card number to be a consecutive series of digits, terminating at the first character that is not a digit ( the null terminator for a keyed card and the number terminator - an equals sign - if a swiped track 2 is supplied).  The card number supplied in the call will not be modified at all.

2. The output parameters may be supplied as character array names or suitably initialised character pointer variables.  The initial contents of the areas supplied will be disregarded.

3. The minimum sizes of the areas supplied must be as follows:
 

Parameter	Minimum Length
pan_length	3
issue_no_length	2
start_date	2
scheme_letter	2
scheme_name	17
processing_requirement	2

The sizes given include space for the null terminating the string.

System requirements

The file CARD-IIN.DAT, which normally resides in \CREDIT\BIN and is used by the server, must be available to the DLL. It must therefore be in the working directory ( the "start in" folder ) of the application calling the DLL!!

Value returned by the function

If the function is successful it will return result 0 (zero).

If the card-iin.dat is not present, there will be a display or screen message and the value returned will be indeterminate. This will be changing to -9 in a future release.

If the card cannot be identified, then -1 will be returned.

If the card has been identified, but the length of the card number is incorrect, then -2 will be returned.

Note that the check digit is NOT checked by this function.
 

Values returned in the parameters

All values are returned as character strings, including numeric values, which must be reconverted to numbers by the user.

It should be remembered that even where the string returned always has length one the value returned is a numeric ascii digit not a numeric binary value.

The contents of the strings returned are as follows:

pan_length

EITHER  The actual length of the card between 11 and 19
OR The number zero meaning any length (this will only occur with a card scheme of "-")
OR The number 1 meaning that any length between 11 and 19 inclusive is acceptable.

issue_no_length

A number between 0 and 2 inclusive giving the length of the issue number for this card type. 0 means that the card does not have an issue number. Note that it is not necessary for the client to provide the exact length in a later call to the CreditAble API, as the server will format the number correctly, provided it is not too large ( i.e. greater than 9 for a 1-digit issue number).

start_date

A "y" if the start date should be checked ( and is required input to the server), and "n" otherwise.

scheme_letter

A single capital letter, usually the first or second letter of the card scheme name. A "-" may be returned indicating that the card cannot be accepted at all.

scheme_name

The name of the scheme to which the card belongs, e.g. Mastercard, Visa, Switch, American Express.

processing_requirement

A digit 0,1,2 or 3 meaning as follows:
 

0	no special processing requirement
1	only acceptable if swiped
2	only acceptable if electronically authorised
3	1 & 2 combined

 

8.0 Functions to supply additional data for a transaction.

• Currency Processing
• Card Security Code and Address validation
• E-commerce indication

Note that in every case the data must be added for every transaction, that means that the call should be made once, immediately preceding the call to request_CA30_auth for each transaction.  All settings arising from these functions are lost as soon as the transaction is transmitted to the server. Calling one of these functions will NOT cause a call to the server or the bank for authorisation.  If two or more calls to these functions are made before the call to request_CA30_auth, then only the values used in the last call will be used. Any one, two or even all three calls may be used set the the required data if required.
 

8.1 Currency Processing

This function sets up the currency and country for the subsequent authorisation request.
 

Parameter Name	Type	Description
currency	char *	The three digit ISO code for the currency
country	char *	The three digit ISO code for the country of the transaction

Results

Note that using this call is an alternative to to the method of selecting currency by using proxy merchant numbers.  If that method is being used, then this call should NOT be used.
 

8.2 Card Security Code and Address validation

This function sets these values for the immediately following authorisation request.
 

Parameter Name	Type	Description
csc	char *	The three digit CSC code from the signature strip
postcode	char *	The post code information
address	char *	The address information

Results

Any or all of the three pieces of information may be set.  Only the data supplied will be checked.  The post code and address data may be supplied in full as the CreditAble routines will extract the numeric data required by the bank.  The client program may do this itself if so desired.

It would not make sense to do this, but the call could be made many times, the values will be taken from the last call made before request_CA30_auth is made.
 

int get_CA30_verification(csc,postcode,address)

This call should only be used if set_CA30_verification has been used before the call to request_CA30_auth.  The call to get_CA30_verification must be made immediately after a successful call to retrieve_CA30_response ( that is: one which returned data).
 
 

Parameter Name	Type	Description
message	char *	The approved display message for the response
response array	char *	The 6 decimal characters returned as response

Results

See the  general description of verification for a list of the characters in the response array and their meanings.
 

8.3 E-commerce  transactions.

This function sets these values for the immediately following authorisation request.
 
 

Parameter Name	Type	Description
ecom	char *	A single character. "y" means this IS an e-commerce trans
emv	char *	The EMV terminal type

Results

Setting ecom to "y" will cause the server to apply e-commerce message types to the authorisation request.  The information will be stored and used to mark transactions as e-commerce on delivery as well.  Using this call is an alternative to setting the correct (e-commerce) message type in the call to request_CA30_auth.  If set_CA30_ecommerce is used then the message type should be left as 20 or 61 as for any other type of transaction.

This call may be unnecessary in an internet-only system as the setup can be done without programming by setting e-commerce=y in the main server configuration file.  In that case the use of this call would only be necessary if there were varying levels of security for the card-holder to merchant link..

The field emv can be used to set the "emv terminal type".  This is used to show the level of security used for the collection of card details from the card holder.  See emv-terminal-type  in the main configuration file for a description of the values that may be used.  If all transactions have the same level of security, then it should be set in the server and this field should be left as an empty string.  Otherwise the default value should be set in the server and this call should be used to mark those transactions with a different security level.
 

THD / TRS June 2001-April 2003

Return to:...Home Page / Contents Page