Acquiring Use Cases

Overview

Eclipse has extensive payment processing capabilities and supports a multitude of options to acquire funds / payments into a tenant's ecosystem. These acquired payments can either be done as an individual sales organisation (ISO), where the tenant has a merchant account with a bank. Alternatively, Ukheshe can act as a super merchant for a tenant acquiring on behalf of that tenant.

Typically the acquiring options available to a tenant are the Eclipse payment processing capabilities described under Payment use cases - any payment option can be used by a tenant to collect money into a designated wallets. This includes but is not limited to:

Card Acquiring - e-Commerce card not present (CNP) payments including 3DS/AMT

• Payment type and use case: GLOBAL_WALLET

Card Acquiring - Google Pay

• Payment type and use case: GOOGLE_PAY

Card Acquiring - card present MPOS/Tap On Phone

• Payment type and use case: GLOBAL_TOG

Cash In at Retailer Acquiring - PicknPay

• Payment type and use case: ZA_PNP_CASH

Instant EFT Acquiring - Ozow

• Payment type and use case: ZA_OZOW

QR Acquiring - Masterpass Scan to Pay QR

• For full details refer to QR Acquiring - Masterpass Scan to Pay.

QR Acquiring - Scan to Pay Deep Linking

• On mobile devices this allows an application to invoke Scan To Pay supported applications (e.g. FNB, Nedbank, Capitec, Scan To Pay app) to complete a payment. For full details refer to Scan to Pay deep linking.

QR Acquiring - Mastercard QR (MCQR)

• For full details refer to QR Acquiring - MCQR.

QQ Acquiring - VisaQR

• Payment type and use case: GLOBAL_EMVCO

Payment links - the ability to easily distribute payment requests using any of the above payment options through flexible single use or reusable payment links.

• Payment type and use case: GLOBAL_PAYMENT_LINK
• Payment type and use case: GLOBAL_REUSABLE_PAYMENT_LINK

coming soon Samsung and Apple Pay

coming soon Visa and Mastercard Click to Pay

Hosted Checkout

Tenants can choose to integrate directly to the payment APIs above as an enterprise integration - this allows full control of the UIX. An alternative option for easier and quicker integration is to use Eclipse Hosted Checkout.

Eclipse hosted checkout allows a tenant to easily generate a URL with a single API call using payment links (either a single use payment link or a more flexible reusable payment link) and the returned URL can be rendered for the customer to complete their payment. This includes the full card journey in terms of capturing card details, completing 3DS, etc.

Eclipse Hosted Checkout supports all Eclipse payment types and these can be enabled at a tenant level by setting the paymentType parameter in the global property public.tenant.{tenantId} - allowed values are mastercard, ozow, pnpcash and eft.

A tenant should be configured for all the payment types allowed on the hosted tenant page. Refer to Payments Use Cases for the prerequisites for each payment type.

Eclipse hosted checkout supports customer branding in terms of logo's, colours, etc. For full details refer to Customisation of the Captive Portal UI.

Enterprise Integration

This section describes acquiring options for tenants that want to integrate directly to the payment APIs as an enterprise integration.

📘

Note

Additional enterprise integration options for acquiring mentioned in the acquiring overview section e.g. Cash in at retailer acquiring, Instant EFT acquiring are all covered under Payment use cases.

Card Acquiring - E-commerce

Eclipse can be used to enable e-commerce for tenants who want to securely store tokenised card on file and process card not present (CNP) card payments including 3DS.

A typical use case would be an e-commerce retailer who wants to enable card payments through their existing customer channels. Eclipse APIs can be used to:

1. To store and retrieve tokenised customer card on file details - refer to Card On File Management for full details.
2. Initiate card payments using the card on file, through card rails with settlement to the designated merchant - refer to GLOBAL_WALLET payments for full details.

QR Acquiring - Masterpass Scan to Pay QR

Masterpass Scan to Pay QR Acquiring enables tenants in South Africa to securely generate Masterpass QR codes that are linked to an Eclipse wallet. Any Masterpass Scan to Pay supporting application can scan and pay these QR codes and the funds will be settled into the relevant Eclipse wallet.

