Integration Overview

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.spm.convera.com/static/js/main.js

📘

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

Integration Steps

---

Step 1 - Import the Embedded Payments 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

JavaScript

<script src="https://sandbox.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 Payments Solution micro frontend wherever you would like it to render in your site.

JavaScript

<script>
		var DATA_INPUT = '<?xml+version="1.0"+encoding="UTF-8"+standalone="yes"?>\
<paymentInformation>\
    <clientReference>TES90</clientReference>\
    <clientId>1000452465</clientId>\
    <buyerCanEdit>true</buyerCanEdit>\
    <merchantId>0c420d9cae0f4f6f85aaddbde33e8063</merchantId>\
    <merchantSecret>K7jkj12hjhkjbdd</merchantSecret>\
    <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 Payments 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
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

<?xml+version="1.0"+encoding="UTF-8"+standalone="yes"?>
<paymentInformation>
	<clientReference>TES90</clientReference>
	<clientId>1000452465</clientId>
	<buyerCanEdit>true</buyerCanEdit>
  <returnURL>google.com</returnURL>
	<merchantId>0c420d9cae0f4f6f85aaddbde33e8063</merchantId>
	<merchantSecret>K7jkj12hjhkjbdd</merchantSecret>
	<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>

JSON

json

{
	"paymentInformation": {
      "clientReference": "TES90",
      "clientId": 1000452465,
      "buyerCanEdit": true,
    	"returnURL" : "google.com",
      "merchantId": "0c420d9cae0f4f6f85aaddbde33e8063",
      "merchantSecret": "K7jkj12hjhkjbdd",
      "buyer": {
          "id": "STUD9001",
          "firstName": "James",
          "lastName": "Bond",
          "address": "Brooklyn St",
          "city": "London",
          "state": "London",
          "zip": 21121,
          "country": "GBR",
          "email": "[email protected]",
          "customField": 90000
		},
		"service": [
			{
				"id": 100000026090,
				"amount": 100.9
			},
			{
				"id": 100000026091,
				"amount": 10.99
		  }
		]
	}
}