DiVert Developer Guide

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>&lt;V_XML Version="2.0" CertificateID="3c993f-71dd-4044-802d-6e234effe8f2" ProductType="Enterprise"

ProductVersion="iVeriWebService" Direction="Request"&gt;

&lt;Enquiry ApplicationID="ec5729c-1d35-4208-86df-61c85cd447ae" Command="RequestForDebit" Mode="LIVE"&gt;

&lt;Amount&gt;3100&lt;/Amount&gt;

&lt;Currency&gt;ZAR&lt;/Currency&gt;

&lt;MerchantReference&gt;20290516.1241&lt;/MerchantReference&gt;

&lt;OrderDescription&gt;Bu:20260104.0922&lt;/OrderDescription&gt;

&lt;AllowBudgetPeriod&gt;&lt;/AllowBudgetPeriod&gt;

&lt;CardHolderName&gt;TestUser&lt;/CardHolderName&gt;

&lt;CardholderEmail&gt;test@gmail.com&lt;/CardholderEmail&gt;

&lt;RequestExpiryDate&gt;2025025&lt;/RequestExpiryDate&gt;

&lt;CreateTransactionUrl&gt;True&lt;/CreateTransactionUrl&gt;

&lt;/Enquiry&gt;

&lt;/V_XML&gt;

</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>&lt;V_XML Version="2.0" Direction="Response"&gt;  &lt;Enquiry ApplicationID="{E157729C-1D35-4208-86DF-61C85CD447AE}" Command="RequestForDebit" Mode="Live" RequestID=" {0E248DED-3F9F-47EC-A13D-4513CD9F8CBE} "&gt;    &lt;Result Status="0" Code="0" Description="" AppServer="QA2019GWAPP01" DBServer="QA2019GWDB02" Gateway="QA" 

/&gt; &lt;MerchantReference&gt;20290516.1241&lt;/MerchantReference&gt; &lt;/TransactionUrl &gt;https://portal.iveri.net/DiVert/Authorise.aspx?

RequestId=43BD2F43-52FB-4638-9588-C349CC106D85&amp;amp;SecurityToken=cERub2NhOHVYTVV0YTVXMVRFdUpQOWNzbmpoREplR3RkeW4wc2VlWTVyOD01

&lt;/TransactionUrl&gt; &gt;  &lt;/Enquiry&gt;&lt;/V_XML&gt;</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: 

  • Incorrect File format Type
  • VXML tags that may be opened but not closed or Vice Versa

 

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