Guides

One-Time Payment

Ad-hoc payment for goods or services

Suggest Edits

💸Request a One-Time Payment Request

Securely.io provides a comprehensive suite of payment solutions to streamline your business transactions. We offer one-time payments for ad-hoc purchases, subscription payments for recurring fees, and e-bill payments for convenience.

Identify a Securely.io Customer

To initiate a one-time payment request, it's crucial to identify the customer using their unique Securely.io customer ID. This ensures accurate payment processing.

One-time payments process

The one-time payment process involves two steps:

  • Payment Request: Initiate a payment request for a specific customer through Securely.io API
  • Payment URL Request: Initiate a request to generate a URL with which a customer can make a payment

Step 1: Payment Request

securelyApiKey="YOUR_SECURELY_API_KEY"
securelyApiSecret="YOUR_SECURELY_API_SECRET"

amount=100
message="payment for services"
internalNotes="from myApp"
invoiceNumber="1000"
externalIdentifier="1001"
customerUserID="securelyCustomerId"
sendNotice="true"
sendReceipt="true"

data="{
  \"amount\": $amount,
  \"message\": \"$message\",
  \"internalNotes\": \"$internalNotes\",
  \"invoiceNumber\": \"$invoiceNumber\",
  \"externalIdentifier\": \"$externalIdentifier\",
  \"customerUserID\": \"$customerUserID\",
  \"sendNotice\": $sendNotice,
  \"sendReceipt\": $sendReceipt
}"

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

curl -X POST \
  https://sandbox-api.securelyme.io/payment-requests/one-time \
  -H "Authorization: Basic $authorization" \
  -H "Content-Type: application/json" \
  -d "$data"

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

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://sandbox-api.securelyme.io/customers/import");
request.Headers.Add("Authorization", $"Basic {encodedCredentials}");
request.Headers.Add("Accept", "application/json");

var jsonData = @"""{
					  ""amount"": $amount,
					  ""message"": ""$message"",
					  ""internalNotes"": ""$internalNotes"",
					  ""invoiceNumber"": ""$invoiceNumber"",
					  ""externalIdentifier"": ""$externalIdentifier"",
					  ""customerUserID"": ""$customerUserID"",
					  ""sendNotice"": $sendNotice,
					  ""sendReceipt"": $sendReceipt
					}""";
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({
  "amount": 2.00,
  "message": "message",
  "internalNotes": "internal nodes",
  "invoiceNumber": "invoices_number",
  "externalIdentifier": "external_identifier",
  "customerUserId": customer_id,
  "sendNotice": true,
  "sendReceipt": true
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://sandbox-api.securelyme.io/payment-requests/one-time',
  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 call, when successful, will return a Payment Request Id

API reference: Create and send a one-time payment request.

Step 2: Payment URL Request

securelyApiKey="YOUR_SECURELY_API_KEY"
securelyApiSecret="YOUR_SECURELY_API_SECRET"

redirectUrl="http://myapp.com/acceptpayment"
confirmationMessage="Thank you! Your service has been funded!"
continueButtonText="Return to myApp"
expiresIn="$(( $(date +%s) + 86400 ))"  # Set expiresOn to 24 hours from now

data="{
  \"redirectUrl\": \"$redirectUrl\",
  \"confirmationMessage\": \"$confirmationMessage\",
  \"continueButtonText\": \"$continueButtonText\",
  \"expiresIn\": $expiresIn
}"

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

curl -X POST \
  https://sandbox-api.securelyme.io/payment-requests/urls \
  -H "Authorization: Basic $authorization" \
  -H "Content-Type: application/json" \
  -d "$data"

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

var paymentRequestId = 1;
var client = new HttpClient();
var request = new HttpRequestMessage(
  										HttpMethod.Post,
  										$"https://sandbox-api.securelyme.io/payment-requests/{paymentRequestId}/urls");
request.Headers.Add("Authorization", $"Basic {encodedCredentials}");

var jsonData = @"{
				  {
				  ""redirectUrl"": ""https://myapp.example.com/payment-scheduled"",
				  ""confirmationMessage"": ""Thank you! Your request is funded."",
				  ""continueButtonText"": ""Continue to myapp.example"",
				  ""expiresIn"": " + DateTime.Now.AddDays(1).ToString("yyyy-MM-ddTHH:mm:ssZ")
				}"
var content = new StringContent(jsonData, null, "application/json");
request.Content = content;

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 paymentRequestId = 1;

let data = JSON.stringify({
  \"redirectUrl\": \"$redirectUrl\",
  \"confirmationMessage\": \"$confirmationMessage\",
  \"continueButtonText\": \"$continueButtonText\",
  \"expiresIn\": $expiresIn
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: `https://sandbox-api.securelyme.io/payment-requests/${paymentRequestId}/urls`,
  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);
});

