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. For more information on signup models, see Merchant Enrollment Models.

How to Use this API to Onboard a Merchant

1. Direct merchants to your Signup Page on Merchant Portal.

Your Signup Page uses one of the following URLs, depending on the environment:

Signup Page URLs
Environment
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
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 (.).
paymentMethod

Optional. Specifies the list of payment methods the merchant can choose from to fund the PB Postage Account. By default, the merchant’s choices are credit card, PB Line of Credit, or ACH. You can optionally limit the choices by setting this parameter to one of the following:

  • PurchasePowerOnly: The merchant must use PB Line of Credit.
  • ACHOnly: The merchant must use ACH.
  • LOC_ACH: The merchant can choose either PB Line of Credit or ACH.
  • CreditCard_LOC: The merchant can choose either PB Line of Credit or credit card.
  • CreditCard_ACH: The merchant can choose either ACH or credit card.
  • CreditCardOnly: The merchant must use credit card.

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

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
developerId String Your Pitney Bowes developer ID.
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 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 null.

paymentAccountNumber String The merchant’s Pitney Bowes payment account number.
enterpriseAccount String An enterprise account number 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 null.

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.
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 null.

For the Authorize a Merchant API call, the possible values are:

  • LineOfCredit/Prepaid: PB Line of Credit
  • CreditCard: U.S. credit card
  • ACH: (Automated Clearing House)
address   Internal use only. This field is null.
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:

  • FEDEX
  • UPS
    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 0.

    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.

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"
}

Error Codes

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