S/MIME certificate

Endpoint: !PlaceOrder

https://secure.trust-provider.com/products/!PlaceOrder

For GET requests, submit parameters in the query string.

For POST requests, submit parameters in application/x-www-form-urlencoded format.

Request parameters

The following table displays the required, optional, and conditional parameters.

Parameter Requirement Type Max.Length Description

Reseller details

ap

required

string

64 chars

The Reseller brand name.

reseller

required

char

Specifies who charges the end-customer for the order.

The allowed values are:

  • Y — You will charge the end-customer. Sectigo will then debit your account funds.

  • N — Sectigo will charge the end-customer.

errorURL

optional

string

255 chars

A URL the browser will be redirected to if an error occurs.

successURL

optional

string

255 chars

A URL the browser will be redirected to if the order is placed successfully.

region

optional

string

64 chars

The region of the world the order is being placed from.

If omitted, the value defaults to Unknown.

isReturningCustomer

optional

char

Specifies whether the customer placing the order is new or already in the system.

The allowed values are:

  • Y — This customer already has an account.

  • N — This is a new customer.

This parameter is only relevant when loginName and loginPassword are being used.

product

optional

string

A comma-separated list of product codes. This is used by the Ordering URLs page, to allow you and your customers to place orders interactively, without the need to 'integrate' this API endpoint into your website.

offerCode

optional

string

64 chars

Specifies values related to offers and provided in cases of special pricing or when extra products are added.

The allowed values are:

  • FREE_EV_UPGRADE

  • FREE_EV_UPGRADE_REQUIRED

  • EVSSLPREREGISTRATIONOFFER

  • FREE_HP_UPGRADE

Company address details

Many products do not require an address to be specified. In cases where it is required, a state or province name may be omitted if LocalityName is specified, and vice versa.

For returning customers, any address details supplied here will replace any details supplied on previous occasions.

organizationName

optional

string

64 chars

The organization name.

organizationalUnitName

optional

string

64 chars

The organizational unit name.

postOfficeBox

optional

string

40 chars

The organization post office box.

streetAddress1

optional

string

128 chars

The street address where the organization operates.

streetAddress2

optional

string

128 chars

The second part of the company’s street address (if necessary).

streetAddress3

optional

string

128 chars

The third part of the company’s street address (if necessary).

localityName

optional

string

128 chars

The city in which the organization operates.

stateOrProvinceName

optional

string

128 chars

The state or province in which the organization operates.

postalCode

optional

string

40 chars

The company’s postal code.

countryName or country

optional

string

2 chars

The ISO 3166 two-character code for the country where the organization operates.

If omitted, the value defaults to US.

Other company details

dunsNumber

optional

string

20 chars

A unique nine-digit identifier for businesses, provided by the company Dun & Bradstreet.

companyNumber

optional

string

64 chars

The company registration number.

BusinessCategory

optional

char

1 char

The legal classification of the organization.

The allowed values are:

  • b — Private

  • c — Government

  • d — Business Entity

x_organizationIdentifier

optional

string

100 chars

The organization identifier, or the PSD2 Authorization Identifier recognized by the National Competent Authority (NCA).

This parameter is required for S/MIME Organization-Validated Multipurpose certificates

User personal details

title

optional

string

64 chars

The customer’s title (for example, Mr, Mrs, Dr, etc).

name

conditional

string

128 chars

The customer’s full name.

If foreName or surName are specified, name is not required.

foreName

conditional

string

64 chars

The customer’s first name.

If name is specified, foreName and surName are not required.

surName

conditional

string

64 chars

The customer’s last name.

If name is specified, foreName and surName are not required.

emailAddress

required

string

255 chars

The customer’s email address.

If isReturningCustomer is not specified, the system determines the customer type as follows:

  • Presence of emailAddress indicates a new customer.

  • Absence of emailAddress indicates a returning customer.

telephoneNumber

optional

string

32 chars