API reference: Create a URL that can be used to view the payment request by a customer

This call, when successful, should return a URL to Securely.io. Redirect the user to this URL and allow them to make a payment.

Alternatively, users could receive a payment link via email or SMS messages from Securely.io, if requested in the one-time payment request.

After successful payment or cancellation, Securely.io will redirect the user to the redirectUrl, which will take the user back to the application that requested payment.

🔗 URL's to Pay a Payment Request

When a merchant makes a Payment Request, Securely.io can generate short URL's that a customer could use to get to make a payment with their chosen method (Digital Currency or Payment Card).

The following API call retrieves all the short URL's associated with a payment request:

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

curl -X GET \
--location 'https://sandbox-api.securelyme.io/payment-requests/{paymentRequestId}/urls?includeExpired=true' \
-H "Authorization: Basic $authorization" \
-H "Content-Type: application/json" 

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

var client = new HttpClient();
var request = new HttpRequestMessage(
  HttpMethod.Get, 
  $"https://sandbox-api.securelyme.io/payment-requests/{paymentRequestId}/urls?includeExpired=true");
request.Headers.Add("Authorization", $"Basic {encodedCredentials}");

request.Content = new StringContent("", null, "text/plain");
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 paymentRequestId = 1;

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: `https://sandbox-api.securelyme.io/payment-requests/${paymentRequestId}/urls?includeExpired=true`,
  headers: { 
    'Accepts': 'application/json', 
    'Authorization': `Basic ${encodedCredentials}`
  },
  data : ''
};

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

The response will contain all a list of all the URL's generated for the given payment request.

API reference: Get the short URLs that are tied to the payment request

📜Transactions tied to a Payment Request

Securely.io has the ability to provide a list of all transactions (successful, cancelled, failed) associated to a Payment Request Id. 

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

curl -X GET \
--location 'https://sandbox-api.securelyme.io/payment-requests/{paymentRequestId}/transactions' \
-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 paymentRequestId = 1;

var client = new HttpClient();
var request = new HttpRequestMessage(
  HttpMethod.Get, 
  $"https://sandbox-api.securelyme.io/payment-requests/{paymentRequestId}/transactions");
request.Headers.Add("Authorization", $"Basic {encodedCredentials}");
request.Headers.Add("Accept", "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 paymentRequestId = 1;

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: `https://sandbox-api.securelyme.io/payment-requests/${paymentRequestId}/transactions`,
  headers: { 
    'Accepts': 'application/json', 
    'Authorization': `Basic ${encodedCredentials}`
  }
};

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

The output of this endpoint can help with transaction tracking, provide better customer service and with Financial analysis. It may also help Merchants with Fraud Detection.

Having a comprehensive list of transactions empowers you to make informed decisions, optimize your business operations, and provide exceptional customer service.

API Reference: Get the transactions tied to the payment request.

ℹ️ Discover the status of a Payment Request

Securely.io offers complete transparency into your payment requests. Simply provide the Payment Request Id, and you'll receive a wealth of information about the request's current state and progress.

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

curl -X GET \
--location 'https://sandbox-api.securelyme.io/payment-requests/{paymentRequestId}' \
-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 paymentRequestId = 1;

var client = new HttpClient();
var request = new HttpRequestMessage(
  HttpMethod.Get, 
  $"https://sandbox-api.securelyme.io/payment-requests/{paymentRequestId}");
request.Headers.Add("Authorization", $"Basic {encodedCredentials}");
request.Headers.Add("Accept", "application/json");

var content = new StringContent("", null, "application/json");
request.Content = content;

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 payementRequestId = 1;

let config = {
  method: 'get',
  url: `https://sandbox-api.securelyme.io/payment-requests/${paymentRequestId}`,
  headers: { 
    'Accepts': 'application/json', 
    'Authorization': `Basic ${encodedCredentials}`
  },
  data : data
};

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

The response will identify the status code of the request, which could include: SENT, VIEWED, DELETED, CANCELLED, PAYMENTREJECTED, ERROR, PAID, PENDINGREFUND, REFUNDED, ACCEPTED, EXPIRED, PARTIALREFUND, PASTDUE

By understanding the different status codes and comprehensive information provided by Securely.io, you can effectively manage your payment requests and stay informed about their progress.

API Reference: Get a payment request.