Prerequisites

• Eclipse digital wallet created
• For merchant acquiring the created wallet should either be a tenant wallet (if the tenant is the acquiring merchant) or an organisation wallet (where the organisation is the acquiring merchant)
• For merchant acquiring the merchant category code needs to be specified on the tenant if the tenant is the acquiring merchant or on the organisation if the organisation is the acquiring merchant. (Refer to MCC List for MCC codes)
• The tenant must be signed up as a Masterpass merchant
• The masterpass merchant setup must settle to the Nedbank acquiring pool account
• API access must be enabled in the masterpass portal
• Tenant config masterpass.config.aesKey must be set to the notification key.
• Tenant config masterpass.config.apiUser and masterpass.config.apiPassword must be set to the masterpass API
• credentials for the merchant
• The masterpass notification URL must be set to https://ukheshe.live/eclipse-conductor/rest/v1/masterpass/incoming-payments?configId=XXX where XXX is the tenantId

Step 1 - Generate a QR Code

Tenants can generate a QR Code and link it to a specific wallet. An already created QR Code can be provided and linked to the wallet or a QR code can be generated as part of this API call. QR codes can also be generated for a specific amount and explicit expiry date if values are passed for amount and expires parameters. If these parameters are omitted the QR code will never expire and the amount will need to be provided then the payer would enter the amount upon payment.

QR codes are generated using the Create QR Endpoint:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/qr-codes
{
  "merchantName": "Johns Bakery",
  "type": "ZA_MASTERPASS",
  "description": "QR Code for Johns Bakery",
  "reference": "Ext-1234567"
}

Example response body:

{
  "walletId": 36714,
  "type": "ZA_MASTERPASS",
  "code": "2997973598",
  "currency": "ZAR",
  "reference": "Ext-1234567",
  "merchantName": "Johns Bakery",
  "description": "QR Code for Johns Bakery",
  "additionalFields": []
}

This QR Code can now be displayed or distributed through whatever means the channel intended and any Masterpass Scan to Pay supporting application can scan and pay the QR code and the funds will be settled into the wallet mapped to the QR code.

There are also endpoints to bulk create QR codes, update QR codes and bulk update QR codes.

QR Acquiring - MCQR

Mastercard QR (MCQR) enables tenants to generate MCQR codes that are linked to an Eclipse wallet. MCQR uses the concept of a receive only PAN as the destination of the payments. This means that a card needs to be issued and associated to the destination Eclipse wallet that must be created with mode receiveonlycard. MCQR is available in any region where MCQR is enabled.

Prerequisites

• Card issuing program created for receive only cards

• Eclipse wallet created with mode receiveonlycard

• Tenant config mcqr.config.partnerId must be set to the notification key.

• Any app generating MCQR codes must be certified by Mastercard

  Step 1 - Generate a QR Code

Tenants can generate a QR Code and link it to a specific wallet. An already created QR Code can be provided and linked to the wallet or a QR code can be generated as part of this API call. QR codes can also be generated for a specific amount and explicit expiry date if values are passed for amount and expires parameters. If these parameters are omitted the QR code will never expire and the amount will need to be provided then the payer would enter the amount upon payment.

QR codes are generated using the Create QR Endpoint:

This QR Code can now be displayed or distributed through whatever means the channel intended and any MCQR supporting application can scan and pay the QR code and the funds will be settled into the wallet that is associated to the receive only PAN.

Card Acquiring - card present MPOS/Tap On Phone

Card Acquiring - card present MPOS/Tap on Phone - Kernel in the Cloud (KiC) Visa Acceptance Cloud (VAC)

Visa Cloud Acceptance (VAC), also know as Kernel in the Cloud (KiC), enables contactless payments on any Android device or phone (Android OS 12 and newer) provided they are NFC-enabled without any additional hardware. VAC is EMV L2 certified.

