Give Your Customers a Better Experience
Embedded Payment UI is a drop-in payment user interface that runs in your web application to provide a seamless payment experience. The UI securely collects your customer’s payment details and returns a payment token. The payment token can be used with our Web API to make a payment at the desired step in your application’s checkout process.
By default, the payment token is used to make a one-time payment. You can also store it as a payment method for a customer profile. This is useful for businesses that need to keep the payment method on-file for future payments.
Requirements
Your page containing the payment form must be served over secure HTTP. Simply put, your page URL must start with https://.
Setup and Integration / Client Details
Client account details can be specified through payment.customParameters and/or payment.clientAccountProfile.id. If both are given, the values in customParameters will override the values in the client account profile.
In the following JSON request example, the client account details are specified through customParameters:
{"payment":{"customParameters":{"insured_name":"Kade Montoya","policy_number":"12345"},"email":"user@example.com","amount":100,"flow":"CHECKOUT"}}Alternatively stored client account details can also be specified through clientAccountProfile.id, as in the following example:
{
"payment":{
"clientAccountProfile":{
"objectType":"ClientAccountProfile",
"id":"2xuRvV4p3QH-5RAxe6jSLNA"
},
"clientPaymentProfile":{
"objectType":"ClientPaymentProfile",
"id":"2TAGi7Q6wSLGZWvqQyRNTTg"
},
"amount":100.00,
"flow":"CHECKOUT"
}
}Scripts loaded directly from Simply Easier Payments server for PCI compliance.
Do NOT host a copy of the script on your server.
For Sandbox/Test environment:
<script src="https://test.simply-easier-payments.com/PaymentApp/Payment/EmbeddedPayment.js"></script>Decide where to insert the payment UI elements. Create an empty DOM container element within your payment form and assign it a unique ID.
For example:
<form id="your-form" method="post" action="your_server_side_action">
<div id="payment-panel " />
<button type="submit">Make Payment</button>
</form>Initialize the script with your API Public Key and the Access Token returned from the previous API request. Update your form submission to request a checkout token and send it to your server.
In the following example, the checkout token is submitted in a hidden form field. Your implementation may differ depending on your server environment.
<script type="text/javascript">
SEP.setup({
apiKey : "your_api_public_key",
mount : "payment-panel"
accessToken : "at_1-qUWJAIRVJlUok-IzaSxiF2dNZxq8K9YS4KHvHoui8VB19pro1DYIIlBx1kLI1B"
});
var form = document.getElementById("your-form");
form.addEventListener("submit", function(event) {
event.preventDefault();
SEP.createToken(function(result) {
if (result.errors) {
showErrors(result);
} else {
// Submit the token to your server.
var hiddenInput = document.createElement('input');
hiddenInput.setAttribute('type', 'hidden');
hiddenInput.setAttribute('name', 'sepPaymentToken');
hiddenInput.setAttribute('value', result.paymentToken.tokenString);
form.appendChild(hiddenInput);
form.submit();
}
});
});
</script>Example 1: Making A Payment
Once the checkout token has been submitted to your server, use Payment API executePayment method with checkoutToken property to make a payment.
JSON Request:
{"checkoutToken":"pt_Bt1f4_pppOidi8bMPjCIpWnSFnwwzOmiHVQ2B79G1C-zZSHfQfhAxZzg9ZqKWpkP"}JSON Response:
{"transaction":{"resultCode":"APPROVED","transNumber":"885-0_2","referenceNumber":"61136ec9-b0c3-48f5-8bab-c5e66942d0cf","paidBy":"M","timeMs":1554385573352},"httpStatusCode":200}Example 2: Storing Payment Methods
The payment token has a short expiration time and is limited to one-time use. To store the collected payment information for long-term use, you can use Client API createPaymentMethod method to store the token as a payment method for a client. This allows you to charge the client later using one of the other API methods, without having to ask for the payment method again.
clientAccountProfileId is required and specifies the client for which to create the payment method.
paymentToken specifies the customer’s payment instrument (i.e. Credit Card/ACH) details, which can be collected using Embedded Payment Form integration flow.
For ACH, instead of paymentToken, you have the option to specify the ACH account details directly through clientPaymentProfile.fundingInstrument.
Request:
POST /v1/ClientSrv/createPaymentMethod
Content-Type: application/json
Accept: application/json
Authorization: ...
{
"clientAccountProfileId" : "2phvdiSG_QBenPe2hpGVtTw",
"paymentToken" : "pt_pYJeOCxLsZrpEW5eWqLknfWBd9F4RDo02ML8Bn8pv09RCOqofahBSIhZ9u9Aoc9b"
}Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"httpStatusCode" : 200,
"clientPaymentProfile" : {
"objectType" : "ClientPaymentProfile",
"id" : "2HndO6mHZTY-trtMWuH0Ipw"
}
}The checkout process described above requires a predetermined payment amount. It is not suitable if you need to store a payment method in advance. You can create a payment token without using the checkout flow with a few simple modifications to the script setup.
First, you can skip the step creating the payment session. There is no need to call Payment API getEmbeddedPaymentPage method.
Initialize the script with your API Public key (without Access Token) and mount the payment UI elements. Update your form submission flow to request a payment token and send it to your server.
In the following example, the token is submitted in a hidden form field. Your implementation may differ depending on your server environment.
<script type="text/javascript">
SEP.setup({
apiKey : "your_api_public_key",
mount : "payment-panel"
});
var form = document.getElementById("your-form");
form.addEventListener("submit", function(event) {
event.preventDefault();
SEP.createToken(function(result) {
if (result.errors) {
showErrors(result);
} else {
// Submit the token to your server.
var hiddenInput = document.createElement('input');
hiddenInput.setAttribute('type', 'hidden');
hiddenInput.setAttribute('name', 'sepPaymentToken');
hiddenInput.setAttribute('value', result.paymentToken.tokenString);
form.appendChild(hiddenInput);
form.submit();
}
});
});
</script>These examples pull from our full developer library available to help you get started and optimize your payment proceses.