🔎Search for Payment Requests

Securely.io empowers you to effortlessly find specific payment requests with its advanced search functionality. Utilize a wide range of criteria like invoice numbers, status codes, customer details, and even creation dates.

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

curl -X POST \
--location 'https://sandbox-api.securelyme.io/payment-requests/search' \
-H 'Content-Type: application/json' \
-H "Authorization: Basic $authorization" 
--data '{
   "createdFromDate": "2024-01-01",
   "createdToDate": "2024-12-10",
   "invoiceNumber": "1001",
   "statusCodes": ["SENT", "VIEWED"],
   "pageSize": 20,
   "page": 1
}'

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

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

var jsonData = @"{
                   ""createdFromDate"": ""2024-09-01"",
                   ""createdToDate"": ""2024-09-30"",
                   ""pageSize"": 20,
                   ""page"": 1
                }";
var content = new StringContent(jsonData, null, "application/json");
request.Content = content;

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-09-01",
  "createdToDate": "2024-09-30",
  "pageSize": 20,
  "page": 1
});

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

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

The intuitive API response delivers a neatly paginated list of matching requests, along with their current status. This streamlined approach simplifies payment request management, saving you valuable time and effort.

API Reference: Search payment requests.

🗑️Void or Cancel a Payment Request

Securely.io empowers merchants with the ability to void payment requests with a Payment Request Id. This functionality provides flexibility and control when unforeseen circumstances prevent service completion.

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

curl --request PUT \
--location  'https://sandbox-api.securelyme.io/payment-requests/{paymentRequestId}/void' \
-H "Authorization: Basic $authorization" 

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

var client = new HttpClient();
var request = new HttpRequestMessage(
  HttpMethod.Put, 
  $"https://sandbox-api.securelyme.io/payment-requests/{paymentRequestId}/void");
request.Headers.Add("Authorization", $"Basic {encodedCredentials}");
request.Headers.Add("Accept", "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 paymentRequestId = 1;

let config = {
  method: 'put',
  maxBodyLength: Infinity,
  url: `https://sandbox-api.securelyme.io/payment-requests/${paymentRequestId}/void`,
  headers: { 
    'Accepts': 'application/json', 
    'Authorization': `Basic ${encodedCredentials}`
  },
  data:''
};

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

Overall, Securely.io payment request voiding feature facilitates a smoother customer service experience by enabling proactive issue resolution.

API Reference: Void a payment request.

🪝Webhook Events

A Webhookis registered with Securely.io (Settings > Integrations > Webhooks) and a secret key is generated. After a transaction is processed, Securely.io invokes the Webhook for every event that occurs on the payment request.

Events include the follow:

  • PAYMENT_REQUESTED: A payment request is sent to a customer.
  • PAYMENT_PAID: A payment request has received a successful payment. Note: Funds have not been received. This is equivalent to a credit card authorization.
  • PAYMENT_FINALIZED: A successful payment has been finalized. The funds are available and will be included in the next Bank Transfer.
  • PAYMENT_CANCELLED_BY_CUSTOMER : The customer declined (cancelled/deleted) a payment request. This can only occur if the payment request has not been paid.
  • PAYMENT_CANCELLED_BY_MERCHANT : The merchant declined (cancelled/deleted) a payment request. This can only occur if the payment request has not been paid.
  • PAYMENT_FAILED : An initially successful payment attempt has failed. This occurs due to ACH Returns, Chargebacks, and other potential failure pathways. This event is reserved for payments that received a successful authorization but failed after.

📘

The use of webhooks is highly recommended

Here are some examples of messages to the Webhook:
When payment is made by the customer for a one-time payment:

{
  "PaymentExternalIdentifier":"ONE-TIME-PAYMENT-REQUEST-EXTERNAL-IDENTIFIER",
  "PaymentRequestId":1,
  "EventCode":"PAYMENT_PAID",
  "EventId":"fe8c6617-df1c-4be7-aa04-70f839ed7731",
  "RecurringPaymentId":null,
  "RecurringPaymentExternalIdentifier":null
}

When a one-time payment is cancelled by the customer:

{
  "PaymentExternalIdentifier":"ONE-TIME-PAYMENT-EXTERNAL-IDENTIFIER",
  "PaymentRequestId":1,
  "EventCode":"PAYMENT_CANCELLED_BY_CUSTOMER",
  "EventId":"3d24dcc8-cbcc-482c-975c-5986ef6bd3f3",
  "RecurringPaymentId":null,
  "RecurringPaymentExternalIdentifier":null
}

Updated 11 months ago