The customer’s telephone number.

faxNumber

optional

string

32 chars

The customer’s fax number.

User login details

loginName

required

string

64 chars

Your account username.

This value is case sensitive.

loginPassword

required

string

128 chars

Your account password.

This value is case sensitive.

Various parameters are required that define the product(s) being purchased. These vary considerably depending on the product(s).

The following table outlines a sample of the types of x_parameters.

The x in the following parameters is a placeholder for an integer indicating the item number. This allows multiple items to be purchased in a single order, so it should be possible to integrate this with shopping cart systems.

The first 'item number' is 1, the second 'item number' is 2 and so on. This means that either 1_ID or 1_PPP must be specified, because there must be at least one item in the order.

You may prepend an underscore to any of the x_parameters. This will be necessary if you need to reference such parameters in Javascript, because Javascript variables may not begin with a digit.

Parameter Requirement Type Max.Length Description

x_ID

conditional

integer

A product ID.

Some products require this parameter to be specified instead of x_PPP.

x_PPP

conditional

integer

A product pricing parameter.

Some products require this parameter to be specified instead of x_ID.

x_visibility

optional

integer

Specifies the visibility of the product in the control panel.

The allowed values are:

  • -1 (default) — Visible.

  • 0 — Invisible.

x_days

conditional

integer

The number of days.

Its necessity is determined by the specific product.

x_seats, x_users, x_servers, x_quantity

required

integer

Indicates a quantity that affects the pricing.

This parameter is named depending on the product.

x_zones

required

integer

Indicates another quantity that affects the pricing.

This parameter is named depending on the product.

x_smimeEmailAddresses

optional

string

255 chars

The email address(es) that are to be included in the Subject Alternative Names field of the resulting certificate.

x_smimeSubjectCN

optional

char

1 char

Specifies in the organization-validated S/MIME certificate request whether to include the organization name in the Common Name field of the certificate subject.

The allowed values are:

  • Y — The organization name will be included in the Common Name field of the certificate subject.

  • N — No Common Name will be included in the certificate subject.

x_smimeSubjectEmail

optional

string

255 chars

Specifies whether to include the email address in the certificate subject.

x_csr

required

string

32767 chars

The Base64-encoded certificate signing request (CSR), with or without the -----BEGIN xxxxx----- and -----END xxxxx----- header and footer.

For more information, see Certificate Signing Request.

An account can contain multiple email templates for the S/MIME certificate orders and/or provisioning of missing shipping details. Contact Support when needed.

When configured, the following parameters can be included in the request to identify the email template to be used.

Parameter Requirement Type Max.Length Description

SMIMEVerificationTemplateID

optional

integer

The S/MIME verification email templates.

SMIMEVerificationTemplateID prevails over languageName if both of these parameters are provided.

SMIMERequestTemplateID

optional

integer

The S/MIME request email templates.

SMIMERequestTemplateID prevails over languageName if both of these parameters are provided.

SMIMECollectionTemplateID

optional

integer

The S/MIME collection email templates.

SMIMECollectionTemplateID prevails over languageName if both of these parameters are provided.

shippingTemplateID

optional

integer

The shipping details email templates.

shippingTemplateID prevails over languageName if both of these parameters are provided.

languageName

optional

string

2 chars

Specifies the two-character code of the language for S/MIME emails.

An account can contain multiple email templates in different languages for S/MIME emails.

Contact Support for the email templates.

There may be exactly one of the following values specified:

  • en — English

  • zh — Chinese-Mandarin

  • da — Danish

  • nl — Dutch

  • fr — French

  • de — German

  • it — Italian

  • ja — Japanese

  • ko — Korean

  • pt — Portuguese

  • ru — Russian

  • es — Spanish

  • sv — Swedish

  • tr — Turkish

Any of the following parameters prevail over the languageName if provided:

  • SMIMEVerificationTemplateID

  • SMIMERequestTemplateID

  • SMIMECollectionTemplateID

  • shippingTemplateID