This is available as an SDK for App integration described below. Alternatively Ukheshe provides the option of using a companion app to manage the Tap On Phone payment process. This requires simpler integration than integrating to the VAC SDK and also means that future verifications and lab testing will not be needed for Tap On Phone on the tenant app as this will be covered by the companion app. For more details please refer to the Tap on Phone Integration Guide.

Benefits of VAC

• Simplified L2 certification requirements resulting in faster time to market
• Low integration cost
• Transforms any connected device into a POS, enabling new payment flows and experiences
• Enabler for integrated value-added services

Device Requirements

• Android OS version should be 12 or higher
• Google Play service-supported device
• Should have the NFC capabilities
• Should have Hardware keystore (ELIGIBILITY_HARDWARE_KEYSTORE_PRESENT)

End-to-end VAC Process

The steps below demonstrate the actions from pre-transaction initiation to the updates needed upon success or failure response. The VAC SDK documentation should be requested for the Visa Developer Portal.

VAC Prerequisites

• Create a JWT
• Create an Organisation
• Create a new Wallet for the Organisation
• If you are using the VAC SDK directly in a new application and not using the Ukheshe companion app - your application must be registered with Visa on sandbox and production including app package name, acquiring bank and Visa project application ID. Contact [email protected]eftcorp.com to have an application registered to Visa for sandbox and production for your applications.

Required tenant configuration:

• For full set of required tenant configs refer to VAC/KiC Tenant Setup
• fees.amount.config.Pay.GLOBAL_TOG_VAC.CARD.SERVER=0.1P | Fees amount
• fees.wallet.config.Pay.GLOBAL_TOG_VAC.CARD.SERVER={WalletID} | Wallet ID to credit for fees
• source.wallet.config.GLOBAL_TOG_VAC.CARD.SERVER={WalletID} | Wallet ID to debit when a customer receives funds

Enabling mPOS

Step 1: Create a Terminal Type

For each tenant a kernel profile must be registered with Visa and made available as a terminal type to the tenant in order for terminals to be created and assigned to organisations. This is a backoffice task. The following screenshot show a terminal mapping created and mapped to tenant id: 7719:

** Attribute allowMultipleInstance will allow for multiple Terminal Instances to be created using this Terminal Type

📘

Note

Typically a single, default terminal type is created and used in a tenant for all instances. However different terminal types can be created with custom settings for accepted cards, floor limits, refunds, etc. and then applied to specific users and wallets.

Only 1 device can be registered at a time per Terminal

Step 2: Create a New Store against the Organisation

A store in VAC terms represents a shop or store. Typically when implementing in a Eclipse 1 store is created per organisation.

Below is an example request:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/stores

{
  "name": "R&P VAC Store",
  "city": "Cape Town",
  "country": "South Africa",
  "line1": "54 Forest Street",
  "state": "Western Cape"
}

Below is an example response:

{
    "storeId": 9,
    "name": "R&G VAC Store",
    "created": "2023-06-20T10:49:21.000Z",
    "lastModified": "2023-06-20T10:49:21.000Z",
    "city": "Cape Town",
    "state": "Western Cape",
    "line1": "54 Forest Street",
    "country": "South Africa",
    "version": 0,
    "mappings": [
        {
            "identifierType": "VAC",
            "identifier": "877fda01-7bf3-9ad9-188b-12f24535bb01"
        }
    ]
}

Step 3: Add a New Terminal against the Organisation

A terminal in VAC terms represents an actual device to accept payments. In most implementations a single terminal type is created for the tenant, and a single terminal is created per organisation. However if multiple terminal types exist then multiple terminals can be created on an organisation. These terminals can use different terminal types and can be configured to be locked to a particular user or wallet e.g. you only want a particular user to be able to use the terminal that can process refunds.

Below is an example request to create a terminal:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/terminals

{
  "name": "R&P VAC Terminal",
  "storeId": "{{storeId}}",
  "terminalTypeId": "{{terminalTypeId}}",
  "status": "ACTIVE"
}

Below is an example response:

{
    "terminalId": 10,
    "terminalTypeId": 9,
    "storeId": 9,
    "name": "R&P VAC Terminal",
    "status": "ACTIVE",
    "created": "2023-06-20T10:50:41.000Z",
    "lastModified": "2023-06-20T10:50:41.000Z",
    "configuration": [],
    "version": 0,
    "mappings": []
}

Once the above is complete, VAC integrations will be initiated as per the Visa requirements.

📘

Note

Stores and terminals can be viewed, added and deleted in the admin portal in the Terminals tab under an Organisation:

Step 4: Link calling user to organisation

The user completing the API calls in the subsequent steps needs to be a member of the organisation against which the store and terminals have been added.

Typically the API calls are done as the customer, and the customer is added as a member of the organisation. However tenants using a tenant system user to access Eclipse on behalf of customers would need to add a User with LEVEL_10 permissions and link that user as a member of all the organisations for which Tap On Phone payments will be initiated. This LEVEL_10 user should be used for all Tap On Phone payments.

Below is an example request to add a user to an organisation using APIs:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/positions

{
  "position": "MEMBER",
  "organisationId": 12583
}

Below is an example response:

{
  "organisationId": 12583,
  "position": "MEMBER"
}

User can be added to an Organisation using the Admin Portal by navigating to the customer then positions:

Step 5: Initiate Tap on Phone Payment

The below are prerequisites:

• Tracing must be implemented. If this is not done, debugging functionality will be disabled
• Check the version of the application to force upgrades
• CheckVacEligibility. This will check if this device can run VAC

Below is an example request for initiating a payment:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/payments

{
  "destinationWalletId": "{{walletId}}",
  "type": "GLOBAL_TOG",
  "amount": 510,
  "currency": "ZAR",
  "externalUniqueId": "{{$guid}}"
}

Below is an example response for initiating a payment:

"paymentId": 54202,
    "externalUniqueId": "42ef7499-f42a-47a8-a8f1-6393d1953bd3",
    "status": "PENDING",
    "amount": 510.000000000,
    "merchantName": "R&G VAC Test Org",
    "currency": "ZAR",
    "destinationWalletId": 247424",
    "acceptedCardSchemes": [],
    "acceptedPaymentMechanisms": [],
    "completionUrl": "eclipse://payment.service/tap?paymentId=54202&eclipseJwt="xxxx"",
    "paymentType": "CARD",
    "created": "2023-06-20T11:15:03.000Z",
    "paymentInstrumentInfo": {},
    "fee": 0,
    "walletId": 196955,
    "customerId": 1126

Step 6: Enroll the Device

If a device is NOT enrolled, the following must be done:

GET /eclipse-conductor/rest/v1/global/config/public.jwt.protected.visa.vac.sdk.setup

Initiate the SDK with the data from the above request. This will return device certificates which must be used to create a terminal as per the below request:

POST: https://eclipse-java-sandbox.ukheshe.rocks/eclipse-conductor/rest/v1/tenants/{{tenantId}}/terminals/enrollments

{
    "deviceCerts": [
        "xxx",
        "xxx",
        "xxx",
        "xxx"
      ],
  "deviceInfo": {
        "osType": "Android",
        "model": "SM-G973F",
        "manufacturer": "samsung"
    }
}

Enrolled device example response. The response is data passed to the SDK to instruct it to enroll the new device.

{
    "deviceId": "a8fd57fd-52c1-f2c8-4e9e-1f12c0477101",
    "deviceAuthPubKid": "4e1708ac-c8e3-45b8-a9a9-f49f64ba0d50",
    "xviaHint": "xxx"
}

📘

Note

• Enrolling a device must only be done per app install. Save the enrolled device details in a local storage to avoid re-enrolling.
• The call to enroll a device must be done from a user that is linked to the organisation against which the terminals have been added

Step 7: Invoke Visa SDK to initiate transaction

• Start up the SDK (refer to the Visa documentation) - this checks whether the SDK is satisfied with your phone
• Make a payment by calling startTransaction (refer to the Visa documentation)
• Update Eclipse on SUCCESS or FAILURE of payment

