Service summary

Use the platform web services if you are an e-commerce platform and want to register your merchant customers with Canada Post so that they can ship with Canada Post from your platform.

Registering a merchant with Canada Post

The diagram below provides an overview of how to sign up merchants for web services.

Registering a merchant with Canada Post

Platform services

Platform services are provided through the following calls.

1. Get Merchant Registration Token
   REST   |    SOAP Use this call to get a unique registration token (token-id) required to launch a merchant into the Canada Post sign-up process.
2. Get Merchant Registration Info
   REST   |    SOAP This call returns the merchant information such as their Canada Post customer number and the username and password required for using web services. You need this to information to perform web service shipping transactions for the merchant.

Programming details

1. When one of your merchant users wants to ship using Canada Post and is prepared to proceed with the Canada Post registration process, using your own authenticated browser session:
   
   • Call the Canada Post web service Get Merchant Registration Token using the appropriate endpoint:
     • REST: POST https://soa-gw.canadapost.ca/ot/token
     • SOAP: https://soa-gw.canadapost.ca/ot/soap/merchant/registration
   • Associate the response to this request with your own unique identification of the merchant on your system.

   Note: The token-id is only valid for 30 minutes—starting when it is issued and including the time a merchant takes to register with Canada Post.

2. Post the following fields to this URL to initiate a Canada Post registration session:
   

   Live environment: https://www.canadapost-postescanada.ca/information/app/drc/merchant

   Testing environment: https://www.canadapost-postescanada.ca/information/app/drc/testMerchant

   Mandatory	Optional
   return-url * (for call-back to your system) token-id (to refer to the interested user) platform-id (your customer number)	first-name last-name address-line-1 prov-state postal-zip-code country-code email city

   *Your URL must be complete—nothing will be appended to it on the Canada Post side.

3. We will redirect to the page specified in your return-url. We will pass the following 2 query parameters with a GET to the redirected page.
   
   • token-id
   • registration-status (will be one of: SUCCESS, CANCELLED, BAD_REQUEST, UNEXPECTED_ERROR, UNAUTHORIZED and SERVICE_UNAVAILABLE)
4. Provide a completion status message to your merchant.
5. If registration-status is OK, proceed to the next step. If Cancelled, please let the merchant know that you will be unable to submit requests on their behalf until they accept the terms and conditions, but their relationship with Canada Post remains in effect. If other, then an error occurred; please try again later.
6. Trade the token for merchant credentials by calling the Canada Post web service Get Merchant Registration Info using the appropriate endpoint:
   • REST: GET https://soa-gw.canadapost.ca/ot/token/{token-id}
   • SOAP: https://soa-gw.canadapost.ca/ot/soap/merchant/registration
7. Associate the response to this request with your own unique identification of the merchant on your system. Save the merchant API key (username and password) to your server. The token-id is no longer useful but the merchant username and password will allow you to submit web services on behalf of the registered merchant.
8. Test the merchant credentials by calling a non-chargeable web service (such as Get Rates or Get Customer Information) to test that the credentials work end-to-end.
9. Pass the merchant’s ongoing HTTPS requests through your server, and add your platform key and the appropriate merchant key.

Request element essentials

• Calls made for a merchant are only accepted by the production endpoints. Authorization error AA002 (wrong environment) will be returned for calls made with merchant credentials to the test environment.
• Protect the security of your platform API key (username and password) by keeping it on your server side.
• Before signing up merchants, consider checking that their account with you is in good standing.
• Note the following about customer numbers:
  • Even though you are submitting calls on behalf of a merchant, the merchant customer number is placed in the mailed-by element. The mailed on behalf of element (MOBO) is a repeat of the merchant customer number (unless the merchant has a previously arranged agreement with another customer).
  • Enter your platform customer number in the request element named platform-id.
  • The platform-id must be the same customer number that you used to register the merchant; that is, the customer number that owns the web service username that authenticated the registration request.

Making SOAP calls to web services on behalf of merchants

