Fondy API Jar

Description

The Jar is designed to allow quick and simple integration into the Fondy platform.
It does the same actions/functions as the Encrypted API (it in fact uses the API).
It just wraps all the calls, logic, payload builds into a single "call" that you make.
The Jar has been designed to be as simple as possible to use, and, as noted
provides the appearance that the Fondy Service is "in the same JVM" as your code.

It can be wrapped into a Springboot stack, with a simple controller that returns
the information. This MUST BE 100% internal to your systems.

High level overview

The flow of the Jar and your code is as follows

DIAGRAM HERE PLEASE

Getting the Jar

Please contact Fondy Support to obtain the latest version of the Jar

Services

There are multiple API services available, each correspond to the API docs
of the same/similar name. There are:

FondyIdentityServiceAPI (identity records)
FondyComplianceServiceAPI (compliance profiles )
FondyCoreBankingServiceAPI (account, payments, transactions etc..)
FondySplitAccountServiceAPI (for the split accounts)

Key management

There are two options that you an use:

implement your own FondyClientCryptoKeyProviderInterface which returns the keys correctly
use the DefaultFondyClientCryptoKeyProvider which takes in the pub/private key as strings

Implementation of the FondyClientCryptoKeyProviderInterface abstract class

This has two methods that require you to implement


    public abstract PublicKey getFondyProvidedPublicKey();

    public abstract PrivateKey getMyPrivateKey();

These provide the keys to sign, encrypted, and decrypt the objects.
The implementation of where they come from, is for you to provide as fondy does not
want to enforce controls on your private/public key management.

Default Crypto

