Divert Specification Guide
Introduction
Divert is a payment solution that allows merchants to request payment from their cardholders for services rendered. Traditionally, this functionality has only been available by accessing the merchant portal – Backoffice where merchants can populate the cardholder data and the payment amount agreed between the merchant and cardholder. On completion, a payment link via email would be distributed to the intended cardholder.
The API implementation carries the same functionality found in Backoffice, the aim of the API is to extend the existing functionality to a wider audience whose requirement may be to automate the process of generating the payment link from the Gateway thus giving control and flexibility to the merchant, making it possible for merchants to integrate the payment requests into their own website/mobile applications.
Use Cases
Adhoc: Rendering of services such as plumbing, electricians
Hospitality: Additional charges that may not be included in the customers reservation
Subscription/Recurring: Where customers may have missed a scheduled payment, merchants can use Divert to collect funds from the customer
DiVert API
Requirements
With the API, merchants are able to generate payment requests to their clients by implementing the “DebitRequest” command and include the specific data parameters that are expected in the message request to the Gateway. The data elements required in the “DebitRequest” command are covered in the Enterprise Documentation
In order to implement the DebitRuquest method, the following should be downloaded or in place.
- Reference the Divert Specification Guide
- Reference the using the “RequestDebit” method in the Enterprise Documentation
- Merchant Agreement with an acquirer with Divert as the solution which will result in a merchant profile on the Gateway
DiVert Functionality
The Divert API has a parameter “CreateTransactionUrl” that can be set to either “True or “False”. The value set determines how the Gateway handles and processes the message request.
Scenario 1
If CreateTransactionUrl” is set to“True” - the Gateway generates a transaction URL and makes a callback to the merchant with the URL.
The merchant can then construct and format their own message, including the URL (returned by the Gateway) and distribute the message to their cardholder using either SMS|Email
When the cardholder receives the messages, it will have all the particulars of the merchant, the cardholder can then click on the URL, and be redirected to a payment page wherein they can make a payment to the merchant
Scenario 2
If CreateTransactionUrl is set to “False” – the Gateway processes the request, packages the payment request and distributes into the cardholder’s specified email address on behalf of the merchant
When the cardholder receives the messages, it will have all the particulars of the merchant, the cardholder can then click on the URL and be redirected to a payment page wherein they can make a payment to the merchant
Divert - Payment Link Parameters
The below table parameters carry one the following definitions and descriptions can be referenced on https://www.iveri.co.za/slides/slide/parameter-description-559 and where API and their structure resides on https://www.iveri.co.za/slides/slide/rest-api-649
Mandatory | |
O | Optional |
C | Conditional |
blank | not relevant |
DiVert Parameter per Action
t | Parameter | RequestForDebit | RequestForAuthorisation |
Core | ApplicationID | M | M |
Core | Category | M | M |
Core | CertificateID | M | M |
Core | Gateway | O | O |
Core | Command | M | M |
Core | Mode | M | M |
Common | Amount | M | M |
Common | Currency | M | M |
Common | MerchantReference | M | M |
Common | CardholderName | M | M |
Common | CardholderEmail | C | C |
Common | OrderDescription | O | O |
Common | AllowBudgetPeriod | O | O |
Common | RequestExpiryDate | O | O |
Common | CreateTransactionUrl | O | O |
DiVert Sample Request/Response
REST |
REQUEST { "Version": "2.0", "CertificateID": "{c5fb89bb-d823-4204-8df8-c0485ac9e113}", "ProductType": "Enterprise", "ProductVersion": "WebAPI", "Direction": "Request", "Enquiry": { "ApplicationID": "{e879975b-df4a-4e13-8ed1-102579581827}", "Command": "RequestForDebit", "Mode": "Test", "MerchantReference": "20220226_1225", "Amount":"2000", "Currency":"ZAR", "OrderDescription":"Check1", "AllowBudgetPeriod":"False", "CardholderName":"Kersh", "ardholderEmail": "test@hotmail.com", "RequestExpiryDate": "20230201", "CreateTransactionUrl": "True" } }
RESPONSE { "Version": "2.0", "Direction": "Response", "Enquiry": { "MerchantReference": "20220226_1225", "TransactionUrl": "https://portal.nedsecure.co.za/DiVert/Authorise.aspx?RequestId=9F5DD3CA-5195-4957-A9E6-79FFF5E021BD&SecurityToken=OGlIUU5ETkNtOEZMTG9xcGhQTUNiNmxwUGVuRUtLRy9aWktXNEZHSmJRaz01", "ApplicationID": "{E879975B-DF4A-4E13-8ED1-102579581827}", "Command": "RequestForDebit", "Mode": "Test", "RequestID": "{3C35B9CF-ACC6-416D-8A1C-0EDB1D61B592}", "Result": { "Status": "0", "Code": "0", "Description": "", "AppServer": "105IVERIAPPPR2N", "DBServer": "105iveridbpr01n", "Gateway": "Nedbank" } } }
|
SOAP |
REQUEST <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Body> <Execute xmlns="http://iveri.com/"> <validateRequest>false</validateRequest> <protocol>V_XML</protocol> <protocolVersion>7.0</protocolVersion> <request><V_XML Version="2.0" CertificateID="3c993f-71dd-4044-802d-6e234effe8f2" ProductType="Enterprise" ProductVersion="iVeriWebService" Direction="Request"> <Enquiry ApplicationID="ec5729c-1d35-4208-86df-61c85cd447ae" Command="RequestForDebit" Mode="LIVE"> <Amount>3100</Amount> <Currency>ZAR</Currency> <MerchantReference>20290516.1241</MerchantReference> <OrderDescription>Bu:20260104.0922</OrderDescription> <AllowBudgetPeriod></AllowBudgetPeriod> <CardHolderName>TestUser</CardHolderName> <CardholderEmail>test@gmail.com</CardholderEmail> <RequestExpiryDate>2025025</RequestExpiryDate> <CreateTransactionUrl>True</CreateTransactionUrl> </Enquiry> </V_XML> </request> </Execute> </soapenv:Body> </soapenv:Envelope> RESPONSE <?xml version="1.0" encoding="utf-8"?><soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <ExecuteResponse xmlns="http://iveri.com/"> <ExecuteResult><V_XML Version="2.0" Direction="Response"> <Enquiry ApplicationID="{E157729C-1D35-4208-86DF-61C85CD447AE}" Command="RequestForDebit" Mode="Live" RequestID=" {0E248DED-3F9F-47EC-A13D-4513CD9F8CBE} "> <Result Status="0" Code="0" Description="" AppServer="QA2019GWAPP01" DBServer="QA2019GWDB02" Gateway="QA" /> <MerchantReference>20290516.1241</MerchantReference> </TransactionUrl >https://portal.iveri.net/DiVert/Authorise.aspx? RequestId=43BD2F43-52FB-4638-9588-C349CC106D85&amp;SecurityToken=cERub2NhOHVYTVV0YTVXMVRFdUpQOWNzbmpoREplR3RkeW4wc2VlWTVyOD01 </TransactionUrl> > </Enquiry></V_XML></ExecuteResult> </ExecuteResponse> </soap:Body></soap:Envelope> |
DiVert API Process Flow
Batch Upload File XML Specification
The Divert Batch Upload Data Elements
The Divert Batch XML upload file uses the following logic:
- The <Divert> element can occur multiple times
- The <DivertItem> element can occur multiple times under a <Divert> element
- The Application ID used in the <DivertItem> elements should be the same through-out the <Divert> element
Divert attributes
Tag Name | Length | Data Type | Format | Description |
Amount | <=12
| Numeric
|
| The sum of the Amount sub-element values of all the <DivertItem> sub-elements |
Count | <=6 | Number |
| The number of <DivertItem> sub-elements |
Divert sub-elements
Tag Name | Length | Data Type | Format | Description |
Date |
8 |
Numeric |
YYYYMMDD | The date when the batch was created (in which case the batch will be processed on the upload date) or a future date on which the batch should be processed (a past or future date cannot be more than 1 calendar month from the upload date)
|
Filename | <=64 | Text |
| The Filename by which the Divert batch can be identified (must be unique for all Divert batches uploaded for an ApplicationID)
|
CreateTransactionUrl |
| Boolean | True|False | Used to generate the URL to which a payment can be made by the cardholder. When this value is set to ‘true’ a ‘TransactionUrl’ will be returned to the merchant, the merchant can then distribute the payment requests with this URL using their preferred comms. If set to ‘false’ a debit request email will be sent by the gateway on behalf of the merchant to the ‘CardholderEmail’ |
DivertItem |
|
| XML element | An element for each transaction in the Divert Batch, this can occur multiple times within a <Divert>
|
DivertItem Attributes
Tag Name | Length | Data Type | Format | Description |
Application ID | 38 | GUID | {00000000-0000-0000-0000- 000000000000}
| The ApplicationID allocated generated by the gateway during merchant capture (the same ApplicationID must be used for all DivertItem elements under a Divert element)
|
Mode | 4 | Text | Test|Live | The mode of an ApplicationID |
Command | <=64 | Text | Debit|Authorisation|Credit| | The Transaction Type to be used |
DivertItem sub-elements
Tag Name | Length | Data Type | Format | Description |
Amount | <=12 | Numeric |
| The transaction value in cents ( no decimal point)
|
Currency | 3 | Alpha |
| The iSO currency code in which the transaction will be processed in ie. ZAR or USD |
OrderDescription | <=255 | Text |
| A description of the Divert Batch |
MerchantReference | <=64 |
|
| Unique merchant reference for this transaction. Must be unique for each DivertItem with Divert uploaded for an Application ID(normally this an Invoice Number) |
AllowBudgetPeriod |
| Boolean | True|False | The number of months over which the cardholder would like to pay the transaction off. |
CardholderName | <=50 |
|
|
|
CardholderEmail | <=128 | String |
| The cardholder email address which the merchant will send payment request to |
RequestExpiryDate | 8 | Numeric | YYYYMMDD | A future date which can be specified by the merchant on the validity period of the Divert payment request. If the date elapses and the request has not been processed by the cardholder the request will expire. |
DiVert Batch Result File
DiVert Batch Result File Data Elements
The result file data elements described in this section are returned to the merchant when the <CreateTransactionURL> in the “DivertUpload” file is set to “True”. Merchants can use the returned data elements to create and format their own payment request messages and send the requests to their cardholder using their own delivery method i.e. SMS|EMAIL
The Divert Batch has the following logic:
- The <Divert> element can occur multiple times
- The <DivertItem> element can occur multiple times under a <Divert> element
Divert Attributes
Tag Name | Length | Data Type | Format | Description |
Amount | <=12 | Numeric |
| The sum of the Amount sub-element values of all the <DivertItem> sub-elements
|
Count | <=6 | Number |
| The number of <DivertItem> sub-elements
|
Divert sub-elements
Tag Name | Length | Data Type | Format | Description |
Date | 8 | Numeric |
| The date when the batch was created (in which case the batch will be processed on the upload date) or a future date on which the batch should be processed (a past or future date cannot be more than 1 calendar month from the upload date)
|
File Name | <=64 | Text |
| The Filename by which the Divert batch can be identified (must be unique for all Divert batches uploaded for an ApplicationID)
|
CreateTransactionUrl | Boolean |
| True|False | Generated URL to which a payment can be made by the cardholder. |
DivertItem |
|
| XML element | An element for each transaction in the Divert Batch, this can occur multiple times within a <Divert>
|
DivetItem Attributes
Tag Name | Length | Data Type | Format | Description |
Application ID | 38 | GUID | {00000000-0000-0000-0000- 000000000000}
| The ApplicationID allocated generated by the gateway during merchant capture (the same ApplicationID must be used for all DivertItem elements under a Divert element) |
Mode | 4 | Text | Test|Live | The mode of an ApplicationID |
Command | <=64 | Text | Debit|Authorisation|Credit| etc. | The Transaction type used |
RequestID | 38 | GUID | {00000000-0000-0000-0000- 000000000000} | A unique identifier for the transaction allocated by iVeri |
DivertItem sub-elements
Tag Name | Length | Data Type | Format | Description |
TransactionURL | <=255 | Text |
| This will be returned to the merchant in the result file if the ‘CreateTransactionUrl’ parameter set to ‘True’
|
MerchantReference | <=64 | Text |
| Unique merchant reference for this transaction. Must be unique for each DivertItem with Divert uploaded for an Application ID(normally this an Invoice Number) |
DiVert Batch Upload Response Code
Error Description | Possible Reasons |
Not a valid payment request Batch file | Can occur due to the following reasons:
|
DiVertItem element Command attribute not valid | Check the Command file |
Invalid Date | Make sure date is provided and on the correct format |
User, Administrator, you have already uploaded a file, Teswa.XML, with applicationId, 8c4adb24-bda4-473b-af75-e4c4cd85ee05.
| File with the same name already uploaded |