Web service requirements for return authorization numbers – SOAP

When creating a parcel return policy, you have the option to request that your customers enter a return authorization (RA) number to retrieve a label. You can use one static number or provide us with a URL address to a web service that you host where your list of unique authorization numbers is housed.

When you create your parcel return policy in My Returns on the Canada Post website, if you select the web service option, you will be prompted to enter the URL, username and password for your web service. Here are the requirements for the web service.

Implementation

Your web service should be implemented using standard SOAP protocol and follow our WSDL.

We will call your web service to validate the RA number entered by your customers before we allow them to retrieve a return label. The web service must return either a pass or fail. If the authorization fails, we will not allow your customers to retrieve a return label.

Your web service should incorporate secure access. When we call your service, we will include the username and password in the WS-Security header as part of our SOAP call.

Please note that your web service must include the authorization number 99999999999999 (i.e., 14 9s), which should always return an indication of a valid number. This will allow Canada Post to ping your web service to determine that it is operational.

Successful completion

If your web service completes its actions successfully for the input data provided, you will return a 200-level HTTP code and respond with the output data contained within a top-level XML element in the SOAP body.

Web service summary

Validations Name Validate RSA
Reason to call To validate the RA number provided by a consumer. The service must also include a “ping” capability to indicate it is up and running.
Input The authorization number to be validated. Optional parameters are the date the RA number was issued, and additional information specified in the policy.
Output A validity flag indicating whether the authorization number is valid.

Request details

Requests Element name Usage Description
ValidateRsa Required The top level XML element for the request input information.
RsaNumber Required
  • Contained within ValidateRsa.
  • Return shipping authorization number that the customer provided to retrieve a return label
  • 1-15 alphanumeric or special characters
  • Special ping value “99999999999999” must always return ValidationStatus = true
RsaNumberIssueDate Optional
  • Contained within ValidateRsa (For future use)
  • Date on which the RSA number was issued to the customer
  • Format: YYYY-MM-DD
AdditionalInfo Optional
  • Contained within ValidateRsa (For future use)
  • Up to 20 characters
  • Additional information specified in the policy that the customer needs to provide (e.g., invoice number, item number, reference number etc.)

Response elements

Responses Element name Usage Description
ValidateRsaResponse Required The top level XML element for the request input information.
ValidationStatus Required
  • Contained within ValidateRsaResponse Boolean
  • false – RsaNumber not valid
  • true – RsaNumber valid

Error condition

If we are not authorized to call the service or the service is not able to complete successfully, then it will be considered an error condition. Your web service should return a SOAP fault with any descriptive information obtained from the back-end service embedded in the SOAP fault body.

Examples

Sample SOAP XML request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/ xmlns:val="http://www.canadapost.ca/webservices/validatersa">
<soapenv:Header>
<wsse:Security soapenv:mustUnderstand="1" 
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" 
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsse:UsernameToken wsu:Id="UsernameToken-1">
<wsse:Username>test</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">test</wsse:Password>
<wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">ITB53//D6aw8hS+EWxI1NA==</wsse:Nonce>
<wsu:Created>2012-09-22T16:59:01.454Z</wsu:Created>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
<soapenv:Body>
<val:ValidateRsa>
<val:RsaNumber>99999999999999</val:RsaNumber>
<val:RsaNumberIssueDate>2012-09-22</val:RsaNumberIssueDate>
<val:AdditionalInfo>PO123-45678-XY</val:AdditionalInfo>
</val:ValidateRsa>
</soapenv:Body>
</soapenv:Envelope>

Sample SOAP - XML response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<s:Header>
<o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<u:Timestamp u:Id="_0">
<u:Created>2012-09-22T20:03:36.751Z</u:Created>
<u:Expires>2012-09-22T20:08:36.751Z</u:Expires>
</u:Timestamp>
</o:Security>
</s:Header>
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ValidateRsaResponse xmlns="http://www.canadapost.ca/webservices/validatersa"> true</ValidationStatus>
</ValidateRsaResponse>
</s:Body>
</s:Envelope>

Sample SOAP response to an error condition

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<s:Header>
<o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<u:Timestamp u:Id="_0">
<u:Created>2012-09-22T20:05:35.673Z</u:Created>
<u:Expires>2012-09-22T20:10:35.673Z</u:Expires>
</u:Timestamp>
</o:Security>
</s:Header>
<s:Body>
<s:Fault>
<faultcode>8304 Sample error</faultstring>
<s:Fault>
</s:Body>
</s:Envelope>