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

<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.

<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 NameDescriptionTypeFormat
clientReferenceThis is the unique transaction reference ID that the merchant generates in their systemOptionalString
clientReference1This is the unique transaction reference ID that the merchant generates in their systemOptionalString
clientReference2This is the unique transaction reference ID that the merchant generates in their systemOptionalString
clientIdThis is a unique ID that identifies a merchant in Convera's ecosystemRequiredString
merchantIdThis is a unique ID that is generated by ConveraRequiredString
merchantSecretThis is a unique secret that is generated by ConveraRequiredString
buyerCanEditBuyer ability to edit populated data points related to buyer or service informationOptionalBoolean
returnUrlThis is a URL that the buyer can be redirected to after completing their paymentOptionalString
buyerInformation passed in payload related to the buyerOptionalBuyer Object
serviceInformation on service the buyer is paying forRequiredService Object

Buyer Object

Field NameDescriptionTypeFormat
idBuyer ID generated by merchantOptionalString
firstNameFirst name of the buyerOptionalString
lastNameLast name of the buyerOptionalString
emailEmail of the buyerOptionalString
addressAddress of the buyerOptionalString
cityCity of the buyerOptionalString
stateState of the buyerOptionalString
countryCountry of the buyerOptionalString
customFieldCustom Field defined by merchantOptionalString

Service Object

Field NameDescriptionTypeFormat
idThis is a unique ID shared by Convera to detail item being paid forRequiredString
amountThis is the amount that the buyer is payingRequiredDecimal (rounded to two decimal places)

Example Payloads

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

{
	"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
		  }
		]
	}
}

Step 4 - White-labeling

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

{
  "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 changes:

<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 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>