The BookOnHold web service is a soap service that exposes certain methods.
- The CreateBooking web method is used to make Reservations for payments so that the Customer can make payments at a later time. This is usually done by logging payment with a Transaction ID which the customer presents at the point of payment.
- The CustomerDataUpload web method is called when the customer information logged is to be reused for as long as possible by the returning customer. This is used to save customer information on Interswitch systems to be used to validate customers at the point of payment.
- The UploadThirdPartyInformation web method is used to upload custom data.
- FetchBookingDetails is used to confirm the status of a booking/reservation that has previously been logged via the CreateBooking call.
- FetchPaymentNotification is used to retrieve payment information.
- UpdateBooking is used to update a booking.
Test Endpoint: https://sandbox.interswitchng.com/bookonhold/bookonhold.asmx
CreateBooking
This method creates booking.
Request Fields
| Field | Mandatory/Optional | Length | Format | Description |
| MerchantId | Mandatory | ANY | Numeric | Unique Id assigned to merchant by Interswitch. |
| ReferenceNumber | Mandatory | 20 | Numeric | Unique reference number for this booking. The first characters must be the MerchantId above. |
| ServiceNumber | Optional | 30 | Alphanumeric | This is an alternate ID used to identify this booking. |
| Description | Mandatory | 60 | Alphanumeric | Description of the booking |
| Amount | Mandatory | n/a | Numeric | Value to be paid for this reservation. Amount paid by the customer in minor Denomination
(kobo). |
| DateBooked | Mandatory | 19 | String Date in format yyyy-MM-dd hh:mm:ss | Date when the reservation was made |
| DateExpired | Mandatory | 19 | String Date in format yyyy-MM-dd hh:mm:ss | Date when the reservation will expire |
| FirstName | Mandatory | 60 | Alphanumeric | Customer’s First name |
| LastName | Mandatory | 60 | Alphanumeric | Customer’s Last name |
| Mandatory | 40 | Alphanumeric | Customer’s Email address | |
| ItemCode | Mandatory | ANY | Alphanumeric | The unique code indicating the exact item linked to the reservation |
Response Fields
| Field | Description |
| ResponseCode | See Appendix 1.0 |
| ReferenceNumber | Same sent in the request |
CustomerDataUpload
This method saves customer detail(s) on the Interswitch Bill payment platform for local verification in anticipation of payment.
Request Fields
| Field | Mandatory/ Optional | Length | Format | Description |
| MerchantReference | Mandatory | n/a | Numeric | Unique Id assigned to merchant by Interswitch. |
| CustReference | Mandatory | 20 | Alphanumeric | Biller Unique reference for customer |
| CustomerReferenceAlternate | Optional | 30 | Alphanumeric | Biller Alternate Unique reference for customer |
| CustomerReferenceDescription | Optional | 60 | Alphanumeric | |
| Amount | Optional | n/a | Numeric | Total amount expected by customer |
| FirstName | Mandatory | 60 | Alphanumeric | |
| LastName | Mandatory | 60 | Alphanumeric | |
| Optional | 40 | Alphanumeric |
Response Fields
| Field | Description |
| ResponseCode | See Appendix 1.0 |
| CustReference | Same sent in the request |
UploadThirdPartyInformation
This method saves custom/additional data on the Interswitch Bill payment platform for local verification in anticipation of payment.
Request Fields
| Field | Mandatory/ Optional | Length | Format | Description |
| MerchantReference | Mandatory | n/a | Numeric | Unique Id assigned to merchant by Interswitch. |
| ThirdParties | Mandatory | 30 | Numeric | Biller Unique reference for customer |
| ThirdParty | Optional | 30 | Alphanumeric | Biller Alternate Unique reference for customer. |
| Code | Optional | 30 | Alphanumeric | |
| Name | Optional | 30 | Numeric | Total amount expected by customer |
| Location | Mandatory | 50 | Alphanumeric |
Response Fields
| Field | Description |
| ResponseCode | See Appendix 1.0 |
FetchBookingDetails
This method retrieves all booking details.
Request Fields
| Field | Mandatory/ Optional | Length | Format | Description |
| MerchantId | Mandatory | n/a | Numeric | Unique Id assigned to merchant by Interswitch. |
| ReferenceNumber | Optional | 20 | Numeric | Unique reference number for this booking. The first characters must be the MerchantId above. |
Response Fields
| Field | Description |
| ResponseCode | See Appendix 1.0 |
| ResponseMessage | See Appendix 1.0 |
| ReferenceNumber | Unique merchant generated reference number |
| Amount | Amount paid by customer |
| DateBooked | Date of Booking as sent by merchant |
| DateExpired | Date of Expiry as set by merchant |
| Status | Status of this booking i.e. Expired / Valid |
| PaymentStatus | Payment Status i.e. Pending / Completed |
| PaymentMethod | Method of Payment i.e. Cash or Card |
| PaymentReference | Unique system generated reference for this payment. |
| ChannelName | Channel where payment was made. |
| TerminaIId | Terminal Id where payment was made. |
| Location | Location where the payment was made. |
| PaymentDate | Date of Payment. |
FetchPaymentNotifications
This method retrieves information about the payments that have been made via the InterSwitch Bill payment platform for a service the merchant provides.
Request Fields
| Field | Mandatory/ Optional | Length | Format | Description |
| MerchantReference | Mandatory | n/a | Numeric | Unique Id assigned to merchant by Interswitch. |
| LastNotificationDate | Mandatory | 19 | String Date in format yyyy-MM-dd hh:mm | Date from when the payment should be fetched. |
Response Fields
| Field | Description |
| ResponseCode | See Appendix 1.0 |
| Payments | Container element for a collection of payments |
| Payment | Container element for a single payment |
| CustReference | Unique ID for the paying customer or specific order. Typically provided to the paying customer by the merchant |
| Amount | Amount paid by the customer. E.g. N20,000 |
| PaymentMethod | Method by which customer made payment. See list of acceptable values in appendix |
| PaymentReference | Unique reference for the payment as issued to the customer at the point of payment. This value is unique for all transactions. |
| PaymentLogId | Unique integer ID for the payment |
| Terminalld | A unique ID for the terminal through which the payment is made |
| ChannelName | Name of channel used for transaction. See acceptable values in appendix |
| Location | Location Payment was made |
| PaymentDate | Date payment was made |
| InstitutionId | Unique ID given to the merchant |
| InstitutionName | Merchant’s configured name within the Bill payment system |
| BranchName | Bank Branch where the payment was made, if applicable |
| BankName | Bank where the payment was made in case of a cash payment or bank whose card was used to pay in the case of a card based payment |
| CustomerName | Name of paying customer |
| OtherCustomerInfo | Further Details on paying customer |
| ReceiptNo | Receipt Number issued to customer |
| CollectionsAccount | The account of the Collecting Bank |
| BankCode | A code representing the Bank where the payment was made or bank whose card was used to pay in the case of a card based payment |
| ItemName | The name of an item that was paid for (There will always be at least one Item) |
| ItemCode | The code of an item that was paid for (There will always be at least one item) |
| ItemAmount | The amount that was paid for the item (Will be equal to Amount if only one item was paid for) |
UpdateBooking
This method updates a booking detail.
Request Fields
| Field | Mandatory/Optional | Length | Format | Description |
| MerchantId | Mandatory | n/a | Numeric | Unique Id assigned to merchant by Interswitch. |
| ReferenceNumber | Mandatory | 20 | Numeric | Unique reference number for this booking. The first characters must be the MerchantId above. Note that this is the Reference Number of the booking to be updated and cannot be updated. |
| ServiceNumber | Optional | 30 | Alphanumeric | This is an alternate ID used to identify this booking. |
| Description | Optional | 60 | Alphanumeric | Description of the booking |
| Amount | Mandatory | n/a | Numeric | Value to be paid for this reservation |
| DateBooked | Mandatory | 19 | String Date in format yyyy-MM-dd hh:mm | Date when the reservation was made. Note that this cannot be updated |
| DateExpired | Mandatory | 19 | String Date in format yyyy-MM-dd hh:mm | Date when the reservation will expire. Note that this cannot be updated |
| FirstName | Mandatory | 60 | Alphanumeric | Customer’s First name |
| LastName | Mandatory | 60 | Alphanumeric | Customer’s Last name |
| Mandatory | 40 | Alphanumeric | Customer’s Email address | |
| ItemCode | Mandatory | ANY | Alphanumeric | The unique code indicating the exact item linked to the reservation. Note that this cannot be updated |
Response Fields
| Field | Description |
| ResponseCode | See Appendix 1.0 |
| ReferenceNumber | Same sent in the request |