Customer Data Validation

This method allows Interswitch Bill Payment Platforms to validate third-party customer information before a payment is made.

📘
Implementation Notes:

Interswitch Bill Payment platforms comunicates with third-party platforms via HTTP POST.

All requests sent via HTTP POST should be in XML format; therefore the content type must be set to text/xml.

Request messages are submitted as raw XML in HTTP POST body and not as request parameters.

If Customer Validation and Payment Notification services are implemented, a single endpoint URL must be provided to Interswitch to receive both message types.

Ensure that all XML fields adhere to the CamelCase naming convention.

Customer Information Request Fields

This defines the expected XML tags that will be sent to third-party systems for Customer Validation. This is a generic system and new tags can be added at any time. Do not hard-code the structure of the XML requests. Your system should be able to retrieve data from the required fields and ignore others.

Field	Mandatory/Optional	Length	Format	Description
ServiceUrl	Mandatory	ANY	Alphanumeric	Third-party platform service URL
ServiceUsername	Optional	ANY	Alphanumeric	Username to access service at merchant's end
ServicePassword	Optional	ANY	Alphanumeric	Password to access service at merchant's end
FTPUrl	Optional	ANY	Alphanumeric	Third-party platform FTP location
FTPUsername	Optional	ANY	Alphanumeric	Username to access FTP location at third party's end
FTPPassword	Optional	ANY	Alphanumeric	Password to access FTP location at third party's end
MerchantReference	Mandatory	ANY	Alphanumeric	Unique ID given by Interswitch to the client using the bill payment solution
CustReference	Mandatory	ANY	Alphanumeric	Unique ID for the paying customer or specific order. Typically provided to the paying customer by the merchant
PaymentItemCategoryCode	Optional	10	Alphanumeric	Agreed code used to group items customers can pay for.
PaymentItemCode	Optional	10	Alphanumeric	This is an agreed code indicating the item that the customer has indicated he wants to pay for.
TerminalId	Optional	8	Alphanumeric	Unique identifier for Terminal.
Amount	Optional	ANY	Numeric	Amount to be paid. NB: You must return amount as 0 when customers can pay any amount.

Sample Customer Validation Request

This shows the sample request message that would be sent to third-party systems to validate a unique customer identified with the CustReference.

The PaymentItemCode is the specific item the customer wants to pay for.

Note: Additional tags can be added at any time. Ensure your system does not break due to this.

Customer Validation Request

         <CustomerInformationRequest>
            <ServiceUsername></ServiceUsername>
            <ServicePassword></ServicePassword>
            <MerchantReference>6405</MerchantReference>
            <CustReference>11111117</CustReference>
            <PaymentItemCode>01</PaymentItemCode>
            <RouteId>bbVendingPhcnEedcv3</RouteId>
            <Service>bill-payment-service</Service>
            <ThirdPartyCode></ThirdPartyCode>
        </CustomerInformationRequest>

Customer Validation Response (Without Payment Item)

         <CustomerInformationResponse>
            <MerchantReference>6405</MerchantReference>
            <Customers>
                <Customer>
                    <Status>0</Status>
                    <CustReference>11111117</CustReference>
                    <CustomerReferenceAlternate></CustomerReferenceAlternate>
                    <FirstName>test test</FirstName>
                    <Phone></Phone> 
                    <ThirdPartyCode></ThirdPartyCode> 
                    <Amount>0.00</Amount> 
                </Customer>
             </Customers>
          </CustomerInformationResponse>

Customer Information Response Fields

This defines the expected XML tags that should be returned by third-party systems during Customer Validation.

Note: Interswitch Bill Payment platforms use the returned status to determine whether the customer is valid or not