Product-specific parameters

S/MIME Mailbox certificate parameters

The following table outlines the product-specific parameters for S/MIME Mailbox-certificates.

All S/MIME certificate customers must supply smimeEmailAddresses.

Product Name/Payment Description Product-Specific Parameters Additional Notes

S/MIME Mailbox-Validated Strict Certificate

1-year

x_PPP=2411

2-year

x_PPP=2412

Supplementary parameters for S/MIME Mailbox-Validated certificate orders

The email address to be included in the certificate subject.

x_smimeSubjectEmail

S/MIME Organization-Validated Multipurpose certificate

All S/MIME certificate customers must supply smimeEmailAddresses and organizationIdentifier parameters. The full company name and address details are also required.

1-year

x_PPP=243

2-year

x_PPP=2432

Supplementary parameters for S/MIME Organization-Validated certificate orders

x_smimeSubjectCN

The allowed values are:

  • Y — The organization name will be included in the Common Name field of the certificate subject.

  • N — No Common Name will be included in the certificate subject.

If omitted, it defaults to N.

x_smimeSubjectEmail

Specifies the email address to be included in certificate subject.

Sample request

curl --location 'https://secure.trust-provider.com/products/!PlaceOrder' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'loginName=login_name' \
--data-urlencode 'loginPassword=login_password' \
--data-urlencode 'isReturningCustomer=N' \
--data-urlencode 'ap=reseller_brand_name' \
--data-urlencode 'reseller=Y' \
--data-urlencode '_1_PPP=2411' \
--data-urlencode '[email protected]' \
--data-urlencode '[email protected]' \
--data-urlencode 'organizationName=ABC Company 3443695' \
--data-urlencode 'stateOrProvinceName=California' \
--data-urlencode 'countryName=US' \
--data-urlencode 'streetAddress1=Elm Street 12' \
--data-urlencode '1_organizationIdentifier=VATDE-1234' \
--data-urlencode '1_showCollectionCode=Y'

Integration example of calling PlaceOrder using an HTML

Here is an example of how to order a one-year S/MIME Mailbox-Validated Strict certificate, by calling PlaceOrder from an HTML <form>:

<html>
<head>
<title>!PlaceOrder example: Ordering a one-year S/MIME Mailbox-Validated Strict certificate</title>
</head>
<body>
<form method=”post” name=”form1” action=”https://secure.trust-provider.com/products/!PlaceOrder”>
<input type=”hidden” name=”ap” value=”myresellerbrand”>
<input type=”hidden” name=”reseller” value=”y”>
<input type=”hidden” name=”errorURL” value=”http://www.mydomain.com/error_page.html”>
<input type=”hidden” name=”successURL” value=”http://www.mydomain.com/success_page.html”>
Email Address: <input type=”text” name=”emailAddress”>
<br>Name: <input type=”text” name=”name”>
<br>Company: <input type=”text” name=”organizationName”>
<input type=”hidden” name=”1_PPP” value=”2411”>
<br>MAC Address: <input type=”text” name=”1_MACAddress”>
<input type=”submit” value=”Place Order”>
</form>
</body>
</html>

Authorizing orders

When an order has been placed successfully with reseller=Y, you will need to authorize it before it is processed by Sectigo. You can authorize an order from within your Reseller account options on the Sectigo Management System, or by using the AutoAuthorize API endpont. Sectigo will deduct funds from your account when you authorize an order unless there is no charge. We recommend that you authorize an order only after you have actually received payment from your customer.

For those products that are free, you may want to avoid having to authorize each order. You can achieve this by using reseller=N when you call PlaceOrder.

Placing orders via ordering URLs

The PlaceOrder has been designed so that it can be integrated 'invisibly' with your own website (no webpages from secure.trust-provider.com need to be displayed to the applicant). However, we recognize that some Resellers will not want to go to the trouble of 'integrating an API' purely to achieve this 'invisibility'.

