E-Bills

👍
e-Bill vs Subscription
While e-bills and subscriptions both involve payment terms and amounts, they differ in the level of customer engagement.
E-bills are typically sent directly to customers and customers choose to pay them, whereas, Subscriptions are automatically paid when they become active.
Customers can setup AutoPay for e-bills or may pay by logging into the Securely.io customer portal, but Subscriptions are paid when they are due without the customers intervention.

📩 Create an e-Bill

Merchants can leverage Securely.io's e-billing system to send invoices to existing customers. These e-bills offer flexibility in payment terms, allowing for either a fixed term (one-time invoice) or an open term (ongoing payments).

To ensure smooth record-keeping, we recommend using the "External Identifier" field. This allows merchants to link the e-bill to their internal accounting systems and include internal notes and dates for easy reference. This integration between Securely.io and your internal processes, streamlines e-bill creation and simplifies tracking for both merchants and customers.

securelyApiKey="YOUR_SECURELY_API_KEY"
securelyApiSecret="YOUR_SECURELY_API_SECRET"
authorization=$(echo -n "$securelyApiKey:$securelyApiSecret" | base64)

curl --location 'https://sandbox-api.securelyme.io/e-bills/create' \
  -H "Authorization: Basic $authorization" \
  -H "Content-Type: application/json" \
--data '{
    "memo": "LIMIT 24 CHARACTERS",
    "customerMessage": "EBILL CUST MSG: Weekly bill for services",
    "customerUserId": 1,
    "internalNotes": "INTERNAL NOTES",
    "invoiceNumber": "EBILL-INV-NO",
    "amount": 0.01,
    "frequency": "Weekly",
    "endDate": "2024-12-31",
    "effectiveDate": "2024-10-03",
    "paymentTermValue": 0,
    "externalIdentifier": "EBILL-EXT-ID"
}'

var apiKey = "YOUR_API_KEY";
var apiSecret = "YOUR_API_SECRET";
var encodedCredentials = Convert.ToBase64String(Encoding.ASCII.GetBytes($"{apiKey}:{apiSecret}"));

string jsonData = @"{
    ""memo"": ""Memo"",
    ""customerMessage"": ""EBILL CUST MSG: Weekly bill for services"",
    ""customerUserId"": 1,
    ""internalNotes"": ""INT-NOTES: Weekly bill for services rendered"",
    ""invoiceNumber"": ""EBILL-INV-NO"",
    ""amount"": 9.02,
    ""frequency"": ""Weekly"",
    ""endDate"": ""2024-12-31"",
    ""effectiveDate"": ""2024-10-03"",
    ""paymentTermValue"": 0,
    ""externalIdentifier"": ""EBILL-EXT-ID""
}";

var client = new HttpClient();
var request = new HttpRequestMessage(
  HttpMethod.Post, 
  "https://sandbox-api.securelyme.io/e-bills/create");

request.Headers.Add("Authorization", $"Basic {encodedCredentials}");
request.Content = new StringContent(jsonData, null, "application/json");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

const axios = require('axios');
const apiKey = "YOUR_API_KEY";
const apiSecret = "YOUR_API_SECRET";
const encodedCredentials = Buffer.from(`${apiKey}:${apiSecret}`).toString('base64');

