Environments

Convera provides a fully integrated sandbox environment which allows you to test your integration. The sandbox environment will have all the features and functionality that are available in the production environment.

📘
Sandbox : https://sandbox-uat.spm.convera.com/static/js/main.js

📘
Production: https://paymentmodule.convera.com/static/js/main.js

Integration Steps

Step 1 - Import the Embedded Payment Solution SDK

Using the below statement, import the Embedded Solution SDK.

Convera recommends loading the JavaScript SDK from the CDN URL rather than saving the JavaScript locally

<script src="https://sandbox-uat.spm.convera.com/static/js/main.js"></script>

Step 2 - Initiate Script

Once imported, the script needs to be initiated by passing the merchantID and merchantSecret to the custom UI element as an attribute.

The merchant specific merchantID and merchantSecret are generated by Convera

Place the custom UI element for the Embedded Payment Solution micro frontend wherever you would like it to render in your site.

<script>
		var DATA_INPUT = '<?xml+version="1.0"+encoding="UTF-8"+standalone="yes"?>\
<paymentInformation>\
    <clientReference>Ref1</clientReference>\
    <clientReference1>Ref2</clientReference1>\
    <clientReference2>Ref3</clientReference2>\
    <clientId>1000452465</clientId>\
    <merchantId>0c420d9cae0f4f6f85aaddbde33e8063</merchantId>\
    <merchantSecret>K7jkj12hjhkjbdd</merchantSecret>\
    <buyerCanEdit>true</buyerCanEdit>\    
    <returnUrl>https://www.google.com</returnUrl>\
      <buyer>\
        <id>STUD9001</id>\
        <firstName>James</firstName>\
        <lastName>Bond</lastName>\
        <address>Brooklyn St</address>\
        <city>London</city>\
        <state>London</state>\
        <zip>21121</zip>\
        <country>GBR</country>\
        <email>[email protected]</email>\
        <customField>90000</customField>\
		</buyer>\
		<service>\
        <id>100000026090</id>\
        <amount>100.90</amount>\
		</service>\
				<service>\
        <id>100000026091</id>\
        <amount>10.99</amount>\
		</service>\
</paymentInformation>'
    let sellerInfo = `<convera-payment data-seller-info='${DATA_INPUT}'></convera-payment>`
    $('#sellerInput').html(sellerInfo);
</script>

Step 3 - Passing Custom Objects

The Embedded Payment Solution accepts data on the payment, buyer and service. This information will be passed and propagated to relevant fields to inform required and optional data points.

Payment Information: Data specific to the client configuration
Buyer Information: Data on the user the payment is being made by or on behalf of (ex. Student)
Service Information: Data on the fee the buyer is paying for (ex. Type of fee and amount)

Payment Information Object

Field Name	Description	Type	Format
clientReference	This is the unique transaction reference ID that the merchant generates in their system	Optional	String
clientReference1	This is the unique transaction reference ID that the merchant generates in their system	Optional	String
clientReference2	This is the unique transaction reference ID that the merchant generates in their system	Optional	String
clientId	This is a unique ID that identifies a merchant in Convera's ecosystem	Required	String
merchantId	This is a unique ID that is generated by Convera	Required	String
merchantSecret	This is a unique secret that is generated by Convera	Required	String
buyerCanEdit	Buyer ability to edit populated data points related to buyer or service information	Optional	Boolean
returnUrl	This is a URL that the buyer can be redirected to after completing their payment	Optional	String
buyer	Information passed in payload related to the buyer	Optional	Buyer Object
service	Information on service the buyer is paying for	Required	Service Object

Buyer Object

Field Name	Description	Type	Format
id	Buyer ID generated by merchant	Optional	String
firstName	First name of the buyer	Optional	String
lastName	Last name of the buyer	Optional	String
email	Email of the buyer	Optional	String
address	Address of the buyer	Optional	String
city	City of the buyer	Optional	String
state	State of the buyer	Optional	String
country	Country of the buyer	Optional	String
customField	Custom Field defined by merchant	Optional	String

Service Object

Field Name	Description	Type	Format
id	This is a unique ID shared by Convera to detail item being paid for	Required	String
amount	This is the amount that the buyer is paying	Required	Decimal (rounded to two decimal places)

Example Payloads

XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<paymentInformation>
	<clientReference>Ref1</clientReference>
	<clientReference1>Ref2</clientReference1>
	<clientReference2>Ref3</clientReference2>
	<clientId>1000455637</clientId>
  <merchantId>ae16e6bde2ba480eb579f6ba55f17aea</merchantId>
	<merchantSecret>7f8cd9c3b4f747569f9b5c1982da0982</merchantSecret>
  <buyerCanEdit>false</buyerCanEdit>
  <returnUrl>https://www.google.com</returnUrl>
	<buyer>
		<id>TES999</id>
		<firstName>James</firstName>
		<lastName>Bond</lastName>
    <address>Brooklyn St</address>
    <city>London</city>
    <state>London</state>
    <zip>21121</zip>
		<country>GBR</country>
		<email>[email protected]</email>
		<customField>test</customField>
		<customField>custom 2</customField>
		<customField>custom 3</customField>
		<customField>custom 4</customField>
	</buyer>
	<service>
		<id>100000047642</id>
		<amount>200</amount>
	</service>
</paymentInformation>

JSON

{
	"paymentInformation": {
		"clientReference": "Ref1",
		"clientReference1": "Ref2",
		"clientReference2": "Ref3",
		"clientId": "1000455637",
    "merchantId": "ae16e6bde2ba480eb579f6ba55f17aea",
		"merchantSecret": "7f8cd9c3b4f747569f9b5c1982da0982",
    "buyerCanEdit": "false",
    "returnUrl': "https://www.google.com",
		"buyer": {
			"id": "TES999",
			"firstName": "James",
			"lastName": "Bond",
			"address": "Brooklyn",
			"city": "London",
			"state": "London",
			"zip": "43223",
			"country": "GBR",
			"email": "[email protected]",
			"customField": [
				"test",
				"custom 2",
				"custom 3",
				"custom 4"
			]
		},
		"service": {
			"id": "100000047642",
			"amount": "200"
		}
	}
}

White-labeling

The Embedded Payment Solution can be fully customized to align with your company's branding and design guidelines, ensuring consistency with your brand image.

Sample including theme:

{
  "primaryColor": "#ff595e",
  "secondaryColor": "#6a4c93",
  "accentColors": [
    "#ff595e",
    "#6a4c93",
    "#2133AF"
  ],
  "warningColor": "#6a4c93",
  "primaryButtonColor": "\"Jersey 10\", sans-serif",
  "fontName": "\"Jersey 10\", sans-serif",
  "fontUrl": "https://fonts.googleapis.com/css2?family=Jersey+10&display=swap"
}

Sample including theme:

<script>
    var DATA_INPUT = '<?xml+version="1.0"+encoding="UTF-8"+standalone="yes"?>\
<paymentInformation>\
	<clientReference>TES90</clientReference>\
	<clientId>1000452465</clientId>\
  <merchantId>0c420d9cae0f4f6f85aaddbde33e8063</merchantId>\
  <merchantSecret>K7jkj12hjhkjbdd</merchantSecret>\	
  <buyerCanEdit>true</buyerCanEdit>\
  <returnUrl>https://www.google.com</returnUrl>\
	<buyer>\
		<id>STUD9001</id>\
		<firstName>James</firstName>\
		<lastName>Bond</lastName>\
		<address>Brooklyn St</address>\
		<city>London</city>\
		<state>London</state>\
		<zip>21121</zip>\
		<country>GBR</country>\
		<email>[email protected]</email>\
		<customField>90000</customField>\
	</buyer>\
	<service>\
		<id>100000026090</id>\
		<amount>100.90</amount>\
	</service>\
		<service>\
		<id>100000026091</id>\
		<amount>10.99</amount>\
	</service>\
</paymentInformation>';
    let themeInfo=JSON.stringify({"primaryColor":"#ff595e","secondaryColor":"#6a4c93","accentColors":["#ff595e","#6a4c93","#2133AF"],"warningColor":"#6a4c93","primaryButtonColor":"\"Jersey 10\", sans-serif","fontName":"\"Jersey 10\", sans-serif","fontUrl":"https://fonts.googleapis.com/css2?family=Jersey+10&display=swap"});
    let sellerInfo = `<convera-payment data-seller-info='${DATA_INPUT}' data-theme='${themeInfo}'></convera-payment>`
    $('#sellerInput').html(sellerInfo);
</script>

Passing Locale

Sample including locale:

Locale Code	Language
en_GB	English
fr_FR	French