Those Resellers can resell the same products via their Reseller 'Ordering URLs'. For those products available through this API endpoint that require a loginName and loginPassword, we recommend that only the end-customers should place orders using these Ordering URLs, because only the end-customers should be in possession of their login credentials. For all other products, you the Reseller may use these 'Ordering URLs' to place orders on behalf of your customers.

Integration examples of calling PlaceOrder via a URL

An example, expressed as URLs, of how to call PlaceOrder from a browser for an order for a one-year S/MIME Mailbox-Validated Strict certificate:

https://secure.trust-provider.com/products/!PlaceOrder?ap=resellerbrand&reseller=y&[email protected]&name=Fred+Bloggs&1_PPP=2411&loginName=login_name&loginPassword=loginpassword&name=Fred

Response

The type of response depends on whether the call was successful and on whether the successURL and errorURL parameters were supplied in the request. successURL and errorURL are intended to be used only when PlaceOrder is called by a browser. When PlaceOrder is called from a back-end server, these parameters are irrelevant.

Unspecified successURL or errorURL

If the call is successful without successURL or fails without an errorURL, the MIME type of the response will be application/x-www-form-urlencoded, because the format of the response will be the same URL-encoded format as the request. For example, name1=value1&name2=value2.

Specified successURL or errorURL

If the call is successful and a successURL was supplied, or if an error occurs and an errorURL was supplied, then the browser will be redirected to the successURL or errorURL, whichever is applicable. The preceding parameters listed for unspecified successURL or errorURL will be passed as GET parameters in the 'query string' of the URL. This query string can be parsed by a JavaScript code.

Response parameters

Various parameters may appear in the response:

Parameter Requirement Type Max.Length Description

errorCode

required

integer

A numeric code that identifies the type of error and is always present in the response. For more information, see Error codes.

orderNumber

optional

string

128 chars

A newly assigned order number if the order was placed successfully.

errorMessage

optional

string

255 chars

The explanation of error if an error occurred.

errorItem

optional

string

255 chars

The name of the request parameter that caused the error if applicable.

Sample success response

orderNumber=8151164

Sample error response

errorCode=-3&errorItem=loginName

Error codes

The following table outlines error responses returned by the PlaceOrder API endpoint for Resellers. Each error response consists of an errorCode and an errorMessage indicating why the request failed.

Error Code Error Message Description

-1

Request was not made over HTTPS!

The request must use HTTPS protocol.

-2

'xxxx' is an unrecognized argument!

The provided argument is not recognized.

-3

The 'xxxx' argument is missing!

A required argument is missing from the request.

-4

The value of the 'xxxx' argument is invalid!

The argument value does not meet validation requirements.

-13

The CSR uses an unsupported key size!

The key size in the CSR is not supported.

-14

An unknown error occurred!

An unknown error occurred.

-16

Incorrect login details, account is locked, password has expired or your source IP is blocked.

Authentication has failed due to one of the specified reasons.

Verify your login credentials or check account restrictions.

-38

Certain details that must be validated for 'errorItem' are missing from this Account!

Certain required details for validation are missing from the account.

-39

At least 1 item is missing from this order!

The order does not contain all items.

-44

Not a white-listed public key!

The provided public key is not on the whitelist.

-62

Company name is required but missing.

The required company name is missing.

-65

PlanID for this product not found.

The specified PlanID for the product could not be found.

-70

Invalid Email Address!

The provided email address is not valid.

-83

'xxxx' is not applicable to this order!

The specified argument is not applicable for the current order.

-91

Permission Denied. 'xxx'

The user does not have permission for the specified context.

-97

Session is expired

The session has expired.

-126

HTTP(S) CSR Hash DCV Methods are not allowed to validate Wildcard Domain!

The HTTP(S) CSR Hash DCV methods cannot be used to validate a wildcard domain.