Step 8: Update Eclipse on SUCCESSFUL or UNSUCCESSFUL payment

Below is an example request:

PUT /eclipse-conductor/rest/v1/tog/payments/{paymentId}
{
  "cardName": "xxxx",
  "cardLast4": "xxxx",
  "authCode": "xxxx",
  "reference": "xxxx",
  "status": "SUCCESSFUL",
  "transactionDate": "2018-05-11T13:35:11Z"
}

Below is an example response:

{
    "paymentId": 54203,
    "amount": 510.000000000,
    "fee": 0E-9,
    "currency": "ZAR",
    "unattended": false,
    "uniqueId": "096f1ac7-7f55-4151-8ef1-62a9128c279f",
    "tenantId": 8,
    "status": "FINAL",
    "userId": 1126,
    "walletId": 196955,
    "paymentType": "CARD",
    "paymentSubType": "SERVER",
    "gatewayStatus": "SUCCESSFUL",
    "gateway": "GLOBAL_TOG_VAC",
    "preProcessingCallbackIds": [],
    "postProcessingCallbackIds": [],
    "postSuccessCallbackIds": [],
    "postReversalCallbackIds": [],
    "completionUrl": "eclipse://payment.service/tap?paymentId=54203&eclipseJwt=eyJraWQiOiIxIiwiYWxnIjoiUFMyNTYifQ.eyJzdWIiOiJoYWxvdHN0Iiwic3JjIjoiQXV0aC1QIiwiY2giOiIrc2tLTk5qV0hpIiwicm9sZXMiOiIiLCJzZXNzIjoiZTIyODdlZTAtODIyZC00MTkzLTgxMmMtYTE5Mjc2NDg0NDJhIiwiaXAiOiI1NC44Ni41MC4xMzkiLCJpc3MiOiJodHRwOi8vZWNsaXBzZS1qYXZhLXNhbmRib3gudWtoZXNoZS5yb2NrcyIsImxvY2FsZSI6ImVuLVVTIiwidWlkIjoxMTI2LCJwb3MiOlt7Im8iOjgwLCJkIjowLCJwIjoiRU1QTE9ZRUUifV0sImV4cCI6MTY4NzI2MzQ2OCwiaWF0IjoxNjg3MjYyNTY4LCJ0ZW5hbnQiOjh9.KzLKh2dzevM2siNtfY5oYWAUrU-g32-d08NrEYdi4wkNXVaOtMblrh60lGOoz_br195v_WwClGhGVNayTrls-IzJxdWAIWnmsi3mOI9yM4d6dQIoCWAgiQ-Yho2Sq59L6KT97Q1-eqd01HYxqPsyEyyPtD_iPadht5BHPO1hHpFQiTyqP2r5_fATjfILWLouQ-X09nLomQcq2fe0hydqKunINu9UC3mlbZHB0deERJbEYqJKSkX6l5q4a9qG-GtHz5S_c55yC-mDYztJF3IBVsRDZMe371jNu4PjKw29HNpMNPVE3uOO4WPJRAd0xuwo-eiTlkMLCgPVyVL3Uu0PUw",
    "created": "2023-06-20T12:02:55.000Z",
    "lastPolled": "2018-05-11T13:35:11.000Z",
    "authCode": "1234",
    "createCardOnFile": false,
    "useCardOnFileIfAvailable": false,
    "additionalFields": [
        {
            "id": "merchantWalletId",
            "value": "196955"
        }
    ],
    "paymentReference": "xxxx",
    "cardLast4": "xxxx",
    "cardName": "xxxx",
    "merchantName": "R&G VAC Test Org",
    "acceptedCardSchemes": [],
    "acceptedPaymentMechanisms": [],
    "customFraudChecks": false
}

Flow of funds

To create a reservation in the credited wallet, until the funds are cleared in the tenant pool account, it is essential to configure the following property in the Tenant Configuration. This will be set by Ukheshe administrators

Card & Scan to Pay Flow of Funds

Pick 'n Pay Flow of Funds

OZOW Flow of Funds