Authorize a Merchant who Signed up via Merchant Portal

HTTP Request

POST /v1/developers/{developerId}/merchants/credentials

Summary

This operation applies if you use the Individual Postage Account model and if your merchants sign up for their postage accounts through the Merchant Portal. For information on enrollment models, see Merchant Enrollment.

To use this API, do the following:

  1. Direct merchants to the Merchant Portal signup page specific to your developer account. See Merchant Signup URL below.
  2. 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.

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.

Merchant Signup URL

The merchant signup URL directs a shipper to a Merchant Portal signup page specific to your developer account where the shipper signs up for a PB Postage Account. The following are the merchant signup URLs:

Production environment:
https://www.pbshippingmerchant.pitneybowes.com/home?developerID={ID}
Sandbox environment
https://developer.pbshippingmerchant.pitneybowes.com/home?developerID={ID}

Replace {ID} with your developer ID. You can optionally append the URL with the paymentMethod parameter to require a specific payment method for the merchant’s PB Postage Account. The parameter takes one of the following values:

  • CreditCardOnly: Signup requires a credit card as the payment method.
  • PurchasePowerOnly: Signup requires PB Line of Credit as the payment method.

For example, the following merchant signup URL requires a credit card as the payment method:

https://<domain>/home?developerID=11223344&paymentMethod=CreditCardOnly

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 Parameters

Name Data Type Description
developerId String Required. Your Pitney Bowes developer ID.

Request Header

Name Data Type Description
Authorization String Required. OAuth token generated using the Generate an OAuth Token API.
Content-Type String Required. The media type of the request entity. Set this to application/json.

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: Some fields might not apply to your operation. This table describes all the possible fields in a merchant object.

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

The date the merchant’s account was deactivated, if applicable, shown as milliseconds since the Unix Epoch. A deactivated merchant can no longer print labels. For an active merchant, the field is set to null.

To convert the value to human-readable form, round from milliseconds to seconds and then 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 If you change a merchant’s status from ACTIVE to INACTIVE, you must give a reason for the change. The reason is recorded here. For an active merchant, the field is set to null.
parcelProtection String If true, the merchant can choose to insure a parcel with PB Parcel Protection when creating a shipment.
paymentMethod String

This is returned only for the Authorize Merchant API call. This field indicates the payment method for the merchant’s PB Postage Account. Possible values are:

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

curl -X POST .../v1/developers/<developer_id>/merchants/credentials \
–H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-d '
{
    "username":"John Smith",
    "password":"PAs5W0rD!"
}'

Sample Response

{
    "fullName": "John Smith",
    "email": "johnsmith@example.com",
    "registeredDate": 1444608000000,
    "deactivatedDate": null,
    "paymentAccountNumber": "1234567",
    "enterpriseAccount": "2345678",
    "subscriptionAccount": "3456789",
    "postalReportingNumber": "55555555",
    "merchantStatus": "ACTIVE",
    "merchantStatusReason": null,
    "parcelProtection": false,
    "paymentMethod": "LineOfCredit/Prepaid"
}

Error Codes

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