Bill Pay
Allow your customers to locate and pay their bills to thousands of billers.
note
The Bill pay API is not enabled by default - compliance action is required in order to offer this feature to your customers. Please contact Unit if you would like to enable this functionality.
List Billers#
List billers. Filtering and paging can be applied.
| Verb | GET |
| Url | https://api.s.unit.sh/payments/billpay/billers |
| Required Scope | payments |
| Timeout (Seconds) | 120 |
Query Parameters#
| Name | Type | Description |
|---|---|---|
| page | integer | Optional. Determine the results page number. |
| name | string | Filter the name of the biller (full or partial). |
curl -X GET 'https://api.s.unit.sh/payments/billpay/billers?name=Electric&page=1' \-H "Authorization: Bearer ${TOKEN}"Response#
Response is a JSON:API document.
200 OK#
| Field | Type | Description |
|---|---|---|
| data | Array of Biller | Array of biller resources. |
Example Response:
{ "data": [ { "type": "biller", "id": "7b0fd858-5f86-4c5e-80fc-6feb6cba4186", "attributes": { "name": "Adams-Columbia Electric Cooperative", "category": "Electric / Gas / Power / Water", "addresses": [ { "city": "ALBANY", "state": "GA", "country": "US", "street": "1234 WESTTOWN RD", "postalCode": "31707" } ] } }, { "type": "biller", "id": "40518a36-1f6e-4b3e-8da5-919e289048a5", "attributes": { "name": "Adams Electric", "category": "Electric / Gas / Power / Water", "addresses": [ { "city": "ALBANY", "state": "GA", "country": "US", "street": "3456 WESTTOWN RD", "postalCode": "31707" } ] } }, { "type": "biller", "id": "48b0742f-a571-4377-ad33-f2c41dfc9c00", "attributes": { "name": "Adams Electric Cooperative, Inc", "category": "Electric / Gas / Power / Water", "addresses": [ { "city": "ALBANY", "state": "GA", "country": "US", "street": "2345 WESTTOWN RD", "postalCode": "31707" } ] } } ]}Create Bill Payment#
In order to create a bill payment, without any sensitive data passing through your systems (which requires PCI compliance), Unit utilizes a 3rd party service called Very Good Security or VGS for short.
VGS provides a JavaScript library (as well as iOS and Android SDKs) called VGS Collect which allows easy integration with your UI components.
VGS Collect offloads the PCI compliance burden by enabling the encrypted transmission of sensitive data from VGS directly to the bill pay processor.
VGS Collect JavaScript library injects a secure iframe into your HTML. VGS hosts both the iframe, and the data on secure, compliant servers.
Integration steps#
Import the VGS Collect library:
<script type="text/javascript" src="https://js.verygoodvault.com/vgs-collect/2.12.0/vgs-collect.js"></script>
Initialize the component:
const form = VGSCollect.create("tntazhyknp1", "sandbox", function(state) {});
note
The Vault Id tntazhyknp1 enables you to test your code in a sandbox environment. Contact Unit for the live Vault Id.
Provide a valid customer token:
const customerToken = "<CUSTOMER TOKEN>"
For instructions, see Create Customer Token.
Example of Create Bill Payment:
<!DOCTYPE html><html lang="en"><head> <meta charset="UTF-8"> <title>VGS Collect Bill Pay Example</title>
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css" integrity="sha384-Gn5384xqQ1aoWXA+058RXPxPg6fy4IWvTNh0E263XmFcJlSAwiGgFAW/dAiS6JXm" crossorigin="anonymous">
<script type="text/javascript" src="https://js.verygoodvault.com/vgs-collect/2.12.0/vgs-collect.js"></script>
<style> body { padding: 25px; }
span[id*="cc-"] { display: block; height: 40px; margin-bottom: 15px; }
span[id*="cc-"] iframe { height: 100%; width: 100%; }
pre { font-size: 12px; }
.form-field { display: block; width: 100%; height: calc(2.25rem + 2px); padding: .375rem .75rem; font-size: 1rem; line-height: 1.5; color: #495057; background-color: #fff; background-clip: padding-box; border: 1px solid #ced4da; border-radius: .25rem; transition: border-color .15s ease-in-out,box-shadow .15s ease-in-out; }
.form-field iframe { border: 0 none transparent; height: 100%; vertical-align: middle; width: 100%; }
p { margin-bottom: 10px; } </style></head><body><main> <div class="row"> <div class="col-md-4"></div> <div class="col-md-4"> <div class="row card card-outline-secondary"> <div class="card-body"> <h3 class="text-center">Bill Pay</h3> <hr> <div class="alert alert-info p-2"> Please fill in and submit the form </div> <form id="cc-form"> <div class="form-group"> <label for="cc-biller">Biller</label> <span id="cc-biller" class="form-field"> <!--VGS Collect iframe for Biller field will be here!--> </span> <label for="cc-account-number">Account Number</label> <span id="cc-account-number" class="form-field"> <!--VGS Collect iframe for Account Number field will be here!--> </span> <label for="cc-amount">Amount</label> <span id="cc-amount" class="form-field"> <!--VGS Collect iframe for Amount field will be here!--> </span> <label for="cc-description">Description</label> <span id="cc-description" class="form-field"> <!--VGS Collect iframe for Description field will be here!--> </span> </div> <!--Submit form button--> <button type="submit" class="btn btn-success btn-block">Submit</button> </form> </div> </div> </div> <div class="col-md-4"></div> </div></main>
<!--Include script with VGS Collect form initialization--><script> // VGS Collect form initialization const form = VGSCollect.create("tntazhyknp1", "sandbox", function(state) {}); const customerToken = "<CUSTOMER TOKEN>"
// Create VGS Collect field for Biller form.field("#cc-biller", { type: "dropdown", name: "biller", placeholder: "Select Biller", validations: ["required"], options: [ { value: "7b0fd858-5f86-4c5e-80fc-6feb6cba4186", text: "Adams-Columbia Electric Cooperative" }, { value: "40518a36-1f6e-4b3e-8da5-919e289048a5", text: "Adams Electric" }, { value: "48b0742f-a571-4377-ad33-f2c41dfc9c00", text: "Adams Electric Cooperative, Inc" }, ], });
// Create VGS Collect field for Account Number form.field("#cc-account-number", { type: "text", name: "accountNumber", placeholder: "Account Number", validations: ["required"], });
// Create VGS Collect field for Amount form.field("#cc-amount", { type: "text", name: "amount", placeholder: "Amount", validations: ["required"], });
// Create VGS Collect field for Description form.field("#cc-description", { type: "text", name: "description", placeholder: "Description", validations: ["required"], });
// Submit by executing a POST request. document.getElementById('cc-form') .addEventListener('submit', function(e) { e.preventDefault(); form.submit('/payments', { headers: { "Content-Type": "application/vnd.api+json", "Authorization": "Bearer " + customerToken }, data: (formValues) => { return { data:{ type:"billPayment", attributes: { billerId: formValues["biller"], accountNumber: formValues["accountNumber"], amount: formValues["amount"], description: formValues["description"], tags: { "account_id": "b6f395c9-e58a-40a5-a5a4-901d603440b9" } }, relationships: { account: { data: { type: "depositAccount", id: "10001" } } } } } } }, function(status, data) { console.log(data); }); }, function (errors) { console.log(errors); });</script></body></html>