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.
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
- 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.
- The source Account number on ROW 2, must be already configured on Autopay UI
- 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 |