2. Home
  4. PAYDirect
  6. REST Service API
  8. Customer Data Validation

Customer Data Validation

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

Note

  1. Interswitch Bill Payment platforms would communicate to third party platforms via HTTP Post.
  2. The data sent via HTTP Post will be xml, hence the content type is text/xml.
  3. The request message will not be in a parameter but a raw post directly to stream.
  4. In cases where you choose to implement Customer Validation and Payment Notification (see section 2.1), you are expected to provide Interswitch with a single url that accepts both message.
  5. Ensure CamelCase naming convention is used for the field returned in the xml
  6. See Appendix 9.0 for the process flow of Customer Validation

CustomerInformationRequest 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.

FieldMandatory/OptionalLengthFormatDescription
ServiceUrlMandatoryANYAlphanumericThird party platform service url
ServiceUsername OptionalANY Alphanumeric Username to access Service at Merchant’s end
ServicePassword OptionalANY Alphanumeric Password to access Service at Merchant’s end
FTPUrlOptionalANYAlphanumericThird Party platform FTP Location
FTPUsername OptionalANY Alphanumeric Username to access FTP Location at Third Party’s end
FTPPassword OptionalANY Alphanumeric Password to access FTP Location at Third Party’s end
MerchantReference MandatoryANY Alphanumeric Unique ID given by Interswitch to the client using the bill payment solution
CustReference MandatoryANY Alphanumeric Unique ID for the paying customer or specific order. Typically provided to the paying customer by the merchant
PaymentItemCategoryCodeOptional10AlphanumericAgreed code used to group items customers can pay for
PaymentItemCode Optional10Alphanumeric This is an agreed code indicating the item that the customer has indicated he wants to pay for.
TerminalIdOptional8AlphanumericUnique identifier for Terminal
AmountOptionalANYNumericAmount to be paid, NB: You must return amount has 0, when customers can pay for 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 that additional tags can be added at any time, ensure your system does not break due to this.

Customer Validation Request
Customer Validation Response without Payment Item

CustomerInformationResponse Fields

This defines the expected xml tags that should be returned by third party systems during Customer Validation. Interswitch Bill Payment platforms use the status to determine if it is a valid customer or not.

FieldMandatory/OptionalLengthFormatDescription
MerchantReference MandatoryANY Alphanumeric Unique ID given by Interswitch to the client using the bill payment solution
CustomersMandatoryContainer element for a collection of Customers
CustomerMandatoryContainer element for a customer
StatusMandatoryANYNumericThis is a status returned indicating if the customer is valid or not.
0 = Valid
1 = Invalid
2 = Expired
StatusMessage OptionalANY Alphanumeric Description of the Status
CustReference MandatoryANY Numeric Unique ID for the paying customer or specific order. Typically provided to the paying customer by the merchant
CustomerReferenceAlternate OptionalANY Alphanumeric This is an alternate ID used to identify the same Customer
FirstName MandatoryANY Alphanumeric This is the first name of customer
LastName OptionalANY Alphanumeric This is the surname of customer
OtherName OptionalANY Alphanumeric This is the middle name of customer
Email OptionalANY Alphanumeric This is the email address of the customer
Phone Number OptionalANY Alphanumeric This is the phone number of the customer
ThirdPartyCode Optional10Alphanumeric This is a unique code agreed between both Systems to group the customer in a category.
Amount MandatoryANY Numeric This is the amount 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 individual payment item
ProductName Optional (Mandatory if returning payment item)ANY Alphanumeric This is the name of the item that 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 item that 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 Validation Response with Payment Item

NB: Use response when returned amount is greater than 0.
Was this article helpful to you? Yes 5 No 6

How can we help?