Developers
EBPP - Billing System Integration Logo

EBPP - Billing System Specifications - Single Profile Account (1.1.7)

Contact: support@billerpayments.com License: © Alacriti Inc

Introduction

This document explains the Billing System specifications that a biller needs to implement.

Account & Billing Specification explains the API specifications needs to implement by client, so that EBPP can pull customer, customer account and billing related information in real-time.

There are two models in EBPP, namely,

  1. Single Profile Account, where only a single customer profile can be associated with a customer account.

  2. Multi-Profile Account model, where multiple customer profiles can be associated with a customer account. For e.g.,

    1. Co-borrowers / Joint borrowers of a loan account who would want to make the EMI payment separately.
    2. Designated employees of a company who manage the Group insurance policy on behalf of their employer.

    This page contains the set of APIs which can be used with the single-profile Account model.

**Important:** A Client cannot opt for both the models at the same time. Therefore, before integrating with the EBPP Payments API, please make sure that you are clear about the model you want to opt for. Please contact us if you need any assistance regarding the choice of model.

Posting Specification explains the API specifications needs to implement by client, so that EBPP can Post the realtime transactions.

Authentication

EBPP supports API Keys over HTTP Headers.

In this authentication scheme, EBPP would send API Keys, in the form of HTTP headers, as part of the request. These API Keys must be configured in EBPP by the biller/client beforehand. Clients can check for the authenticity of the request by comparing the API keys and values received in the request with the ones configured in EBPP. Clients can configure more than one API Keys based on their business needs.

HTTP Response Codes

This API specification supports standard HTTP response codes to return the status of an API call. Additional information, such as errors, may be useful to the caller (EBPP). An HTTP response code of 2xx indicates success. An HTTP response code of 4xx indicates a client error and 5xx indicates a processing error. In these cases, billers are expected to return the list of errors in the format specified in the Error Codes section. Each error has a code, message and specifics on which field the error pertains to (if applicable.)

Error Codes

An HTTP response code of 4xx indicates a client error and 5xx indicates a processing error. Each error has a code, message and field.

Example :

{
  "errors": [
   {
      "code": "error_field",
      "message": "The error returned if a mandatory field is missing value or if the value is invalid. This is accompanied by the field that caused the error.",
      "field": "account_number"
   }
  ]
}

The following error codes can be implemented by the biller.

code message remarks
error_field The error returned if a mandatory field is missing value or if the value is invalid. This is accompanied by the field that caused the error. The agent will take appropriate action based on error code
error_posting_rejected The payment will never post The agent will take appropriate action based on error code
error_account_closed Account status closed The agent will take appropriate action based on error code
error_account_status_invalid Account status queued for repair The agent will take appropriate action based on error code
error_payment_amount_low Payment amount is too low The agent will take appropriate action based on error code
error_payment_amount_high Payment amount too high The agent will take appropriate action based on error code
error_duplicate_posting Duplicate Posting, no action required The agent will take appropriate action based on error code
error_member_warning Member warnings not allow to post The agent will take appropriate action based on error code
error_account_warning Account warnings not allow to post The agent will take appropriate action based on error code
error_refund_initiate The payment will never post,Initiate refund for this posting The refund will be initiate by the Orbipay system

Resources

Customers holds Customer Accounts. A Payment is always made against a Customer Account by/on behalf of a Customer using an associated Funding Account.

Customer : The individual or entity associated with a Customer Account.

Customer Account : The billing account against which a Customer makes payments.

Payment The process through which funds from an associated Funding Account are applied towards a balance due on a Customer's billing account.

Accounts & Billing

This section outlines the API required to exchange and manage customer information, such as customer account details.

Lookup Customer

This API is used to retrieve/lookup customer from biller/client system. Customer can be retrieved matching criteria that includes the customer reference or customer account number or lookup reference.

