Implementation

This simple flow diagram illustrates how the logic should work when implementing the Eclipse Payment Service from a mobile app.

The overall sequence of the transactional flow is as follows:

Payment needs to be created to initiate the tap-on-phone transaction. The purpose of this API call is to get a signed payload that will be passed to the Eclipse Payment Service. This is of payment type GLOBAL_TOG.

API Summary

POST /eclipse-conductor/rest/v1/tenants/<tenant ID>/payments
{
	"amount": 150,
	"currency": "ZAR",
	"externalUniqueId": "tenant external ID or reference",
	"type": "GLOBAL_TOG",
	"additionalFields": [{
		"id": "merchantWalletId",
		"value": "destination wallet id"
	}]
}

See the Eclipse Integration Guide or Eclipse swagger for more information.

A signed payload is returned by Eclipse that will be passed to the Eclipse Payment Service. The parameter returned is completionUrl which needs to be used to invoke the EPS app. This completion URL contains a specially crafted URL with a custom schema and the required payload.
Your backend needs to provide your app with this completion URL.
Your Android app needs to invoke this completion Url. It is at this point where you can apply styling- please see the styling section.

Sample Invocation

try {
       Intent intent = new Intent(Intent.ACTION_VIEW); 
       intent.setData(Uri.parse(completionUrl));
       startActivityForResult(intent, 2);
} catch (ActivityNotFoundException e) {
       redirectToAppStore();
}

Eclipse Payment Service app will handle the tap transaction and process the financial messages to the acquirer.
The Eclipse Payment Service will respond to the calling app using the onActivityResult mechanism within Android. The response has the following parameters:

Parameter	Description
errorCode	This is a result code for information purposes. This should be stored, however, the REAL status of the payment should be retrieved in step 8.
traceId	This is used for debugging. whenever a support request is raised, this trace ID needs to be provided.
paymentId	This is the payment ID for the payment. This is used to retrieve the status of the payment in step 8

Your backend service needs to verify the payment status. The only way to ensure this is by executing an API to Eclipse to retrieve the payment status.

Sample Request

GET /eclipse-conductor/rest/v1/tenants/<tenant id>/payments/<payment id>

Eclipse also supports webhooks to notify your backend of a payment. Please see the Eclipse Integration guide for more information.