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 credentials for a merchant who signed up for a PB Postage Account via Merchant Portal. The operation applies if you use the Individual Postage Account enrollment model and if your merchants sign up for their postage accounts via a Merchant Portal signup page specific to your developer account. For more information on signup models, see Merchant Enrollment Models.

How to Use this API¶

1. Direct merchants to your signup page on Merchant Portal.¶

Your signup page on Merchant Portal uses following URLs and query parameters:

URLs¶

Environment:
Signup Page URL:

Production https://www.pbshippingmerchant.pitneybowes.com/home?developerID={ID}[&optional query parameter]

Sandbox https://developer.pbshippingmerchant.pitneybowes.com/home?developerID={ID}[&optional query parameter]

Query Parameters¶

Query Parameter:
Description:

developerID Required. Your Pitney Bowes developer ID. To retrieve your developer ID, log into Developer Hub and click your username and select Profile.

referral_code Optional. Attaches a referral code to the merchant that you can use to identify who referred the merchant to your software. The referral code can use up to 25 characters and can use alphanumeric characters, underscores (_), hyphens (-), and dots (.).

2. Retrieve the merchant’s Shipper ID.¶

Once a merchant signs up, use this POST operation to retrieve the merchant’s Shipper ID. The Shipper ID lets you print labels and request transactions on the merchant’s behalf.

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¶

Important

The operation returns a Merchant Object. The table below describes all possible fields in a Merchant Object. Some fields might not apply to your operation.

Name	Data Type	Description
fullName	String	The merchant’s full name.
email	String	The merchant’s email address.
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.
deactivatedDate	Number	For an inactive merchant, the date the merchant’s account was deactivated, shown as milliseconds since the Unix Epoch. For an active merchant, this field is set to `null`. To convert milliseconds since the Epoch to human-readable form: Round from milliseconds to seconds. Apply the Unix timestamp conversion algorithm. Alternatively, use a web site that converts milliseconds since the Epoch, such as https://currentmillis.com.
paymentAccountNumber	String	The Pitney Bowes customer account number assigned to the merchant.
enterpriseAccount	String	An enterprise account number that is associated with the merchant.
subscriptionAccount	String	Any subscription account that the merchant might have.
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.
merchantStatus	String	The merchant’s status. Possible values are: `ACTIVE` `INACTIVE`
merchantStatusReason	String	For an inactive merchant, the reason the merchant was deactivated. For an active merchant, this field is set to `null`.
parcelProtection	String	If `true`, the merchant can choose to request PB Parcel Protection coverage when creating a shipment.
paymentKey	String	If the merchant uses ACH as the payment method, this returns the ACH payment key. Otherwise this returns the `null` value.
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 returns the `null` value. For the Authorize a Merchant API call, the possible values are: `LineOfCredit`: PB Line of Credit `CreditCard`: U.S. credit card `ACH`: (Automated Clearing House)
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 Newgistics 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: `UPS` `FEDEX` (Coming soon to Sandbox)
deactivationDate	Number	If the merchant has removed the carrier account, this is the date the account was removed.
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 carrier account was registered to be used with Pitney Bowes.
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.

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/<developer_id>/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¶

{
    "fullName": "John Smith",
    "email": "johnsmith@example.com",
    "registeredDate": 1517961600000,
    "deactivatedDate": "null",
    "paymentAccountNumber": "24345678",
    "enterpriseAccount": "24345688",
    "subscriptionAccount": "24345688",
    "postalReportingNumber": "9024989955",
    "merchantStatus": "ACTIVE",
    "merchantStatusReason": null,
    "parcelProtection": false,
    "paymentKey": null,
    "paymentMethod": "LineOfCredit/Prepaid"
}

Error Codes¶

For a list of all PB Shipping APIs error codes, see Error Codes.

Environment:	Signup Page URL:
Production	`https://www.pbshippingmerchant.pitneybowes.com/home?developerID={ID}[&optional query parameter]`
Sandbox	`https://developer.pbshippingmerchant.pitneybowes.com/home?developerID={ID}[&optional query parameter]`

Query Parameter:	Description:
`developerID`	Required. Your Pitney Bowes developer ID. To retrieve your developer ID, log into Developer Hub and click your username and select Profile.
`referral_code`	Optional. Attaches a referral code to the merchant that you can use to identify who referred the merchant to your software. The referral code can use up to 25 characters and can use alphanumeric characters, underscores (`_`), hyphens (`-`), and dots (`.`).