Field	Mandatory/Optional	Length	Format	Description
MerchantReference	Mandatory	ANY	Alphanumeric	Unique ID given by Interswitch to the client using the bill payment solution.
Customers	Mandatory			Container element for a collection of Customers.
Customer	Mandatory			Container element for a customer.
Status	Mandatory	ANY	Numeric	This is a status returned indicating if the customer is valid or not. 0 = Valid 1 = Invalid 2 = Expired
StatusMessage	Optional	ANY	Alphanumeric	Description of the Status.
CustReference	Mandatory	ANY	Numeric	Unique ID for the paying customer or specific order. Typically provided to the paying customer by the merchant.
CustomerReferenceAlternate	Optional	ANY	Alphanumeric	This is an alternate ID used to identify the same customer.
FirstName	Mandatory	ANY	Alphanumeric	This is the first name of the customer.
LastName	Optional	ANY	Alphanumeric	This is the surname of the customer.
OtherName	Optional	ANY	Alphanumeric	This is the middle name of the customer.
Email	Optional	ANY	Alphanumeric	This is the email address of the customer.
Phone Number	Optional	ANY	Alphanumeric	This is the phone number of the customer.
ThirdPartyCode	Optional	10	Alphanumeric	This is a unique code agreed between both systems to group the customer in a category.
Amount	Mandatory	ANY	Numeric	This is the amount the customer is expected to pay. Value should be in major denomination. NB: Amount must be greater than 0.
PaymentItems	Optional (Mandatory if returning payment item)	-	-	Container element for a collection of payment items.
Item	Optional (Mandatory if returning payment item)	-	-	Container element for an individual payment item.
ProductName	Optional (Mandatory if returning payment item)	ANY	Alphanumeric	This is the name of the item that the customer should/can pay for.
ProductCode	Optional (Mandatory if returning payment item)	ANY	Alphanumeric	This is the code of the item that the customer should/can pay for.
Quantity	Optional (Mandatory if returning payment item)	ANY	Numeric	This is the number of items that the customer should/can pay for.
Price	Optional (Mandatory if returning payment item)	ANY	Numeric	This is the unit price of the item that the customer should/can pay for.
Subtotal	Optional (Mandatory if returning payment item)	ANY	Numeric	This is the total amount that the customer should/can pay for less tax.
Tax	Optional (Mandatory if returning payment item)	ANY	Numeric	This is the additional cost added to the original cost of the item.
Total	Optional (Mandatory if returning payment item)	ANY	Numeric	This is the total amount that the customer should/can pay for.

Sample Customer Validation Response

This shows the sample response message that would be returned from third-party systems to Interswitch Bill Payment Platforms.

Customer Validation Response

NB: Amount is returned as 0, meaning customers will be allowed to pay any amount.

Customer Information Response

          <CustomerInformationResponse>
            <MerchantReference>639</MerchantReference>
            <Customers>
                <Customer>
                    <Status>0</Status>
                    <CustReference>23470</CustReference>
                    <CustomerReferenceAlternate>            </CustomerReferenceAlternate>
                    <FirstName>test test</FirstName>
                    <Phone></Phone> 
                    <ThirdPartyCode></ThirdPartyCode> 
                    <Amount>0</Amount> 
                </Customer>   
             </Customers>
          </CustomerInformationResponse>

Customer Validation Response (With Payment Item)

NB: Use this response when the returned amount is greater than 0

         <CustomerInformationResponse>
            <MerchantReference>639</MerchantReference>
            <Customers>
                <Customer>
                    <Status>0</Status>
                    <CustReference>23470</CustReference>
                    <CustomerReferenceAlternate></CustomerReferenceAlternate>
                    <FirstName>test test</FirstName>
                    <Phone></Phone> 
                    <ThirdPartyCode></ThirdPartyCode> 
                    <Amount>234078</Amount> 
                    <PaymentItems> 
                       <Item> 
                           <ProductName>PayAtBank</ProductName> 
                           <ProductCode>01</ProductCode> 
                           <Quantity>1</Quantity> 
                           <Price>234078</Price> 
                           <Subtotal>234078</Subtotal> 
                           <Tax>0</Tax> 
                           <Total>234078</Total> 
                       </Item> 
                    </PaymentItems
                </Customer>
             </Customers>
          </CustomerInformationResponse>