.png)
Introduction
The service uses a v2 authentication token and requires the token to be generated with the scopes recipients:write, recipients:read for adding/updating/getting recipient information, and for transfers the accounts:read, transfers:write scope is required in the body.
Consumers rely heavily on the ability to transfer money to pay bills and move funds between their own accounts or to those of family members. Facilitating the ability to move money is one of the most common and fundamental functions of a financial institution.
The Money Movement APIs provide the capability for account holders to perform transfers between accounts at their financial institution. It also allows users to create and manage external recipients (other account holders at the same financial institution) who can receive transfers. Two APIs support these tasks: the Recipient Service API and the Transfers API.
The Recipient Service API provides a method for creating and retrieving the following recipient records:
- Create Recipient
- Validate Recipient
- Update Recipient
- Delete Recipient
- Retrieve a list of Recipients
- Retrieve a single Recipient
The Transfers API makes money movement possible by offering a set of basic services used to do the following:
- Perform one-time transfers
- Schedule future transfers
- Execute scheduled transfers
These services can be used within accounts owned by one customer (including payments to IRA and loan accounts) as well as between different customer or member accounts.
What is Supported?
While the technical documentation in the Recipient Service API specs section describes all the endpoints (or ways to call the API with different parameters to execute different actions), the following provides asimplified list of use cases for the API.
Create recipient: Before a transfer can take place, a recipient record must be created and stored.
- Identify the recipient as a valid customer of the financial institution with the proper account for transfer.
- Identify the account to receive transfers
- Identify the recipient's email address and display nickname
- Input the recipient's passcode (needed to validate transfer execution) and display nickname.
- Validate the recipient (calls the Validate Recipient API)
Validate Recipient - Before a recipient record can be saved, the system must validate the data entered for the recipient record:
- Send the customer ID of the recipient
- Send the recipient's account number to receive transfers
- Send the recipient's account type
- Send the recipient's passcode
Update Recipient - When changes are needed for an existing recipient record:
- Send the customer ID of the recipient
- Send the recipient's account number to receive transfers
- Send the recipient's account type
- Send the recipient's passcode
Retrieve a List of Recipients - After one or more recipient records are created, the list can be retrieved:
- Commonly used in the context of creating a list of recipients to be selected during a transfer
- Retrieves all recipient records created by a given customer, along with their associated data
Retrieve a single Recipient - To view a recipient record or to select it for use in a transfer:
- Commonly used in the context of creating a list of recipients to be selected during a transfer.
- Retrieves all recipient records created by a given customer or member, along with their associated data.
Getting Started
Candescent’s APIs support financial institutions worldwide. They can empower financial institutions and their partners to build valuable digital banking experiences.
It’s important to work with your Candescent representative to get officially onboarded to DevX for access to these APIs. Once onboarded, you’ll be able to implement your application, access shared and secret keys and begin testing the APIs.
After all the legal and compliance partnership agreements are in place, we'll set you up with your Authentication API client account. This will grant you access to a unique secret key that will be your ticket to the authentication API and staging and production environments.
The service available through the Candescent Digital Banking Developer Portal provides a token for the grant type:
Client Credentials
- Used for trusted server-side applications
- Sending a request passes a key-and-secret pair assigned to your application
- Since the token is issued in the context of a Financial Institution (FI) rather than a user, no end-user login is required
- Response provides the Bearer Token to be used to call other DevEx APIs
Steps to getting started:
- Sign up and/or Login in for authentication
To make your first API request, you'll need toself-register by clicking the Sign Up button. Then, click the link in your welcomeemail to verify your emailaddress. - Review API documentation and request postman collections
Your Candescent representative will be able to email you the Postman collection for an API you are interested in. You may reach out directly or add the specific API to your favorites to alert your representative.
- Test APIs in Postman
In addition to the sample apps, a test drive environment is available to help you visualize the APIs. Using the JSONcollection and Postman, you’ll be able to see API requests working in action and view the information required to make them.
This will also allow you to experience actual API behavior prior to beginning your integration. For a deeper dive into Postman, view additional reference material here.
Authentication
Authentication proves that you are who you say you are. Authentication tokens identify a user (the person using the app or site).
You‘ll need the following items to set up basic authentication:
- Developer Experience account
- Sandbox environment with an organization
- Shared Key
- Secret Key
Generating your Secret Key
You’ll need a bearer token or an API security key to authenticate API calls. A secret key serves as a secure token to authenticate and authorize requests. Unauthorized use of a secret key could potentially cause a security breach. Thes ecret key holds the error token used to access real data through the API.
Visit our guide on authentication to learn more.
Before you begin, you‘ll require a unique client_id and client_secret for your app. Notify your implementation manager or PossibleNOW Support atsupport@possiblenow.com to request an OAuth client_id and client_secret. Include your My Preferences Client ID and the environment (staging (sandbox) or production) for which you want to generate the credentials in your request.
These credentials must be treated securely.
Use Cases & Examples
The end user wants to get the list of accounts from the bill pay system, or the user wants to get a specific account from the bill pay system.The user in this case is the customer of financial institution (FI).
Gets the accounts for the given institution customer
- Get list of accounts GET /db-accounts/v1/accounts
- Request -> Query Parameters:
hostUserId: The specific identifier for that customer - Headers:
Authorization: The bearer access token from the Authentication API
TransactionId: A UUID string used as unique identifier for this token request
Get the specified account for the given user
- Get the accounts GET /db-accounts/v1/accounts/{accountId}
- Request:
Headers:
Authorization: The access token from the Authentication APITransactionId: A UUID string used as unique identifier for this token request