let data = JSON.stringify({
  "memo": "Memo: voluptatem",
  "customerMessage": "EBILL CUST MSG: Weekly bill for services",
  "customerUserId": 102787,
  "internalNotes": "INT-NOTES: Weekly bill for services rendered",
  "invoiceNumber": "EBILL-INV-NO-775",
  "amount": 9.02,
  "frequency": "Weekly",
  "endDate": "2024-12-31",
  "effectiveDate": "2024-10-03",
  "paymentTermValue": 0,
  "externalIdentifier": "EBILL-EXT-ID-632"
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://sandbox-api.securelyme.io/e-bills/create',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': `Basic ${encodedCredentials}`
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

This API call for creating e-bills returns a successful response with a 201 Created status code and a unique eBillId. This identifier serves as a reference for future actions like suspending, resuming, canceling, or updating the e-bill. By preserving the eBillId, you can efficiently manage and track your e-bill transactions.

{
    "payload": {
        "eBillId": 123456
    },
    "success": true
}

🔠 Managing e-Bill Transactions

Merchants can effortlessly manage their e-bills. With a simple PUT request and the unique eBillId, merchants can easily suspend, resume, cancel, or update their e-bill transactions.

securelyApiKey="YOUR_SECURELY_API_KEY"
securelyApiSecret="YOUR_SECURELY_API_SECRET"
authorization=$(echo -n "$securelyApiKey:$securelyApiSecret" | base64)
ebillId=1

curl --location --globoff --request PUT \
	'https://sandbox-api.securelyme.io/e-bills/{ebillId}/suspend' \
	-H "Authorization: Basic $authorization"

var apiKey = "YOUR_API_KEY";
var apiSecret = "YOUR_API_SECRET";
var encodedCredentials = Convert.ToBase64String(Encoding.ASCII.GetBytes($"{apiKey}:{apiSecret}"));
var eBillId = 1

var client = new HttpClient();
var request = new HttpRequestMessage(
  HttpMethod.Put, 
  $"https://sandbox-api.securelyme.io/e-bills/{eBillId}/suspend");
request.Headers.Add("Authorization", $"Basic {encodedCredentials}");

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

const axios = require('axios');
const apiKey = "YOUR_API_KEY";
const apiSecret = "YOUR_API_SECRET";
const encodedCredentials = Buffer.from(`${apiKey}:${apiSecret}`).toString('base64');
const ebillId = 1

let config = {
  method: 'put',
  url: 'https://sandbox-api.securelyme.io/e-bills/{ebillId}/suspend',
  headers: { 
    'Authorization': `Basic ${encodedCredentials}`
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

🔍 Searching for E-Bills

Merchants can search for e-bills using a range of optional parameters, which include, create date range, customer id, status codes, external identifiers among others.

securelyApiKey="YOUR_SECURELY_API_KEY"
securelyApiSecret="YOUR_SECURELY_API_SECRET"
authorization=$(echo -n "$securelyApiKey:$securelyApiSecret" | base64)

curl --location 'https://sandbox-api.securelyme.io/e-bills/search' \
--header 'Content-Type: application/json' \
-H "Authorization: Basic $authorization"
--data '{
  "createdFromDate": "2024-01-01",
  "createdToDate": "2024-12-31",
  "pageSize": 20,
  "page": 1
}'

var apiKey = "YOUR_API_KEY";
var apiSecret = "YOUR_API_SECRET";
var encodedCredentials = Convert.ToBase64String(Encoding.ASCII.GetBytes($"{apiKey}:{apiSecret}"));

string jsonString = @"{
  ""createdFromDate"": ""2024-01-01"",
  ""createdToDate"": ""2024-12-31"",
  ""pageSize"": 20,
  ""page"": 1
}";

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://sandbox-api.securelyme.io/e-bills/search");
request.Headers.Add("Authorization", $"Basic {encodedCredentials}");

request.Content = new StringContent(jsonString, null, "application/json");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

const axios = require('axios');
const apiKey = "YOUR_API_KEY";
const apiSecret = "YOUR_API_SECRET";
const encodedCredentials = Buffer.from(`${apiKey}:${apiSecret}`).toString('base64');

let data = JSON.stringify({
  "createdFromDate": "2024-01-01",
  "createdToDate": "2024-12-31",
  "pageSize": 20,
  "page": 1
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://sandbox-api.securelyme.io/e-bills/search',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': `Basic ${encodedCredentials}`
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

A successful response will contain a list of e-bills created on a given date range, with data that defines this transaction.

👍
How does a get Customer notified of an E-Bill
Securely.io creates a Payment Requestwhen an E-Bill is due. Customers are notified of this payment request. If a customer cancels a payment request associated with an e-bill, only that transaction is cancelled and subsequent e-bills are presented for the payment term.

📫 Find the status of an e-Bill that is due

Merchants can conveniently track the status of their e-bills by reviewing associated payment requests. Since payment requests are generated when e-bills become due, this provides a direct way to monitor the payment status and take necessary actions if needed.

Notice the ebillId in the URL:

securelyApiKey="YOUR_SECURELY_API_KEY"
securelyApiSecret="YOUR_SECURELY_API_SECRET"
authorization=$(echo -n "$securelyApiKey:$securelyApiSecret" | base64)
ebillId=1

curl --location --request GET \
	'https://sandbox-api.securelyme.io/e-bills/{ebillId}/payment-requests?pageSize=20&pageNumber=1' \
-H 'Content-Type: application/json' \
-H "Authorization: Basic $authorization"

var apiKey = "YOUR_API_KEY";
var apiSecret = "YOUR_API_SECRET";
var encodedCredentials = Convert.ToBase64String(Encoding.ASCII.GetBytes($"{apiKey}:{apiSecret}"));
var ebillId = 1;

var client = new HttpClient();
var request = new HttpRequestMessage(
  HttpMethod.Get, 
  $"https://sandbox-api.securelyme.io/e-bills/{ebillId}/payment-requests?pageSize=20&pageNumber=1");
request.Headers.Add("Authorization", $"Basic {encodedCredentials}");

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

const axios = require('axios');
const apiKey = "YOUR_API_KEY";
const apiSecret = "YOUR_API_SECRET";
const encodedCredentials = Buffer.from(`${apiKey}:${apiSecret}`).toString('base64');
const ebillId = 1
let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: `https://sandbox-api.securelyme.io/e-bills/${ebillId}/payment-requests?pageSize=20&pageNumber=1`,
  headers: { 
    'Authorization': `Basic ${encodedCredentials}`
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

🤵‍♀️ E-Bill Payment Requests

Securely.io manages e-bill payments seamlessly. Upon an e-bill becoming due, a corresponding payment request is automatically generated for the customer. Customers can then conveniently settle the payment. For transparency and record-keeping, merchants can retrieve detailed information on these payment requests. A simple API call allows them to access the complete history of all payment requests associated with a specific e-bill, ensuring efficient tracking and management of e-bill transactions.

securelyApiKey="YOUR_SECURELY_API_KEY"
securelyApiSecret="YOUR_SECURELY_API_SECRET"
authorization=$(echo -n "$securelyApiKey:$securelyApiSecret" | base64)
ebillId=1

curl --location GET \
'https://sandbox-api.securelyme.io/e-bills/{ebillId}/payment-requests?pageSize=20&pageNumber=1' \
-H "Authorization: Basic $authorization"

var apiKey = "YOUR_API_KEY";
var apiSecret = "YOUR_API_SECRET";
var encodedCredentials = Convert.ToBase64String(Encoding.ASCII.GetBytes($"{apiKey}:{apiSecret}"));
var ebillId = 1;

var client = new HttpClient();
var request = new HttpRequestMessage(
  HttpMethod.Get, 
  $"https://sandbox-api.securelyme.io/e-bills/{ebillId}/payment-requests?pageSize=20&pageNumber=1");
request.Headers.Add("Authorization", $"Basic {encodedCredentials}");

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

const axios = require('axios');
const apiKey = "YOUR_API_KEY";
const apiSecret = "YOUR_API_SECRET";
const encodedCredentials = Buffer.from(`${apiKey}:${apiSecret}`).toString('base64');
const ebillId = 1

let config = {
  method: 'get',
  url:`https://sandbox-api.securelyme.io/e-bills/${ebillId}/payment-requests?pageSize=20&pageNumber=1`,
  headers: { 
    'Authorization': `Basic ${encodedCredentials}`
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

A successful call to the endpoint would return a result that looks like this:

{
    "hasMore": false,
    "totalCount": 1,
    "payload": [
        {
            "paymentRequestId": 123,
            "statusCode": "PAID",
            "amount": 1.02,
            "tipAmount": 0.00,
            "totalAmount": 1.35,
            "message": "EBILL CUST MSG: Weekly bill for services",
            "createdDate": "2024-01-01T15:00:00.000000+00:00",
            "completedDate": "2024-01-01T15:00:00.000000+00:00"
        }
    ],
    "success": true
}

🖇️ Attachment to an e-Bill

Merchants can easily add an attachment to their e-bills. This attachment may be the terms of the e-bill or even a PDF of the bill

Merchants may upload a document, that is base64 encoded, with the appropriate MIME type.

const axios = require('axios');

securelyApiKey="YOUR_SECURELY_API_KEY"
securelyApiSecret="YOUR_SECURELY_API_SECRET"
authorization=$(echo -n "$securelyApiKey:$securelyApiSecret" | base64)

curl --location 'https://sandbox-api.securelyme.io/e-bills/create' \
-H 'Content-Type: application/json' \
-H 'Authorization': 'Basic $authorization' \
--data '{
    "memo": "Memo",
    "customerMessage": "Message for the customer",
    "customerUserId": 1111,
    "internalNotes": "Internal notes for the Merchants reference",
    "invoiceNumber": "INVOICE-NUMBER-001",
    "amount": 0.01,
      "attachment": {
        "name": "Agreement",
        "content": "dGhpcyBpcyBhIHRlc3QgZmlsZSBvbmx5Lgo=",
        "mimeType": "text/plain"
      },
    "frequency": "Weekly",
    "endDate": "2025-01-01",
    "effectiveDate": "2025-01-01",
    "paymentTermValue": 12,
    "externalIdentifier": "INV-123"
}'

var apiKey = "YOUR_API_KEY";
var apiSecret = "YOUR_API_SECRET";
var encodedCredentials = Convert.ToBase64String(Encoding.ASCII.GetBytes($"{apiKey}:{apiSecret}"));

string json = @"{
    ""memo"": ""Memo"",
    ""customerMessage"": ""Message for customer"",
    ""customerUserId"": 1111,
    ""internalNotes"": ""Internal notes for Merchants reference"",
    ""invoiceNumber"": ""INVOICE-NO-001"",
    ""amount"": 0.01,
    ""attachment"": {
        ""name"": ""Agreement"",
        ""content"": ""dGhpcyBpcyBhIHRlc3QgZmlsZSBvbmx5Lgo="",
        ""mimeType"": ""text/plain""
    },
    ""frequency"": ""Weekly"",
    ""endDate"": ""2025-01-01"",
    ""effectiveDate"": ""2025-01-01"",
    ""paymentTermValue"": 12,
    ""externalIdentifier"": ""INV-123""
}";

var client = new HttpClient();
var request = new HttpRequestMessage(
  HttpMethod.Post, 
  "https://sandbox-api.securelyme.io/e-bills/create");
request.Headers.Add("Authorization", $"Basic {encodedCredentials}");
request.Content = new StringContent(json, null, "application/json");

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

const axios = require('axios');

const apiKey = "YOUR_API_KEY";
const apiSecret = "YOUR_API_SECRET";
const encodedCredentials = Buffer.from(`${apiKey}:${apiSecret}`).toString('base64');
const customerId = 1

let data = JSON.stringify({
  "memo": "Memo",
  "customerMessage": "Message for customer",
  "customerUserId": 1111,
  "internalNotes": "Internal notes for Merchant reference",
  "invoiceNumber": "INV-NO-001",
  "amount": 0.01,
  "attachment": {
    "name": "Attachment",
    "content": "dGhpcyBpcyBhIHRlc3QgZmlsZSBvbmx5Lgo=",
    "mimeType": "text/plain"
  },
  "frequency": "Weekly",
  "endDate": "2025-01-01",
  "effectiveDate": "2025-01-01",
  "paymentTermValue": 12,
  "externalIdentifier": "ID-001"
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://sandbox-api.securelyme.io/e-bills/create',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': `Basic ${encodedCredentials}`
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Attachments are visible on the Merchant dashboard, while viewing an e-bill or subscription.

🪝 Webhook Responses

Messages to the Webhook occur for various events and some of the events are as follows:

Notification that a payment request for an e-bill has been created

{
  "PaymentExternalIdentifier":null,
  "PaymentRequestId":1234,
  "EventCode":"EBILL_PAYMENT_REQUESTED",
  "EventId":"2b795c1c-6c0b-404a-a60f-f516722dadea",
  "RecurringPaymentId":123456,
  "RecurringPaymentExternalIdentifier":"EBILL-EXTERNAL-ID"
}

A Payment past-due notification:

{
  "PaymentExternalIdentifier":null,
  "PaymentRequestId":1234,
  "EventCode":"PAYMENT_PASTDUE",
  "EventId":"ee719447-3a62-4979-be5d-733b57713d24",
  "RecurringPaymentId":null,
  "RecurringPaymentExternalIdentifier":null
}

A Payment Paid notification:

{
  "PaymentExternalIdentifier":null,
  "PaymentRequestId":1234,
  "EventCode":"PAYMENT_PAID",
  "EventId":"98091873-96f0-485e-9ce2-adba0807df1b",
  "RecurringPaymentId":null,
  "RecurringPaymentExternalIdentifier":null
}

E-Bills

👍
e-Bill vs Subscription

📩 Create an e-Bill

🔠 Managing e-Bill Transactions

🔍 Searching for E-Bills

👍
How does a get Customer notified of an E-Bill

📫 Find the status of an e-Bill that is due

🤵‍♀️ E-Bill Payment Requests

🖇️ Attachment to an e-Bill

🪝 Webhook Responses

👍e-Bill vs Subscription

📩 Create an e-Bill

🔠 Managing e-Bill Transactions

🔍 Searching for E-Bills

👍How does a get Customer notified of an E-Bill

📫 Find the status of an e-Bill that is due

🤵‍♀️ E-Bill Payment Requests

🖇️ Attachment to an e-Bill

🪝 Webhook Responses

👍
e-Bill vs Subscription

👍
How does a get Customer notified of an E-Bill