Integrate a secure, hosted payment iframe into your application powered by Launchpay Orchestrate to accept credit card, Apple Pay, and Google Pay payments. This guide walks you through the full setup process, from generating an access token to handling transaction responses.

Before You Begin

Make sure you have the following:

Your API Key
Your Client ID
Your Location ID
Your iframe URL

Step 1: Generate an Access Token

❗️
Important: This API call must be made from your backend server. Never expose your API key or client ID in client-side code.

Your server must request an access token before loading the iframe. This token authenticates the session and is required in all subsequent steps. Use the Access Token endpoint to generate your token.

Example Request (Node.js)

async function fetchAccessToken() { 
  const url = 'https://sandbox-api-gtw.softpoint.io/locations/' + locationId + '/auth'; 
	
  const params = { 
		api_key: 'your_api_key', 
    client: 'your_client_id' 
  }; 

  const requestOptions = { 
    method: 'POST', 
    headers: { 
      'Content-Type': 'application/json', 
    }, 
    body: JSON.stringify(params),
  }; 

	const response = await fetch(url, requestOptions);
	const data = await response.json();
	return data.accessToken;
}

Example Response

The token expires after the duration specified in expires_in (in seconds). Generate a new token as needed.

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
  "expires_in": 3600
}

Step 2: Add the iframe Script to Your Page

Include the following <script> tag in the <head> of your HTML page. This loads the payment form library and authenticates the session using your access token from Step 1.

<script
  src="[IFRAME_URL]/api/softpointpay?location_id=[LOCATION_ID]&session_key=[ACCESS_TOKEN]">
</script>

Replace the bracketed values:

Placeholder	Value
[IFRAME_URL]	[PLACEHOLDER: your iframe base URL]
[LOCATION_ID]	Your Location ID
[ACCESS_TOKEN]	The access token returned in Step 1

Step 3: Add the iframe Container HTML

Add a <div>with the ID iframeContent inside a <form> element. The iframe library will inject the payment input fields into this div. You control the surrounding layout — header, footer, container styling, and the submit button are all yours to customize.

<div id="containerIframe" class="your-custom-styles">
  <form>
    <!-- Payment fields render here automatically -->
    <div id="iframeContent"></div>

    <!-- Your custom submit button -->
    <div>
      <button id="btnSubmit" class="btn btn-primary" type="submit">
        Pay Now
      </button>
    </div>
  </form>
</div>

Step 4: Initialize the Payment Form

Call initPaymentForm() to render the payment fields inside the iframeContent div. Pass a configuration object to control which fields appear and how the payment is processed.

Configuration Parameters

Parameter	Description	Value
location_id	Location ID
timestamp	Current Unix timestamp -> used for auto-reload	unix timestamp
process_type	Transaction type	tokenize, authorize, sale
payment_methods	Payment methods displayed in the iframe	“credit_card”, “apple_pay”, “google_pay”
include-cardholder	Turn cardholder field on/off	0 or 1 - default = 0
include-street	Turn street field on/of	0 or 1 - default = 0
include-street2	Turn street 2 field on/of	0 or 1 - default = 0
include-zip	Turn zip field on/off	0 or 1 - default = 0
include-email	Turn email field on/of	0 or 1 - default = 0
country_iso	ISO 3166-1 Alpha-2 code	Default = US
currency_iso	ISO 4217 alphabetic code	USD

Example

const conf = {
  "location_id": YOUR_LOCATION_ID,
  "access_token": "your_access_token",
  "process_type": "tokenize",
  "timestamp": Math.floor(Date.now() / 1000),
  "include-cardholder": 1,
  "include-street": 1,
  "include-street2": 1,
  "include-zip": 1,
  "country_iso": "US",
  "currency_iso": "USD"
};

initPaymentForm('iframeContent', conf);

Step 5: Handle Payment Submission

When the user clicks your Submit button, call submitPayment() with the payment details.

Submit Parameters

Parameter	Description	Value
amount	Amount of order or shopping cart to be charged	Example: 20.00
orderid	Unique order ID
user_id	Unique user ID
location_id	Location ID
domain	Domain URL
access_token	Access token
store-card	Tokenize card for later use. Enabled when process_type is tokenize.	0 or 1 - Default = 0, Tokenize Card = 1
phone_number	The user phone number	Example: 7513200000
email	The user email

Example

const form = document.querySelector('form');

form.addEventListener('submit', (event) => {
	event.preventDefault();
  
//Prepare settings
let amount = 10;
const paymentDetails = {
	"location_id": [location_id],
	"access_token": "[your access token]",
	"amount": amount,
	"domain": "https://www.domain.com/",
	"store-card": 1,
	"user_id": "5000",
	"order": {
    "items": [
			{
			"id": "1000",
			"productSKU": "productSKU",
			"name": "Credit",
			"quantity": 1,
			"price": 10.00,
			"tax": 1.00,
			"phone_number": "[optional]"
      }
    ]
  }
}

submitPayment(paymentDetails);
});

Step 6: Handle the Responses

Define the following two callback functions in your page's JavaScript. The iframe calls these automatically after a transaction attempt.

function onApprovedCallback(e) {
  // Handle successful transaction
  console.log('Payment approved:', e);
}

function onDeclinedCallback(e) {
  // Handle failed transaction
  console.log('Payment declined:', e);
}

Support

💬 Have a question? Contact us on the Customer Support Portal.

🔹Learn about updates in our Changelog.