This page provides an overview on how to get started with the Payments API integration.
It is aimed at developers who need to understand the features and functions of API and integration steps.
Resources
EBPP Basics
Learn more about our platform to build a foundation for your API integration with us.
Client Key
EBPP assigns a unique identifier called “Client Key” to each API client. This key is used to identify and authenticate the API requests. Clients who sign for our API will be provided with separate Client Keys for Sandbox and Production environments.
The correct Client Key that represents the appropriate entity and environment must be sent with each API request.
Channel
Each EBPP client is configured for one or more Channels. Channel is a logical route by which an end user of EBPP — customer, agent, or any other type of user accesses the EBPP functionalities.
EBPP has a set of Channels that share core functions. Access to functions and features are controlled by configurations enabled for the Channel. Available options may vary, and each Channel may have its own unique set of configurations.
Select Channel(s) with the functions that you want to make available to your end users. Either standard EBPP name or custom name can be used. If a custom name is used, the value of the custom name needs to be shared with Alacriti Team as part of the onboarding process.
The correct Channel name must be sent with each API request.
Payment Type
Each Channel is configured with one or more Payment Types that defines processing cycle.
There are two groups: single (One Time) and repeating.
The repeating type requires an enrollment that confirms the end user is enrolled to have a series of payments generated. Child payments will be created per parameters associated with the enrollment as part of the cycle.
Sending a request to schedule a repeating payment is invalid.
The following repeating types are available:
- Recurring: Series of payments where the date, frequency, duration and amount is selected by the end user. Recurring enrollment creates Recurring Payments.
- AutoPay: Series of payments where the date, frequency, duration and amount is driven by billing data. AutoPay enrollment creates AutoPay Payments.
- Payment Plan: Series of monthly payments to pay off a fixed amount that is owed. Payment Plan enrollment creates Payment Plan payments.
Only the Payment Type options enabled for the Channel must be sent with applicable API requests.
Funding Account
Funding Accounts that can be used for each Payment Type enabled in each Channel are then configured. Currently, ACH and Card are supported.
Additionally, Auxiliary API can be opted for Cash payments that do not require fulfillment. Payments processed in external systems can be recorded in EBPP.
Only the correct Funding Accounts enabled for the Channel must be sent with Funding Account and Payment related API requests.
Payment Amount Type
One or more Payment Amount Types are defined for each Payment Type enabled within each Channel. There are two types: predefined and undefined.
For the predefined type, a value must be passed to EBPP via Batch File (Account Master File) or API prior to sending API requests associated with payment amount types. Current Balance, Minimum Payment Due, Past Payment Due, and Current Statement Balance can be used for this.
Discount Amount is available to offer a discount for prompt payment on account in full limited to One Time Payment. Select one predefined Payment Amount Type associated with One Time Payment within each applicable Channel. Logic to evaluate customer’s eligibility for discount needs to be configured and may require ongoing updates via Batch File (Account Master File).
Penalty Amount to charge a penalty for late payments is also supported limited to One Time Payment. Logic to assess a penalty must be configured for one predefined Payment Amount Type associated with One Time within each applicable Channel.
For the undefined, no prior or ongoing billing data is required. Select Other to pass a payment amount that is entered by the end user.
Only the Payment Amount Types associated with the Payment Types enabled for the Channel must be sent with Payment related API requests.
Fee
Fee can be configured to be assessed to each Payment Type enabled within each Channel.
The fee can be added to the main payment and processed as a single transaction. Or it can be split and processed separately from the payment. Your business type will determine which Fee Type to elect.
If fee setup is managed in EBPP, you do not need to send fee attributes in Create Payment API requests as they will be populated based on the selected configuration. In response to a successful Create Payment API request, EBPP will return details of the fee charged.
If fee setup is managed outside EBPP, a fee amount must be sent with each Create API request. Only the Add_to_Principal fee type is supported.
Custom Fields
Optionally, Custom Fields can be configured to store additional information on an object outside the standard EBPP database setup.
This can only be set up at the Customer Account and Payment level. Up to 64 standard custom fields can be supported along with up to 12 secure custom fields.
Object Identifiers
A pair of unique identifiers can be used for each object: Reference and ID.
A value for the Reference is originated from the Client system, and a value for the ID is generated in EBPP. Note that EBPP assigns an ID to an object that is successfully created.
Resources
Explore our data objects to form your integration use cases.
Customer
This is the individual or company that owns one or more accounts that they need to pay.
Customer Account
This is what gets paid when a payment is made. In our definition, an account has one or more amounts owed and possibly a due date. As the billing system cycles the account, the new balance replaces the old balance such that there is only one liability at a time.
Funding Account
This is what the customer uses to make a payment with – ACH and/or Card Account depending on your setup. Funding Accounts are linked to the customer and can be used for any Customer Accounts the customer holds.
Payment
This is the process that moves money from the Funding Account to the Customer Account to update the current balances on that Customer Account.
Upon successful creation of a payment, EBPP issues a unique identifier and a Confirmation Number to the payment. The Confirmation Number advises the payment to the end user and can be used to look up the transaction in EBPP. The ID is passed by EBPP with each ACH or Card transaction record that is passed through the customer’s bank or card issuer, and it can be used to look up the transaction as well.
As the payment goes through the processing cycle, the payment status may get updated.
Payment Setup
This is an enrollment to have a series of payments created.
Upon successful creation of payment setup, EBPP issues a unique identifier and a Confirmation Number to the payment setup. The payment setup and each payment will have a unique ID but share the same Confirmation Number.
As the payment goes through the processing cycle, the payment status may get updated.
Refund
This is a process to move money from the Customer Account paid previously to the Funding Account associated with that payment to credit the customer.
Developer Journey
Follow the steps listed below in a sequential order to complete your API integration with us.
Step 1: Setup Sandbox
Select configuration options that suit your business needs and implement them with the help of the Alacriti Team prior to API integration. Any changes to the configurations will impact your API testing/deployment subsequently.
Sandbox Credentials
Upon completion of the sandbox setup, we will provide you with your sandbox credentials: Client Key and a pair of Client Secret Keys. Either Secret Key can be used with the Client Key. Treat these keys as sensitive data as you will need them for authentication.
Different credential values are used between Sandbox and Production. Production values will be generated once you migrate to production.
Step 2: Start Your API Integration Testing
Once your sandbox setup is complete, you can begin your API integration testing. Understand what objects EBPP API has and an order of API calls to make for each use case you have.
Step 3: Sign-off on Your Sandbox
Review your sandbox testing results and provide your sign-off on the sandbox setup.
Step 4: Migrate to Production
Upon your request, we will migrate your sandbox setup to production.
Production Credentials
Upon completion of the production build, we will provide you with your production credentials.
Live Proving
Perform end-to-end testing with low volume transactions in a controlled environment, from transaction processing to settlement, prior to a full release.
Full Launch
Fully go live with the Payments API integration after successful validation on the soft launch.
Common Use Cases
This section explains the API calls to invoke to fulfill some of the common Client features.
Note that EBPP assigns a unique identifier to each object that is created in its system. Those identifiers are returned in the API response to a successful create request.
We recommend that you save the identifiers for subsequent API calls. If not, you will need to use retrieve API calls to locate those identifiers.
Create a One-time Payment
Required Resources: None
Step 1: Simple Payment API
Simple Payment API can be used to create a payment in one shot, without explicitly creating a Customer, Customer Account and Funding Account. This API creates a Customer and Customer Account on the fly. The Funding Source used for the payment can, optionally, be saved for future use. This API is useful when the client does not want to maintain the EBBP issued identifiers. The Simple Payment API also takes care of updating the Customer and Customer Account details based on the unique identifiers defined by the client.
Simple Payment API request for same day payments must be sent prior to your payment cut off time configured in EBPP.
When a payment is scheduled, EBPP assigns an ID to the payment and generates a unique confirmation number. The confirmation number provides the end user with a reference for the payment.
Step 1: Create Simple Payment
Enroll for AutoPay
Required Resources: Customer & Customer Account and Funding Account
AutoPay is used to set up a series of payments where the date, frequency, duration, and amount is driven by ongoing billing data. To supply this billing data, you will need an additional integration for a batch file (Account Master File).
If you have identified all required objects and have the corresponding object ID’s, you can create a payment setup. If not, you will need to retrieve the IDs from EBPP by making Retrieve requests to the appropriate Resources.
Step 1: Retrieve Customers (Optional)
Look up customers by unique customer attribute(s) that was used to create the customer in EBPP such as Account Number.
A list of customers and its customer account(s) that match the search criteria will be returned as well as the ID’s linked to these objects. If more than one customer is found, refine the search parameters to locate the correct customer.
Step 2: Get Customer (Optional)
Retrieve details of the customer and its customer account(s) associated with the customer ID from EBPP. Use the ID of the customer account returned in response to the Retrieve Customers request.
Step 3: Retrieve Funding Accounts (Optional)
Retrieve all funding accounts linked to the customer by using the customer ID. Only an active funding account can be used to schedule a payment. Locate the funding account to use.
Step 4: Create Payment Setup
Once the ID’s of the customer, customer account, and funding account are identified, a payment setup can be created. Payment schedule type (AutoPay) and payment amount type (selected payment amount) must be defined.
Upon completion of the request, EBPP assigns an ID to the payment and generates a confirmation number. The same confirmation number is used for the setup and its child payments while a unique ID will be assigned to each child payment.
Enroll an Existing Customer for AutoPay with an Existing Funding Account
Add a Funding Account to an Existing Customer
Required Resources: Customer & Funding Account
Funding accounts are linked to the customer object and can be used for any customer accounts the customer holds. The ID of the customer to which a funding account is added must be identified in the Add Funding Account API request.
If you have identified all required objects and have the corresponding object ID’s, you can add a funding account. If not, you will need to retrieve the ID’s from EBPP by making Retrieve requests to the appropriate Resources.
Step 1: Retrieve Customer (Optional)
Step 2: Add Funding Account
Add a Funding Account to an Existing Customer
Update a Pending Payment
Required Resources: Customer & Payment
Payments that are yet to be processed can be updated. Customer and payment objects to be updated must be identified, and the ID of these objects must be sent in the Update Payment API request.
If you have identified all required objects and have the corresponding object ID’s, you may update the payment. If not, you will need to retrieve the ID’s from EBPP by making Retrieve requests to the appropriate resources.
Step 1: Retrieves Customers (Optional)
Step 2: Get Customer (Optional)
Step 3: Retrieve Payments (Optional)
Look up payments the customer made with the Retrieve Payments API request by using the ID of the customer and customer account. A list of all payments on this customer/customer account will be returned. Confirmation number alone in the request will return a particular payment.
Additional search criteria may be used to filter those payments. For example, setting the status to Scheduled in the request will only return pending payments that can be updated.
Step 4: Get Payment (Optional)
Once a payment to edit has been identified, get details of the payment. Payment ID and customer ID are required in the Get Payment API request.
Step 5: Update Payment
Only include the attributes of the payment that is to be updated in the Update Payment API request. Payment ID and customer ID are required for this request.
EBPP will return the same ID to the updated payment in response to the successful request. Confirmation number will also remain the same.
Update a Pending Payment
Delete a Payment
Required Resources: Customer & Payment
You can delete pending payments that are yet to be processed. Payment to be deleted and the customer associated with that payment must be identified, and the ID of these objects must be sent in the Update Payment API request.
If you have identified all required objects and have the corresponding object ID’s, you can delete the payment. If not, you will need to retrieve the ID’s from EBPP by making Retrieve requests to the appropriate Resources.
Step 1: Retrieves Customers (Optional)
Step 2: Get Customer (Optional)
Step 3: Retrieve Payments (Optional)
Step 4: Get Payment (Optional)
Step 5: Delete Payment
Customer ID must be identified in the Delete Payment API request, as well as the ID of the payment to be deleted.
EBPP will return the same ID to the deleted payment in response to the successful request. Confirmation number will also remain the same.
Delete a Payment
Refund a Payment
Required Resources: Customer & Payment
Only payments that have been processed can be refunded. Payment to be refunded and the customer linked with the payment must be identified. The ID’s of these objects must be included in the Create Refund API request.
If you have identified all required objects and have the corresponding object ID’s, you can refund the payment. If not, you will need to retrieve the IDs from EBPP by making Retrieve requests to the appropriate Resources.
Step 1: Retrieves Customers (Optional)
Step 2: Get Customer (Optional)
Step 3: Retrieve Payments (Optional)
Step 4: Get Payment (Optional)
Step 5: Create Refund
Customer ID must be identified in the Delete Payment API request, as well as the payment ID to be refunded.
EBPP will return a new ID to the refunded payment in response to the successful request. Confirmation Number will remain the same.
Refund a Payment
Developer Guide
The following videos will assist the developer put it all together and integrate with our API quickly.
Developer Guide
Note: The layout and design of the Developers portal might change from time to time. However, this would not have any implication on the guidance for integrating the EBPP API, as provided in the videos.
API Playground
Try out the API using the samples listed, for the various SDKs published. Please contact your RM for the authentication details to access the API Playground. However, please note that this is not a sandbox/testing environment to test the API integration.
