Introduction

This documentation defines the service message specification between Interswitch and Third Party Platforms who wish to process payments using the AutoPAY platform via SFTP. Third Party platforms are expected to drop a file in Interswitch /IN SFTP folder, this would be picked and processed by AutoPAY. Transaction status would be gotten from the /OUT SFTP folder, while any errors encountered reading the input file would be in the /ERROR SFTP folder. This integration is broken down into two phases.


Phase 1: Balance Enquiry and PIN change

Your system must be able to perform balance enquiry call and PIN change call. Find more details on how to make a balance enquiry here.


Phase 2: Crediting Beneficiaries

To credit beneficiaries, follow the steps below:

  • Constructing a valid file.
  • Connecting to the IN folder of our SFTP location to drop the file.
  • Connecting to the ERROR (to read files with errors) and OUT folder (to read files that have successfully been processed).

Find more details on how to credit beneficiaries here.

SFTP File Format

Introduction

Field Mandatory (M)/Optional (O) Length Format Description
Batch_Reference M Alphanumeric Code to uniquely identify a batch of payments NB: This must be unique per batch.
Batch_Description M Alphanumeric  This describes the batch e.g. Salary Payments.NB: This must be unique per batch.
Is_Single_Debit M Boolean True or false True means -- you want single debit (line-by-line debit) on your corporate account while False means -- you want bulk debit on your corporate account. This requires Float card.
Terminal_Id M 8 Alphanumeric Uniquely identified the third party system. It will be provided by Interswitch.
Secure_Data M Alphanumeric Sample Code would be provided in JavaScript and C# on how to generate secure data using Source Card Pan, Expiry and Pin. Please click here to download Library JavaLibrary, JavaScript, C#_CSVFileGeneration, C#_BalanceEnquiryandPinChange
Source_Account_Number M <=25 Numeric Ensure NUBAN for commercial banks. For prepaid card load, specify the card number (PAN).
Source_Account_Type M 2 Numeric Specify whether account is savings or current. See appendix for options.
Encrypted_Pin M Alphanumeric Cryptographically secure pin data
Mac_Data M Alphanumeric Concatenate Terminal ID, beneficiary code(s), total amount and beneficiary account number(s). Hash using the SHA512 algorithm.  (See appendix for sample code)
PaymentRef M Alphanumeric A unique reference tied to each payment item. NB: This must be unique per beneficiary.
Amount M Numeric Amount for each Beneficiary, sent in lower denomination.
BeneficiaryCode M Alphanumeric Usually the Employee ID, Contractor ID, etc. Account number may be used. Please note that this must be unique per beneficiary
Beneficiary_Name M Alphabetic Name of Beneficiary
Bank_Cbn_Code M <=3 Numeric A code for each bank. See appendix
Beneficiary_Account M <=25 Numeric Ensure NUBAN for commercial banks. For prepaid card load, specify the card number (PAN).
Beneficiary_Account_Type M M 2 Numeric
Narration O  Alphanumeric Uniquely describes what the payment is intended for, example are "Salary payment, Refunds and vendor payment"
IS_PrepaidLoad M 1 Boolean Used to specify if a card or account is being credited. (True / False)
Mobile_Number O >11 Numeric Beneficiary mobile number

Source_Account_Number : Pass any valid NUBAN account No.

Source_Account_Type: Pass the account type tied to the above Source_Account_Number.

Note: The PAN,CVV,PIN, and Expiry date are values used to compute the Secure_Data, Encrypted_PIN and AUTH_DATA. - Secure_Data, and Encrypted_PIN: These are values generated when creating a file. - AUTH_DATA: This value is used for balance enquiry and PIN change.

Refer to the below link to access the libraries that would assist you in generating Secure_Data, Encrypted_PIN and AUTH_DATA.

Secure_Data, Encrypted_PIN and AUTH_DATA Libraries.

The libraries are only available in C# or JavaScript.

/IN File Format

Row Format Description
1 Batch_Reference, Batch_Description, Is_Single_Debit, Terminal_Id Batch header information
2 Secure_Data, Source_Account_Number, Source_Account_Type, Bank_Cbn_Code, Encrypted_Pin,Mac_Data Consists of payment information up until the second to the last row
3 to n Secure card data paymentRef, Amount, Narration, BeneficiaryCode, Beneficiary_Email_Address, Beneficiary_Bank_Cbn_Code, Beneficiary_Account, Beneficiary_Account_Type, IS_PrepaidLoad,Currency_Code, Beneficiary_Name, Mobile_Number