<script>
    var DATA_INPUT = '<?xml+version="1.0"+encoding="UTF-8"+standalone="yes"?>\
<paymentInformation>\
	<clientReference>TES90</clientReference>\
	<clientId>1000452465</clientId>\
  <merchantId>0c420d9cae0f4f6f85aaddbde33e8063</merchantId>\
  <merchantSecret>K7jkj12hjhkjbdd</merchantSecret>\
  <buyerCanEdit>true</buyerCanEdit>\
  <returnUrl>https://www.google.com</returnUrl>\
	<buyer>\
		<id>STUD9001</id>\
		<firstName>James</firstName>\
		<lastName>Bond</lastName>\
		<address>Brooklyn St</address>\
		<city>London</city>\
		<state>London</state>\
		<zip>21121</zip>\
		<country>GBR</country>\
		<email>[email protected]</email>\
		<customField>90000</customField>\
	</buyer>\
	<service>\
		<id>100000026090</id>\
		<amount>100.90</amount>\
	</service>\
		<service>\
		<id>100000026091</id>\
		<amount>10.99</amount>\
	</service>\
</paymentInformation>';
    let themeInfo=JSON.stringify({"primaryColor":"#ff595e","secondaryColor":"#6a4c93","accentColors":["#ff595e","#6a4c93","#2133AF"],"warningColor":"#6a4c93","primaryButtonColor":"\"Jersey 10\", sans-serif","fontName":"\"Jersey 10\", sans-serif","fontUrl":"https://fonts.googleapis.com/css2?family=Jersey+10&display=swap"});
    let sellerInfo = `<convera-payment data-seller-info='${DATA_INPUT}' data-theme='${themeInfo}' data-locale="fr_FR"></convera-payment>`
    $('#sellerInput').html(sellerInfo);
</script>

Custom Event Listener

A custom event listener allows your system to monitor specific events as they occur. By adding the event listener code when integrating the embedded payment solution, your system can respond to custom events in real time, enabling dynamic actions to handle user interactions seamlessly.

<script>
    var DATA_INPUT = '<?xml+version="1.0"+encoding="UTF-8"+standalone="yes"?>\
<paymentInformation>\
	<clientReference>TES90</clientReference>\
	<clientId>1000452465</clientId>\
  <merchantId>0c420d9cae0f4f6f85aaddbde33e8063</merchantId>\
  <merchantSecret>K7jkj12hjhkjbdd</merchantSecret>\
	<buyerCanEdit>true</buyerCanEdit>\
  <returnUrl>https://www.google.com</returnUrl>\
  <buyer>\
		<id>STUD9001</id>\
		<firstName>James</firstName>\
		<lastName>Bond</lastName>\
		<address>Brooklyn St</address>\
		<city>London</city>\
		<state>London</state>\
		<zip>21121</zip>\
		<country>GBR</country>\
		<email>[email protected]</email>\
		<customField>90000</customField>\
	</buyer>\
	<service>\
		<id>100000026090</id>\
		<amount>100.90</amount>\
	</service>\
		<service>\
		<id>100000026091</id>\
		<amount>10.99</amount>\
	</service>\
</paymentInformation>';

  let converaPayment = document.createElement('convera-payment');
  converaPayment.setAttribute('data-seller-info', DATA_INPUT );
  converaPayment.setAttribute('data-payment-events-enabled', "true");
 
  // Name of the Custom event - converaEvent  
  converaPayment.addEventListener('converaEvent', (event) => {
      console.log('event received:', event); //  event JSON object
   });

</script>

Event Object

Event	Description
Redirect	Event is triggered when payer clicks on 'Return to Homepage' button on receipt pages
Session_Expiry	Event is triggered when payer session has timed out

Structure of Event Object

{ 
 source: 'EPS_CONVERA',
 timestamp: string
 paymentMethod: string, //(optional, may be null)
 clientRef: string
 eventName: "REDIRECT" or "SESSION_EXPIRY"
}

Integration Overview

📘
Sandbox : https://sandbox-uat.spm.convera.com/static/js/main.js

📘
Production: https://paymentmodule.convera.com/static/js/main.js

Step 1 - Import the Embedded Payment Solution SDK

Step 2 - Initiate Script

Step 3 - Passing Custom Objects

Example Payloads

White-labeling

Passing Locale

Custom Event Listener

📘Sandbox : https://sandbox-uat.spm.convera.com/static/js/main.js

📘Production: https://paymentmodule.convera.com/static/js/main.js

Step 1 - Import the Embedded Payment Solution SDK

Step 2 - Initiate Script

Step 3 - Passing Custom Objects

Example Payloads

White-labeling

Passing Locale

Custom Event Listener

📘
Sandbox : https://sandbox-uat.spm.convera.com/static/js/main.js

📘
Production: https://paymentmodule.convera.com/static/js/main.js