Authorize a Merchant who Signed up via Merchant Portal¶
Important
This POST operation sends the username and password of the merchant’s PB Postage Account. Ensure you use TLS encryption when sending the request.
HTTP Request¶
POST /v1/developers/{developerId}/merchants/credentials
Summary¶
This operation retrieves the Shipper ID for a merchant who signs up through Merchant Portal for his or her PB Postage Account. The operation applies if you use the Individual Postage Account enrollment model, as described in the Merchant Enrollment Models table on the Merchant Accounts page.
To use this API, you must first provide the merchant with a URL to your signup page on Merchant Portal, as described in Provide a Signup URL. After the merchant signs up, you use this API to retrieve the merchant’s Shipper ID. The Shipper ID lets you print labels and request transactions on the merchant’s behalf.
Prerequisite¶
Before you use this API:
- You must provide the merchant with a URL to your signup page on Merchant Portal. See Provide a Signup URL.
- The merchant must sign up.
After the merchant signs up, use this API to retrieve the merchant’s Shipper ID and other account information.
Request URIs¶
Sandbox: https://api-sandbox.pitneybowes.com/shippingservices/v1/developers/{developerId}/merchants/credentials
Production: https://api.pitneybowes.com/shippingservices/v1/developers/{developerId}/merchants/credentials
Path Parameter¶
Name | Description |
---|---|
developerId
|
Required. Your Pitney Bowes developer ID. |
Request Headers¶
Name
|
Description |
---|---|
Authorization | Required. OAuth token generated using the Generate an OAuth Token API. |
Content-Type | Required. The media type of the request entity. Set this to application/json . |
X-PB-UnifiedErrorStructure | Recommended. Set this to true to use the standard error
object if an error occurs. |
Request Elements¶
Name | Data Type | Description |
---|---|---|
username | String | Required. The username for the merchant’s PB Postage Account. |
password | String | Required. The password for the merchant’s PB Postage Account. |
Response Elements¶
The operation returns a Merchant Object. The following table describes all possible fields in a Merchant Object.
Important
Some fields in the Merchant Object might not apply to your operation and are marked accordingly.
Name
|
Data Type | Description |
---|---|---|
address | Internal use only. If this field is returned, it is set to null . |
|
company | String | The merchant’s company. |
deactivatedDate | String | For an inactive merchant, the date the merchant’s account was deactivated, returned in the ISO 8601 format. For an active merchant, this field is |
developerId | String | Your Pitney Bowes developer ID. |
String | The merchant’s email address. | |
enterpriseAccount | String | An enterprise account number associated with the merchant. |
fullName | String | The merchant’s full name. |
merchantCarrierAccounts | Array[Object] | Merchants with Multiple Carriers Only. This array appears in the response of the merchant object only if the merchant has registered additional commercial carrier accounts, other than PB Standard or PB Presort. Each object in this array contains information on a specific carrier account. |
accountNumber | String | The merchant’s account number with the carrier. |
carrierName | String | The carrier. Possible values:
|
deactivationDate | Number | If the merchant has removed the carrier account, this field is set to the date that the carrier account was removed. If the carrier account is still active, this field is set to |
isActive | Boolean | If true , the carrier account is active. If false , the merchant has
removed the carrier account. |
isAuthorized | Boolean | If true , the PB Shipping APIs can generate labels with this carrier on
behalf of the merchant. If false , the APIs cannot generate labels with
the carrier for this merchant. |
merchantCarrierAccountAttributes | Array[Object] | Attributes that correspond to settings in the merchant’s carrier account. Each object in the array defines an attribute and its value. |
attributeName | String | The carrier account attribute. |
attributeValue | String | The value of the carrier account attribute. |
registrationDate | Number | The date the merchant’s carrier account was registered for use with Pitney Bowes, shown as milliseconds since the Unix Epoch. |
shipperCarrierAccountId | String | The unique identifier to use when the merchant performs an operation
that uses this carrier account. The identifier is passed in the
X-PB-Shipper-Carrier-AccountId request header of the API request. |
merchantStatus | String | The merchant’s status. Possible values are:
|
merchantStatusReason | String | For an inactive merchant, the reason the merchant was deactivated. For an active merchant, this field is |
merchantType | String | This field is returned only for the Register a Merchant
API call and returns the value KNOWN_SHIPPER . |
parcelProtection | Boolean | If true , the merchant can choose to request PB Parcel Protection coverage when creating a shipment. |
paymentAccountNumber | String | The merchant’s Pitney Bowes payment account number. |
paymentKey | String | If the merchant uses ACH as the payment method, this returns the ACH payment
key. Otherwise this field is null . |
paymentMethod | String | When returned by the Authorize a Merchant
API call, this field indicates the payment method
for the merchant’s PB Postage Account. For other API calls, this field is For the Authorize a Merchant API call, the possible values are:
|
postalReportingNumber | String | The unique ID used to identify the merchant. Note: This value is also the merchant’s Shipper ID. You must specify Shipper ID when creating a shipment. |
registeredDate | Number | The date the merchant’s account was created, shown as milliseconds since the Unix Epoch. You can convert the date to human-readable form by rounding from milliseconds to seconds and then using the Unix timestamp conversion algorithm, or by using a web site that converts milliseconds since the Epoch, such as https://currentmillis.com. |
subscriptionAccount | String | Any subscription account that the merchant might have. |
Sample Request¶
Important: You must use TLS encryption when passing the merchant credentials using this POST operation. The APIs require TLS. For the required TLS version, see TLS.
curl -X POST .../v1/developers/12345678/merchants/credentials \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
"username":"John Smith",
"password":"PAs5W0rD!"
}'
Sample Response¶
{
"developerId": "12345678",
"fullName": "John Smith",
"email": "john@example.com",
"registeredDate": 1517961600000,
"paymentAccountNumber": "24345678",
"enterpriseAccount": "24345688",
"subscriptionAccount": "24345688",
"postalReportingNumber": "9024989955",
"merchantStatus": "ACTIVE",
"merchantStatusReason": null,
"parcelProtection": false,
"paymentKey": null,
"paymentMethod": "LineOfCredit/Prepaid"
}