Batch File Template for Manual Commit

Row Format Description
1 Batch_Reference, Batch_Description, Is_Single_Debit, Terminal_Id Batch header information
2 Source_Account_Number, Source_Account_Type, Bank_Cbn_Code, Mac_Data Source Account details
3 to n PaymentRef, Amount, Narration, BeneficiaryCode, Beneficiary_Email_Address, Beneficiary_Bank_Cbn_Code, Beneficiary_Account, Beneficiary_Account_Type, IS_PrepaidLoad, Currency_Code, Beneficiary_Name, Mobile_Number Consists of payment information up until the second to the last row.

Note

  1. The Secure_Data and Encrypted_Pin are not needed for the Manual Commit, however there rightful locations should not be deleted/removed even though they are blank.
  2. The source Account number on ROW 2, must be already configured on Autopay UI
  3. Please note that for manual commit, when the batch file is dropped into the corporate SFTP /IN folder, approval, authorization and the final commit are done via the Autopay User interface (UI).

/OUT File Format

Row Format Description
1 Batch_Reference , Batch_Description , Is_Single_Debit , Terminal_Id, RESPONSE_CODE Batch header information
3 to n PaymentRef , Amount , Beneficiary_Name , Bank_Cbn_Code , Beneficiary_Account, Beneficiary_Account_Type , IsPrepaidCardLoad, SWITCH_RESPONSE } Consists of payment information up until the second to the last row.

/ERROR File Format

Row Format Description
1 Batch_Reference , Batch_Description , Is_Single_Debit , Terminal_Id, RESPONSE_CODE Batch header information
2 Secure_Data , Source_Account_Number , Source_Account_Type , Bank_Cbn_Code , Encrypted_Pin , Mac_Data, RESPONSE_CODE Secure card data
3 to n PaymentRef , Amount , Narration, BeneficiaryCode, Beneficiary_Email_Address, Beneficiary_Bank_Cbn_Code , Beneficiary_Account, Beneficiary_Account_Type , IS_PrepaidLoad, Currency_Code, Beneficiary_Name, Mobile_Number, RESPONSE_CODE Consists of payment information up until the second to the last row.

File Format Samples

File Type File Link
IN KGCTest_IN
OUT KGCTest_OUT
ERROR KGCTest_ERROR

Bank CBN Codes

Bank Name CBN Code CBN Short Code
Access Bank Plc 044 ABP
Access Bank Plc (Diamond) 063 DBP
Ecobank Nigeria 050 ECO
Enterprise Bank Plc 084 ENB
Fidelity Bank Plc 070 FBP
First Bank of Nigeria Plc 011 FBN
First City Monument Bank 214 FCMB
Guaranty Trust Bank Plc 058 GTB
Heritage Bank 030 HBP
Jaiz Bank 301 JAIZ
Keystone Bank Ltd 082 KSB
Mainstreet Bank Plc 014 MSB
Polaris Bank 076 SKYE
Stanbic IBTC Plc 039 STANBIC
Sterling Bank Plc 232 SBP
Union Bank Nigeria Plc 032 UBN
United Bank for Africa Plc 033 UBA
Unity Bank Plc 215 UNITY
WEMA Bank Plc 035 WEMA
Zenith Bank International 057 ZIB

Appendix


Account Types

Account Type Description
00 Default
10 Savings Account
20 Current Account


First Level Validation Response Codes