This is a simple to use one, that takes the keys (your private, Fondy's public) as strings
and builds the logic to return the Public and Private Key (it implements the interface above)

public class ExampleDefaultCrypto {

    //DI etc.. these key values
    private static String yourPrivateKey;
    private static String fondyPublicKey;
    /**
     * Where you store the pub/private keys are up to you, call this method with the keys to create the
     * CryptoKey Interface to encode/decode messages. This is an example how to do it, it can be anywhere
     * in the code.
     */
    public static final FondyClientCryptoKeyProviderInterface createDefaultKeyCrypto() throws Exception {
        return new DefaultFondyClientCryptoKeyProvider(yourPrivateKey, fondyPublicKey);
    }
}

Development APIs

For the development areas (example sandbox), then there is base 64 encoder to
allow messages to go through the system, however be encoded in a manner that allows
for easier debugging.

To undertake this, the URL called will be different, and this is for NON production
services only.

FondyCustomerException

This is a standard error object, if there is an issue with interactions with the stacks,
and is the error that all the APIs listed below will/can throw.

Note: The errors can be local to your machine in the Jar (example null values), or
from the Fondy Servers.

Format

The format is the same as the one in the APIs if called directly:

Error{
   "code": HTTP Code
   "message": What the error was/something useful as to why the action failed
   "reference": a UUID so logs can be checked for what caused this (if needed)
}

And the data can be accessed by

        Error error =fondyException.getError();
        error.getCode();
        error.getMessage();
        error.getReference();
        
        //if server side error the the following check works.
        fondy.isServerSideError() //returns true
        //if the above is false, then the issue is (most likely) data being sent into API

Creating API Services

To create the API the blow is the code (example) for creation. Each are created with
different data where applicable.

Core Banking API Service

public class ExampleCoreBankingCode {

    private FondyCoreBankingServiceAPI service;

    /**
     * Create the banking API Interface, using the key provide, the customerID (provided by Fondy),
     * the email of the user accessing the system (agreed with Fondy/client), URL of the Fondy service
     * (provided by Fondy)
     */
    public ExampleCoreBankingCode(String uRLOfFondyServer,
                                  UUID yourCustomerID,
                                  String emailOfUserAccessing){
        FondyClientCryptoKeyProviderInterface keyhandler = ExampleDefaultCrypto.createDefaultKeyCrypto();
        service=  FondyCoreBankingServiceAPI.getInstance(yourCustomerID, emailOfUserAccessing, uRLOfFondyServer, keyhandler);
    }


    public Account getAccountById(UUID accountID)throws FondyCustomerException {
        return service.getAccount(accountID);
    }

    public Payment getPaymentById(UUID accountID, UUID paymentId)throws FondyCustomerException {
        return service.getPaymentById(accountID,paymentId);
    }

    public List<Account> getAllAccounts()throws FondyCustomerException{
        return service.getAccounts();
    }

    public List<Transaction> getAllAccounts(UID accountID)throws FondyCustomerException{
        return service.getTransactions(accountID);;
    }

    /**
     * This method defaults to Faster payment, use if using UK FPS Scheme
     */
    public Payment createFasterPayment(UUID accountId, Payment payment) throws FondyCustomerException{
        return service.createFasterPayment(accountId,payment);
    }

    /**
     * This allows you to set the scheme of payment (example Chaps if allowed for you) etc..
     */
    public Payment createPayment(UUID accountId, Payment payment) throws FondyCustomerException{
        return service.createPayment(accountId,payment);
    }

}

Compliance Profile API Service


public class ExampleCompliance {

    private FondyIdentityServiceAPI service;

    /**
     * Create the banking API Interface, using the key provide, the customerID (provided by Fondy),
     * the email of the user accessing the system (agreed with Fondy/client), URL of the Fondy service
     * (provided by Fondy)
     */
    public ExampleCoreBankingCode(String uRLOfFondyServer,
                                  UUID yourCustomerID,
                                  String emailOfUserAccessing){
        FondyClientCryptoKeyProviderInterface keyhandler = ExampleDefaultCrypto.createDefaultKeyCrypto();
        service = FondyIdentityServiceAPI.getInstance(yourCustomerID, emailOfUserAccessing, uRLOfFondyServer, keyhandler);
    }


    public ComplianceProfile getComplianceProfile(UUID profileId)throws FondyCustomerException {
        return service.getComplianceProfile(accountID);
    }

    public ComplianceProfile createComplianceProfile(ComplianceProfile profile)throws FondyCustomerException {
        return service.createComplianceProfile(accountID,paymentId);
    }

    public List<ComplianceProfile> getAllComplianceProfile()throws FondyCustomerException{
        return service.getAllComplianceProfile();
    }
}

Split Account API Service


public class ExampleClass {
    private FondySplitAccountServiceAPI splitAccountService;
    // all of the these values will be provided by fondy
    private String FONDY_SERVER_URL;
    // API Username -> this is agreed with fondy
    private String API_USERNAME;
    private UUID CUSTOMER_REFERENCE_FROM_FONDY;
    private UUID SPLITACCOUNT_REFERENCE;
    private UUID DEFAULT_SPLITACCOUNT_WALLET;

    /**
     * NOTE here - there are two URLs to use
     *  -> Dev/Test Environments
     *      -> can be ..../v1/... or .../example/.... or /mocked/...
     *  -> Prod and Pre-prod
     *      -> only ..../v1/... 
     *  The "example" one does Base64 encryption -> it is not supported on PROD/PreProd
     *  The "example" only requires a "null" implementation
     *  The "mocked" one returns some data for the APIs -> this is not to be relied on,
     *  nor fully supported
     */
    private MyFondyClientCryptoKeyProviderInterface keyhandler = ExampleDefaultCrypto.createDefaultKeyCrypto();
    ;
    //getters/setters for the above values 

    public ExampleClass {
        splitAccountService = FondySplitAccountServiceAPI
                .getInstance(CUSTOMER_REFERENCE_FROM_FONDY,
                        API_USERNAME,
                        FONDY_SERVER_URL,
                        SPLITACCOUNT_REFERENCE,
                        keyhandler);
    }

    public SplitAccountWallet createAWallet(Identity idReturned) throws FondyCustomerException{
        SplitAccountWallet wallet = new SplitAccountWallet();
        //set the values
        // wallet.set... etc..
        //set the id reference on the wallet
        wallet.setIdentityId(idReturned.getId());
        wallet.setDefaultWalletId(DEFAULT_SPLITACCOUNT_WALLET);

        SplitAccountWallet walletReturned = splitAccountService.createWallet(wallet);

        return walletReturned;
    }

    /**
     * Note this can be combined with the other create... etc..
     * Split out to show the steps
     * Some steps are missing (e.g. creating the data for amount etc..)
     * the "..." are the values to the buildAPayment method
     */
    public SplitAccountPayment  createATransfer(SplitAccountWallet wallet) throws FondyCustomerException{
        SplitAccountPayment  transfer = buildAPayment(SplitAccountPaymentType.TRANSFER,...);
        //set the values
        // transfer.set... etc..
        // and then
        transfer.setFromWalletId(wallet.getDefaultWalletId());
        transfer.setToWalletId(wallet.getId());

        // this is "from this wallet do this payment"
        SplitAccountPayment  rtn = splitAccountService.createPayment(wallet.getDefaultWalletId(),transfer);

        return rtn;
    }

    /**
     * Note this can be combined with the other create... etc..
     * Split out to show the steps
     * Some steps are missing (e.g. creating the data for amount etc..)
     * the "..." are the values to the buildAPayment method
     */
    public SplitAccountPayment  createAReversal(SplitAccountWallet wallet) throws FondyCustomerException{
        SplitAccountPayment  reversal = buildAPayment(SplitAccountPaymentType.REVERSAL,...);
            //set the values
        // transfer.set... etc..
        // and then
        reversal.setFromWalletId(wallet.getId());
        reversal.setToWalletId(wallet.getDefaultWalletId());

        // this is "from this wallet do this payment"
        SplitAccountPayment  rtn = splitAccountService.createPayment(wallet.getId(),reversal);

        return rtn;
    }

    /**
     * Note this can be combined with the other create... etc..
     * Split out to show the steps
     * Some steps are missing (e.g. creating the data for amount etc..)
     * the "..." are the values to the buildAPayment method
     */
    public SplitAccountPayment  createAPayout(SplitAccountWallet wallet....) throws FondyCustomerException{
        SplitAccountPayment  payout = buildAPayment(SplitAccountPaymentType.PAYOUT,...);
        //set the values
        // payout.set... etc..
        // and then
        payout.setFromWalletId(wallet.getId());

        // this is "from this wallet do this payment"
        SplitAccountPayment  rtn = splitAccountService.createPayment(wallet.getId(),payout);

        return rtn;
    }

    /**
     * example common method to build a payment
     */
    public static SplitAccountPayment  buildAPayment(SplitAccountPaymentType type, 
                                                   int amount,
                                                   String myReference,
                                                   String additionalInfo){
        SplitAccountPayment  payment = new SplitAccountPayment ();
        payment.setType(type);
        RequestedAmount amount = new RequestedAmount();
        amount.setCurrency("GBP");
        // ONLY GBP SUPPORTED IN THE CURRENT VERSION
        amount.setAmount(BigInteger.valueOf(amountInt));
        payment.setAmount(amount);
        payment.setExternalId(myReference);
        payment.setAdditionalInfo(additionalInfo);
        return payment;
    }

    /**
     *  below is an example of getting by ID, the same is for all get by id
     */
    public SplitAccountPayment  getPayment(UUID fromThisWallet, UUID thisPaymentRef){
        return splitAccountService.getPayment(fromThisWallet,thisPaymentRef);
    }

}