header Parameters
client-key
required
string [ 0 .. 50 ] characters [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

api-key
required
string

API key to authenticate requests. You can pass one or more pair (< Key > < Value >).

Request Body schema: application/x-www-form-urlencoded
customer_reference
string [ 0 .. 100 ] characters ^$|[0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\s\\]+

Unique ID assigned by the biller/client system for a given customer.

account_number
string [ 4 .. 32 ] characters [a-zA-Z0-9-_/!@#$%&*{}.]+

Customer Account number of the customer to get details of.

ssn
string 9 characters [0-9]{9}

The SSN of the customer if the account holder is an individual or the tax ID, if the customer is a business.

email
string <email> [ 0 .. 100 ] characters [a-zA-Z0-9!#$%&'*+-/=?^._`{|}~]+@[a-zA-Z0-9_.-]+\.[a-zA-Z0-9._]+

The email address of the customer to which notifications from EBPP will be sent. This will default to the registered_email while creating a customer.

lookup_reference
string [ 0 .. 100 ] characters ^$|[0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\s\\]+

The alternate reference maintained in the biller/client system for a customer.

Responses

200

The concerned Resource found with the provided matching criteria.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized, often due to missing api key(s).

403

Forbidden

404

The requested resource doesn't exist.

500

Something went wrong at the Server

post/spacustomers
https://client.endpoint.com/spacustomers

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
}

Posting

This section outlines the API required to post the transaction information to the client system.

Payment Posting

This API is used to post the real time transaction details into the biller/client system.

header Parameters
client-key
required
string [ 0 .. 50 ] characters [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

api-key
required
string

API key to authenticate requests.

Request Body schema: application/json
posting_info
object

The posting information.

amount
required
string ^[0-9]{1,14}(\.[0-9][0-9]?)?$

The amount being paid for the payment.

card_cvv_number
string [0-9]{3,4}

This is never returned by EBPP. This needs to be passed to EBPP when making or editing a payment with a card funding account.

confirmation_number
required
string [a-zA-Z0-9]{1,30}

The confirmation number or reference provided to the customer for the payment.

currency_code3d
required
string [A-Z]{3}

The three-letter currency code in the ISO4217 format, in uppercase, for the card account. It must be a currency supported by EBPP. This defaults to USD.

custom_fields
required
object

The additional information or meta-information that EBPP can accept, maintain and transmit back to the client. The custom fields need to be configured with EBPP before they can be accepted. EBPP would reject custom fields that are not pre-configured. Please contact support@billerpayments.com for more information on configuring and using custom fields.

customer
required
object

The customer making the payment

customer_account
required
object
expected_payment_settlement_date
string <date> ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date on which the payment is expected to be settled with the biller. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.

fee
object
funding_account
required
object
id
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the payment.

payment_amount_type
string
Enum: "current_balance" "minimum_payment_due" "past_payment_due" "statement_balance" "discounted_amount" "penalty_amount" "other" "payoff_amount" "paydown_amount"

The type of amount, as per the bill/statement, that is being paid. The payment amount is derived from the amount type selected for the payment. This defaults to other.

payment_date
required
string <date> ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date on which the payment is scheduled to be made. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.

payment_entry_date
string <date> ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date on which the payment is captured in EBPP. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.

payment_method
required
string
Enum: "ach" "check" "visa_debit" "pinless_debit" "master_debit" "amex_credit" "discover_credit" "visa_credit" "master_credit" "discover_debit" "cash" "swiped_card" "scanned_check" "external_pos" "apple_pay" "google_pay" "voyager_fleet"

The fulfillment method for the payment.

payment_network_response
required
object

The response received either from ACH or Card networks.

payment_reference
string [0-9a-zA-Z._-]{1,50}

The unique identifier in the client system for the payment.

payment_request_date
string <date> ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date on which the biller wants the payment to be settled. It must be in ISO8601 full-date format, namely, YYYY-MM-DD. This is applicable only if the client has opted for it.

payment_return_date
string <date> ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date on which the ACH returns is received by EBPP.

payment_schedule_type
required
string
Enum: "one_time_payment" "autopay_generated_payment" "variable_recurring_generated_payment" "payment_plan_generated"

The schedule type for the payment. This defaults to one_time_payment.

return_code
string [a-z0-9]{1,10}

The ACH return code or the chargeback code received from Visa/Mastercard, in the event of returned payments.

status
required
string
Enum: "scheduled" "cancelled" "processing" "processed" "returned" "declined" "disputed" "error"

The status of the payment.

payment_notification_email
string <email> [a-zA-Z0-9!#$%&'*+-/=?^._`{|}~]+@[a-zA-Z0-9_.-]+\.[a-zA-Z0-9._]{1,100}

The email address to which notifications for the payment will be sent. The notifications will be sent to the customer's email in case this is not provided.

comments
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"\r\n]{1,1000}

Comments that can be used to recollect the operation performed on the resource object. API clients need to ensure that no sensitive information is passed in the memo. Alacriti (EBPP) is not responsible for the security of any sensitive information that may be passed as part of the memo.

token
string [0-9a-zA-Z._-]{1,64}

The token is used to uniquely identify the payment, such as the POS token.

url
string

This URL fetches the details of payment.

Responses

200

The payment posting response Object.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized, often due to missing api key(s).

403

Forbidden

404

The requested resource doesn't exist.

422

The parameters were valid but the request failed..

500

Something went wrong at the Server

post/paymentposting
https://client.endpoint.com/paymentposting

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
}

Payment Reversal

This API is used to post the cancelled transaction details into the biller/client system.

header Parameters
client-key
required
string [ 0 .. 50 ] characters [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

api-key
required
string

API key to authenticate requests. You can pass one or more pair (< Key > < Value >).

Request Body schema: application/json
posting_info
object

The posting information.

amount
required
string ^[0-9]{1,14}(\.[0-9][0-9]?)?$

The amount being paid for the payment.

card_cvv_number
string [0-9]{3,4}

This is never returned by EBPP. This needs to be passed to EBPP when making or editing a payment with a card funding account.

confirmation_number
required
string [a-zA-Z0-9]{1,30}

The confirmation number or reference provided to the customer for the payment.

currency_code3d
required
string [A-Z]{3}

The three-letter currency code in the ISO4217 format, in uppercase, for the card account. It must be a currency supported by EBPP. This defaults to USD.

custom_fields
required
object

The additional information or meta-information that EBPP can accept, maintain and transmit back to the client. The custom fields need to be configured with EBPP before they can be accepted. EBPP would reject custom fields that are not pre-configured. Please contact support@billerpayments.com for more information on configuring and using custom fields.

customer
required
object

The customer making the payment

customer_account
required
object
expected_payment_settlement_date
string <date> ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date on which the payment is expected to be settled with the biller. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.

fee
object
funding_account
required
object
id
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the payment.

payment_amount_type
string
Enum: "current_balance" "minimum_payment_due" "past_payment_due" "statement_balance" "discounted_amount" "penalty_amount" "other" "payoff_amount" "paydown_amount"

The type of amount, as per the bill/statement, that is being paid. The payment amount is derived from the amount type selected for the payment. This defaults to other.

payment_date
required
string <date> ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date on which the payment is scheduled to be made. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.

payment_entry_date
string <date> ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date on which the payment is captured in EBPP. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.

payment_method
required
string
Enum: "ach" "check" "visa_debit" "pinless_debit" "master_debit" "amex_credit" "discover_credit" "visa_credit" "master_credit" "discover_debit" "cash" "swiped_card" "scanned_check" "external_pos" "apple_pay" "google_pay" "voyager_fleet"

The fulfillment method for the payment.

payment_network_response
required
object

The response received either from ACH or Card networks.

payment_reference
string [0-9a-zA-Z._-]{1,50}

The unique identifier in the client system for the payment.

payment_request_date
string <date> ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date on which the biller wants the payment to be settled. It must be in ISO8601 full-date format, namely, YYYY-MM-DD. This is applicable only if the client has opted for it.

payment_return_date
string <date> ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date on which the ACH returns is received by EBPP.

payment_schedule_type
required
string
Enum: "one_time_payment" "autopay_generated_payment" "variable_recurring_generated_payment" "payment_plan_generated"

The schedule type for the payment. This defaults to one_time_payment.

return_code
string [a-z0-9]{1,10}

The ACH return code or the chargeback code received from Visa/Mastercard, in the event of returned payments.

status
required
string
Enum: "scheduled" "cancelled" "processing" "processed" "returned" "declined" "disputed" "error"

The status of the payment.

payment_notification_email
string <email> [a-zA-Z0-9!#$%&'*+-/=?^._`{|}~]+@[a-zA-Z0-9_.-]+\.[a-zA-Z0-9._]{1,100}

The email address to which notifications for the payment will be sent. The notifications will be sent to the customer's email in case this is not provided.

comments
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"\r\n]{1,1000}

Comments that can be used to recollect the operation performed on the resource object. API clients need to ensure that no sensitive information is passed in the memo. Alacriti (EBPP) is not responsible for the security of any sensitive information that may be passed as part of the memo.

token
string [0-9a-zA-Z._-]{1,64}

The token is used to uniquely identify the payment, such as the POS token.

url
string

This URL fetches the details of payment.

Responses

200

The payment response object.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized, often due to missing api key(s).

403

Forbidden

404

The requested resource doesn't exist.

422

The parameters were valid but the request failed..

500

Something went wrong at the Server

post/paymentreversalposting
https://client.endpoint.com/paymentreversalposting

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
}

Payment Refunded

This API is used to post the refund transaction details into the biller/client system.

header Parameters
client-key
required
string [ 0 .. 50 ] characters [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

api-key
required
string

API key to authenticate requests. You can pass one or more pair (< Key > < Value >).

Request Body schema: application/json
posting_info
object

The posting information.

refund_reference
string [0-9a-zA-Z._-]{1,50}

The unique identifier in the client system for the refund.

id
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the refund.

url
string

This URL fetches the details of refund.

refund_type
string
Enum: "payment_and_fee" "payment_only" "fee_only" "other"

The portion of the payment amount that is to be or has been refunded. The original payment can be refunded fully including the amount and the fee components, or partially, for just the amount or the fee component. Refund can also be initiated for an arbitrary amount limited by the original payment amount.

refund_amount
string ^[0-9]{1,14}(\.[0-9][0-9]?)?$

The refund amount upto 2 decimal places.

fee_refund
object
status
required
string
Enum: "scheduled" "cancelled" "processing" "processed" "declined" "returned" "disputed" "error"

The status of the refund.

confirmation_number
required
string [a-zA-Z0-9]{1,30}

The confirmation number or reference provided to the customer for the refund.

refund_date
string ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date on which the refund is scheduled to be made. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.

refund_entry_date
string ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date on which the refund captured in EBPP. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.

expected_refund_settlement_date
string ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date by which the credits would be posted to the original funding account. ISO8601 full-date format, YYYY-MM-DD

source_payment
required
object
payment_network_response
object

The response received either from ACH or Card networks.

custom_fields
object

The additional information or meta-information that EBPP can accept, maintain and transmit back to the client. The custom fields need to be configured with EBPP before they can be accepted. EBPP would reject custom fields that are not pre-configured. Please contact support@billerpayments.com for more information on configuring and using custom fields.

comments
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"\r\n]{1,1000}

Comments that can be used to recollect the operation performed on the resource object. API clients need to ensure that no sensitive information is passed in the memo. Alacriti (EBPP) is not responsible for the security of any sensitive information that may be passed as part of the memo.

Responses

200

The payment response object.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized, often due to missing api key(s).

403

Forbidden

404

The requested resource doesn't exist.

422

The parameters were valid but the request failed..

500

Something went wrong at the Server

post/paymentrefundposting
https://client.endpoint.com/paymentrefundposting

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
}