Response Code Description
70012 Invalid terminal owner
20050 Message integrity validation failed
70038 Data not found
90000 Success
AX0001 Invalid Cash Card Load Field
AX0002 Invalid Bank Cbn Code Field
AX0003 Invalid Bank Account Field
AX0004 Amount not formatted
AX0005 Failed Nuban Validation
AX0006 To account type not formatted properly
AX0007 Payment Reference not found
AX0008 Invalid payment column count
AX0009 Payment Column count exceeded
AX0010 Duplicate Transaction detected
AX4001 Security Violation
AX4002 Duplicate File
AX4003 Batch Name Not Supplied
AX4004 Invalid Terminal Id
AX4005 Invalid Mac
AX4006 Invalid Source Account
AX4007 Encrypted Pin Data, Missing in secure row
AX4008 Invalid Encrypted Pin Data
AX4010 Invalid Secure Row
AX4011 General Batch Header Row Error
AX4012 Corporate Information Not Setup
AX4013 Invalid Batch Reference, found in file
AX4014 Invalid Batch Description, found in file
AX4015 Invalid Beneficiary Code, found in file
AX4016 Invalid Beneficiary Email, found in file
AX4017 Invalid Narration, found in file
AX4019 Incorrect MAC, found in file
AX4020 Invalid Rows In File (Possible less than 3)
AX4021 Unknown error while parsing secure
AX4101 Float card not configured
AX4102 Missing Account Setup (Pending Commit Mode Users)
AX4103 Source bank bin appears incorrect
AX4104 Pin change verification failure (pin possibly incorrect)
AX4105 Payments logged but not queued for processing to switch (admin to check logs) -- single processing model
AX4106 Float card load failed (Bulk model users)
AX4107 Payments logged but not queued for processing to switch (admin to check logs) -- bulk processing model
AX4108 Queue payments for processing failure, corporate configuration not found
AX4109 Queue payments for processing failure, unknown
AX4110 Error loading corporate's fee data, check fee setup
AX4111 Error loading corporate's fee data, cbn code may be invalid.
AX4112 Error loading corporate's fee type, fee type must not be letters/empty, fee type must be either 1 or 0
AX4113 Error loading corporate's fee type, fee type must be either 1 or 0
AX4114 Error loading corporate's fee, switch fee must not be letters/empty
AX4115 Error loading corporate's fee, sponsor fee must not be letters/empty
AX4118 Switch fee in file is less than minimum switch fee configured for corporate, switch fee must be equal to/greater than minimum switch fee configured for corporate


Transaction Response Codes

Code Description
00 Approved or completed successfully
01 Refer to card issuer
02 Refer to card issuer, special condition
03 Invalid merchant
04 Pick-up card
05 Do not honor
06 Error
07 Pick-up card, special condition
08 Honor with identification
09 Request in progress
10 Approved, partial
11 Approved, VIP
12 Invalid transaction
13 Invalid amount
14 Invalid card number
15 No such issuer
16 Approved, update track 3
17 Customer cancellation
18 Customer dispute
19 Re-enter transaction
20 Invalid response
21 No action taken
22 Suspected malfunction
23 Unacceptable transaction fee
24 File update not supported
25 Unable to locate record
26 Duplicate record
27 File update field edit error
28 File update file locked
29 File update failed
30 Format error
31 Bank not supported
32 Completed partially
33 Expired card, pick-up
34 Suspected fraud, pick-up
35 Contact acquirer, pick-up
36 Restricted card, pick-up
37 Call acquirer security, pick-up
38 PIN tries exceeded, pick-up
39 No credit account
40 Function not supported
41 Lost card, pick-up
42 No universal account
43 Stolen card, pick-up
44 No investment account
45 Account closed
46 Identification required
47 Identification cross-check required
51 Not sufficient funds
52 No check account
53 No savings account
54 Expired card
55 Incorrect PIN
56 No card record
57 Transaction not permitted to cardholder
58 Transaction not permitted on terminal
59 Suspected fraud
60 Contact acquirer
61 Exceeds withdrawal limit
62 Restricted card
63 Security violation
64 Original amount incorrect
65 Exceeds withdrawal frequency
66 Call acquirer security
67 Hard capture
68 Response received too late
69 Advice received too late
75 PIN tries exceeded
76 Reserved for future Postilion use
77 Intervene, bank approval required
78 Intervene, bank approval required for partial amount
90 Cut-off in progress
91 Issuer or switch inoperative
92 Routing error
93 Violation of law
94 Duplicate transaction
95 Reconcile error
96 System malfunction
97 Reserved for future Postilion use
98 Exceeds cash limit


Test Script


File Upload Test

ID Description Test
1 BatchReference and Batch Description check. BatchReference and Batch Description is unique per file
2 Requirement for Is_single_Debit has been defined.
3 Source_Account_Number check
4 Source_Account_Type check.
5 PaymentRef check.
6 Amont check.
7 Bank Code Check.
8 Beneficiary_Account_Number check.
9 Beneficiary_Account_Type check.
10 File Check.


Balance Enquiry and PIN Change Test

ID Description Test
1 Balance Enquiry -- Product_Code Check. Product_code is passed in the header of the request.
2 Balance Enquiry  Check. Balance Enquiry Request was successful
3 Pin change -- Product_Code Check. Product_code is passed in the header and body of the request.
4 Pin change -- terminalId. terminalId  is passed in the body of the request.
5 Pin change  Check. Pin change Request was successful