Windcave provides a SFTP Batch solution for the merchant who need to process large number of transactions quickly, easily and securely.
SFTP Batch has been specifically designed to support organizations that do regular billing for the same or variable amounts and do not want the compliance cost or risk of storing sensitive card details.
Windcave SFTP Documentation (PDF): Click here to download
The merchant needs to initiate a SFTP (SSH File Transfer Protocol) connection with Windcave and once the connection has been established the SFTP Server monitors the server for input batch files. When an input file is detected the file is sent to the central batch processor for processing. Once processed, an output file is put in the OUTPUT folder for merchant pickup.
Organizations who wish to access the Windcave SFTP service must provide Windcave with the IP address of the originating machine.
Host: sftp.windcave.com
Port: 22
There are two methods in which organizations can login to the Windcave SFTP server.
The Input file format is CSV (Comma Separated Value), Excel style. Each line of the file represents an authorisation, purchase, completion, refund or add cards request.
Please note in order to avoid any unexpected errors in the output the input file needs to contain ASCII text characters only and it should not contain any Unicode characters. If there is any unexpected errors in the output please remove any hidden characters in the input file.
Windcave will ensure that all lines within the body contain valid transactions and that the transaction count and total in the footer before attempting to process the transactions contained in the batch. Where actual card numbers have been used in the batch input these will be truncated within the output file.
| Field | Value |
|---|---|
| Header | "PXBatchStart" |
| Batch ID | Unique Identifier assigned by organisation |
The body contains the information required for the transactions. There are several different transaction types available and each of them contains a slightly different body format.
| Field | Parameter | Description |
|---|---|---|
| 1 | TxnType | Transaction type that you would like to send. Can be Purchase Refund Tipping or Billing type transactions. Valid values are 'A'=Auth 'C'=Completion 'P'=Purchase 'R'=Refund 'V'=Validate 'B'=Bill |
| 2 | Account | Windcave account number. Values can be 0-9999 depending upon account to settle to. |
| 3 | MerchantReference | Free transaction reference field. E.g.: booking reference order reference or invoice number. |
| 4 | CardNumber/ DPSBillingId/CardId/CardNumber2 | Card Number. Note - must be followed by a single ' character if this file is loaded and saved using Microsoft Excel spreadsheet. |
| 5 | ExpiryDate | Card Expiry Date in MMYY format. Some acquirers do not require this field - contact Windcave for more details. Also not required if DpsBillingId/CardId is used. |
| 6 | Amount | Amount in d.cc format e.g. $1.23 would be 1.23 |
| 7 | PreAuthNumber/ DpsTxnRef | Either PreAuthNumber or DpsTxnRef/TransactionId (Preferred) needs to present for completion requests to match against original authorisation. DpsTxnRef/TransactionId will also need to be present for Refund transactions to match the original Purchase Completion or Billing transaction. |
| 8 | CPC | Corporate Purchase Card transactions. Extended data which will appear on corporate cardholder's statements if your merchant account supports it. |
| 9 | CardHolderName | Cardholder Name if known. |
PXBatchStart,BatchReference123
P,9997,Ref1,4111111111111111,1010,1.23, , ,TEST NAME1
P,9997,Ref1,5431111111111111,1010,1.23, , ,TEST NAME2
P,9997,Ref1,371111111111114,1010,1.23, , ,TEST NAME3
PXBatchEnd,3,3.69
Scenarios for other transaction types are available at Batching Scenarios.
The Output file format is CSV (Comma Separated Value), Excel style. The original filename is used with the suffix "_OUT" appended to the original name. The file type .CSV is preserved. Each line of the file represents an authorisation, purchase, completion or refund result. All the Output files will be placed in an output folder.
| Field | Value |
|---|---|
| Header | "PXBatchStart" |
| Batch ID | Unique Identifier assigned by organisation |
| Batch Success | "0" if successful |
| Reason | "Batch successful" or Reason for failure if applicable |
| Field | Parameter | Description |
|---|---|---|
| 1 | TxnType | Transaction type that you would like to send. Can be Purchase Refund Tipping or Billing type transactions. Valid values are 'A'=Auth 'C'=Completion 'P'=Purchase 'R'=Refund 'V'=Validate 'B'=Bill |
| 2 | Account | Windcave account number. Values can be 0-9999 depending upon account to settle to. |
| 3 | MerchantReference | Free transaction reference field. E.g.: booking reference order reference or invoice number. |
| 4 | CardNumber/DpsBillingId/CardId/CardNumber2 | Card Number. Note - must be followed by a single ' character if this file is loaded and saved using Microsoft Excel spreadsheet |
| 5 | ExpiryDate | Card Expiry Date in MMYY format |
| 6 | Amount | Amount in d.cc format e.g. $1.23 would be 1.23 |
| 7 | PreAuthNumber/DpsTxnRef/TransactionId | Either PreAuthNumber or DpsTxnRef/TransactionId (Preferred) needs to present for completion requests to match against original authorisation. DpsTxnRef/TransactionId will also need to be present for Refund transactions to match the original Purchase Completion or Billing transaction. |
| 8 | CPC | Corporate Purchase Card transactions. Extended data which will appear on corporate cardholders statements if your merchant account supports it. |
| 9 | CardHolderName | Cardholder Name if known. |
| 10 | Result | Success of the transaction. 0=declined/failed 1=accepted |
| 11 | ResponseCode | 2 character response code e.g.: "00" |
| 12 | ResponseText | Text associated with response code. E.g.: "ACCEPTED" |
| 13 | AuthCode | Authorisation (Approval) code if accepted. |
| 14 | DpsTxnRef/TransactionId | Windcave' unique transaction reference of the new transaction |
| 15 | AcquirerDate | YYYYMMDD |
| 16 | AcquirerTime | HHMMSS |
| 17 | DateSettlement | YYYYMMDD |
PXBatchStart,BatchReference123,0,Batch successful
P,9997,Ref1,411111......1111,1010,1.23,, , TEST NAME1,1,00,APPROVED,151837,0000000101a19474,20121025,151837,20121025
P,9997,Ref1,411111......1111,1010,1.23,, , TEST NAME2,1,00,APPROVED,151837,00000001015bac95,20121025,151837,20121025
P,9997,Ref1,411111......1111,1010,1.23,, , TEST NAME3,1,00,APPROVED,151837,0000000103s45dh7,20121025,151838,20121025
PXBatchEnd,3,3.69
- When the transaction count doesn't match in the input file:
Output file with error message: hash total in footer is incorrect
- When transaction amount total doesn't match in the input file:
Output file with error message: transaction count in footer is incorrect
Purchase Transactions
Input Sample
PXBatchStart,Batch1
P,9997,Ref1,4111111111111111,1010,1.23, , ,TEST NAME1
PXBatchEnd,1,1.23
Output Sample
PXBatchStart,Batch1,0,Batch successful
P,9997,Ref1,411111......1111,1010,1.23,, , TEST NAME1,1,00,APPROVED,151837,0000000101a19474,20121025,151837,20121025
PXBatchEnd,1,1.23
Refund Transactions
Input Sample
PXBatchStart,Batch1
R,9997,Refund,,,1.23, 0000000101a19474,,TEST NAME
PXBatchEnd,1,1.23
Output Sample
XBatchStart,Batch1 ,0,Batch successful
R,9997,Refund,,,1.23,0000000101bbc153,,TEST NAME,1,00,APPROVED,152225, 0000000101a19474,20121029,152225,20121029
PXBatchEnd,1,1.23
Note: The DpsTxnRef/TransactionId is 0000000101a19474. This value is given as the output in the original purchase, complete or billing transaction. All refund transactions need to be matched with the original transaction.
Authorisation Transactions
Input Sample
PXBatchStart,Batch1
A,9997,Auth1,4111111111111111,1010,1.23,,,TEST NAME
PXBatchEnd,1,1.23
Output Sample
PXBatchStart,Batch1 ,0,Batch successful
A,9997,Auth1,411111......1111,1010,1.23,,,TEST NAME,1,00,APPROVED,15282401bbd3f600000001,0000000101bbd3f6,20121029,152824,20121029
PXBatchEnd,1,1.23
Note: The Pre-Authorisation code (15282401bbd3f600000001) is given back and can be used to complete transactions.
Note: The DpsTxnRef/TransactionId (0000000101bbd3f6) is given back and is the preferred method for matching the completions.
Completion Transactions using Pre-Auth Number
Input Sample
PXBatchStart,Batch1
C,9997,Completion,,,1.23,15282401bbd3f600000001,,TEST NAME
PXBatchEnd,1,1.23
Output Sample
PXBatchStart,Batch1 ,0,Batch successful
C,9997,Completion,,,1.23,15282401bbd3f600000001,,TEST NAME,1,00,APPROVED,153424,0000000101bbe227,20121029,153424,20121029
PXBatchEnd,1,1.23
Note: The Pre-Auth Number is highlighted above. This value was given as the output from the original authorisation transaction.
Completion Transaction using DpsTxnRef/TransactionId
Input Sample
PXBatchStart,Batch1
C,9997,CompDPSTxnRef,,,1.23,0000000101bbd3f6,,TEST NAME
PXBatchEnd,1,1.23
Output Sample
PXBatchStart,Batch1 ,0,Batch successful
C,9997,CompDPSTxnRef,,,1.23,0000000101bbd3f6,,TEST NAME,1,00,APPROVED,153649,0000000101bbe7b1,20121029,153649,20121029
PXBatchEnd,1,1.23
The output format has the following properties in addition to the input message - Authorized (1 or 0), ReCo, Response Text, DpsBillingId/CardId, DpsTxnRef/TransactionId, Date, Time, DateSettlement
Billing Transactions with DpsBillingId/CardId
Input Sample
PXBatchStart,Batch1
B,9997,dpsbillid,0000010003224216, ,1.23, , ,TEST NAME
PXBatchEnd,1,1.23
Output Sample
PXBatchStart,Batch1 ,0,Batch successful
B,9997,dpsbillid,0000010003224216, ,1.23,, ,TEST NAME,0,JA,DECLINED,,,,,19800101
PXBatchEnd,1,1.23
Billing Transactions with CardNumber2
Input Sample
PXBatchStart,Batch1
X0009,K,9997,Charge CardNumber2,0090200000000023, ,1.00, , , ,123
PXBatchEnd,1,1.00
Output Sample
PXBatchStart,Batch1 ,0,Batch successful
X0009,K,9997,Charge CardNumber2,0090200000000023, ,1.00, , , ,123,1,00,APPROVED,175305,0000000101a2fd17,20121025,175305,20121025
PXBatchEnd,1,1.00
Note: The CardNumber2 value is 0090200000000023.
To add a billing card to the Billing Vault and receive a token for subsequent billing purposes you will use a different message format. A format specifier, "X0006", must appear as the first field in every record.
Valid TxnTypes are "P", which processes a purchase transaction and stores the card details, "A", which processes an authorisation transaction and stores the card details, and "H", which simply stores the card details without processing a financial transaction.
X0006, TxnType, Operation, Account, Merchant Reference, Card Number, Expiry, Amount, Issue Number, Card holder name
For "H" transaction type use an amount of "1.00" which will be disregarded as no financial transaction takes place.
Add DpsBillingId/CardId
Input
PXBatchStart,Batch1
X0006,H,Add,9997,create token 1,4111111111111111,1010,1.00, ,C HOLDER
PXBatchEnd,1,1.00
Output
PXBatchStart,Batch1,0,Batch successful
X0006,H,Add,9997,create token 1,411111......1111,1010,1.00, ,C HOLDER, ,1, ,ADDED,0000010003224216, , , ,
PXBatchEnd,1,0.00
To add a CardNumber2 value you will use a different message format. A format specifier, "X0008", must appear as the first field in every record.
X0008, TxnType, Operation, Account, Merchant Reference, Card Number, Expiry, Amount, Issue Number, Card holder name
Add Cardnumber2
Input
PXBatchStart,Batch1
X0008,H,Add, ,create CardNumber2 1,4111111111111111,0110, , ,C HOLDER
PXBatchEnd,1,0.00
Output
PXBatchStart,Batch1,0,Batch successful
X0008,H,Add, ,create CardNumber2 1,411111......1111,0110, , ,C HOLDER,1, ,ADDED,0090200000000023,2BC29AF2, , ,
PXBatchEnd,1,0.00
2BC29AF2 = TxnMac Value
Some card issuer have risk management rules in place that cause a transaction to be declined if it is the same card and the same value being processed within 5 minutes of each other. Therefore the exception handling service is designed to handle this scenario.
If a transaction is submitted in a batch file that has the same cardnumber and transaction amount, the transaction will be put into a sub-file for later processing.
The exception handling services is turned off by default. For more information on enabling the Exception Handling, please contact [email protected]
Account (input) Max 4 characters
Accounts with Windcave can be setup with multiple merchant numbers. This field can be used to specify which merchant number should be used to process the transaction. Allowed values range between 0-9999. If only one merchant account has been setup this value will usually be 1 for a live account. And 9997 for a development account. Please contact Windcave to confirm the value that should be used in this field.
AcquirerDate (output) Max 8 bytes
Contains the date the transaction was processed in YYYYMMDD format. This field may be blank if the transaction was rejected locally or otherwise not processed by the bank host.
AcquirerTime (output) Max 8 bytes
Contains the date the time of the day the transaction was processed in HHMMSS format. This field may be blank if the transaction was rejected locally or otherwise not processed by the bank host.
Amount (input) Max 13 characters
Set the amount to be charged or refunded (depending on the TxnType). Format is d.cc (d=dollars, c=cents). Max amount is 99999.99
AVS Post Code (output) Datatype: BSTR Max 20 bytes
Address Verification System property. Post Code that is listed on the customer's bank statement.
AVS StreetAddress (output) Datatype: BSTR Max 60 bytes
Address Verification System property. Address that is listed on the customer's bank statement.
AVS Action (output) Datatype: INT Max 1 bytes
Address Verification System property. Values are 0,1 & 2.
The value will most likely be 1 for most circumstances.
CardHolderName (output) Max 64 characters
The cardholder name as it appears on customer card.
CardId (input/output) Max 16 Characters
CardId is the Windcave REST API parameter exact equivalent to DpsBillingId – they are two different names for the same data item. When output, contains the Windcave generated token. Only returned for transactions that are requested by the application with the EnableAddBillCard value set to 1 (true) indicating a token billing entry should be created.
CardNumber (input) Max 20 characters
The card number. No leading or embedded blanks are permitted. Must contain a numeric value.
Corporate Purchase Card (input) Mandatory 30 characters
Amex Corporate Purchase Card transactions. Extended data, which will appear on corporate cardholders statements if your merchant account supports it. This field needs to be exactly 30 characters, with the first character being an "A". The CPC field contains 2 corparate purchase card reference fields, with the 1st 9 characters after the "A" belonging to Corporate Purchase Card data 1 and the last 20 characters of the CPC input field belonging to Corporate Purchase Card data 2. You will need to pad if your reference is shorter than the required field length.
Example - P,9997,Reference,4111111111111111,1010,1.23,,A4387436 Payment March ,TEST NAME
DateExpiry (input) Max 4 bytes
Indicates card expiry date. Format is MMYY where MM is month 01-12 and Year 00-99. do not insert "/" or other delimiter. Some acquirers do not require this field - contact Windcave for more details. Also not required if DpsBillingId/CardId is used.
DateSettlement (output) Max 8 bytes
Indicates Date of settlement (when money will be deposited in Merchant bank account) if this is supported by the Acquirer, otherwise contains the date the transaction was processed in YYYYMMDD format.
DpsTxnRef (input/output) Max 16 Characters
Returned for every transaction. If the transaction was approved, DpsTxnRef can be used as input to a Refund or Completion transaction for other Windcave products. Used to specify a transaction for refund without supplying the original card number and expiry date. The DpsTxnRef value returned by the original approved Auth transaction must be supplied also when doing a complete transaction.
DpsBillingId (input/output) Max 16 Characters
When output, contains the Windcave generated token. Only returned for transactions that are requested by the application with the EnableAddBillCard value set to 1 (true) indicating a token billing entry should be created.
MerchantReference (input) Max 32 Characters
Free text to appear on transaction reports.
ResponseText (output) Max 20 Characters
The Response Text is associated with ResponseCode. For successful transactions this is usually Approved and for unsuccessful transactions this can be a number of texts depending on why the transaction declined. For example it could be Card Expired, Declined, Invalid Card, REFER TO CARD ISSUER, DO NOT HONOUR. All acquirers have their own response texts and should be displayed for better understanding of why the transaction got declined.
ResponseCode (output) Max 2 characters
2 character response code from the bank. Explanation of the ResponseCode is usually provided in the ResponseText.
Result (output) Boolean true/false
Indicates success or failure of the transaction. 1 for successful and 0 for an unsuccessful transaction.
TransactionId (input/output) Max 16 Characters
TransactionId is the Windcave REST API parameter exact equivalent to DpsTxnRef – they are two different names for the same data item. Returned for every transaction. If the transaction was approved, DpsTxnRef can be used as input to a Refund or Completion transaction for other Windcave products. Used to specify a transaction for refund without supplying the original card number and expiry date. The DpsTxnRef value returned by the original approved Auth transaction must be supplied also when doing a complete transaction.
TxnType (input) Max 1 Character
| Value | Description |
|---|---|
| P | Purchase |
| R | Refund |
| A | Auth |
| C | Completion |
| V | Validate |
| B | Bill |