For SOAP calls, place the <platform-id> element at the top level of each request i.e., at the same level as locale or mailed-by.

Making REST calls to web services on behalf of merchants

Every time you make a REST call on behalf of a merchant, you must include Platform-Id in the HTTP header.

In addition, if the URL of the REST request includes mailed-by customer, you must also append a hyphen and your platform-id to the mailed-by customer number. Failure to do so will result in an authentication error. This approach keeps data for the same merchant separate over multiple platforms. See the list of affected REST calls below.

REST example calls for platforms

• Where 1111111 = the customer-number of the merchant
• Where 1234567 = your customer number/platform-id
• Where username = the merchant-username.
• Where password = the merchant-password

The above were returned to you by the Get Merchant Registration Info web service and then stored on your system.

Note: You can still use the <group-id> field for grouping user shipments within your platform. Overlap of group-id values from other platforms is not a concern since the mailed-by identifier is a top-level separator.

REST request URLs that include mailed-by customer

The following calls require you to append a hyphen and your platform-id to the mailed-by customer number.

Shipping

Create Shipment

Get Groups

Get Shipment

Get Shipment Details

Get Shipment Price

Get Shipments

Void Shipment

Manifest

Transmit Shipments

Get Manifest

Get Manifests

Get Manifest Details

Non-Contract Shipping

Create Non-Contract Shipment

Get Non-Contract Shipment Receipt

Get Non-Contract Shipment Details

Get Non-Contract Shipments

Get Non-Contract Shipment

Returns

Create Authorized Returns

Create Open Return Template

Get Open Return Template

Delete Open Return Template

Get Open Return Templates

Customer Information

Get Customer Information

Get MOBO Customer Information

Dimensions

Dimensions (i.e. parcel length, width, and height) will provide your merchants with more accurate shipping costs. If dimensions are not passed to the Canada Post API, the merchant may be subject to additional charges above the price quoted based on weight alone. This occurs in cases of large box sizes with light contents.

Warning message for your merchants

We recommend you display the following warning to your merchants before they print a label or transmit a manifest:

Note the information provided to Canada Post is subject to verification. Therefore, if Items actually presented to Canada Post are inconsistent with the information provided (incorrect category, volumes, weights, preparation; missing surcharges etc.) prices may be adjusted and/or additional charges added as provided for in the Customer's Agreement with Canada Post. The Customer agrees that such price changes are to be automatically applied to the Customer through the same method of payment chosen by the Customer for the Order (credit card or Canada Post account), with no further notice required to the Customer from Canada Post.

Error messages

Code	Description	Meaning and Mitigation
AA002	The username and password of the request do not match the endpoint. E.g. development key against production endpoint or vice versa.	Merchant requests cannot be sent to the development environment.
AA005	Platform id not specified	The platform-id header variable is empty or not present in the URL. This should only be encountered during platform development coding.
AA006	Platform not authorized	The platform-id specified is incorrect or the merchant subsequently came to Canada Post and intentionally revoked permission for your platform to submit transactions on its behalf. The merchant could be asked to revalidate with Canada Post if they want to re-establish their relationship with the platform. This error would also occur if the online owner of the platform key voluntarily withdrew from the Developer Program. In rare cases, Canada Post may have deactivated the entire platform status due to fraud or misuse concerns.
AA007	Registration requests cannot be made until the platform status is approved	The request for platform status has been made but Canada Post has not yet approved the request. In rare cases, Canada Post may have deactivated the entire platform status due to fraud or misuse concerns.
AA008	Only authorized platforms may access registration services.	An attempt was made to access the registration service without applying to Canada Post to become a platform.
AA009	Key type not valid for platform-id	If a key other than a merchant key is being used to authenticate a transaction, the platform-id field must not be specified. Remove the platform-id field from the request even if you are a registered platform. Only requests done on behalf of a merchant can specify the platform-id.
AA010	Incorrectly configured platform request	The platform-id in the header and the platform-id in the URL disagree. These values must match.