Authorize a Merchant who Signed up via Merchant Portal¶

Important

This POST operation sends the username and password of the merchant 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 a merchant account and 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 use the URL to sign up for an account.
The merchant must provide you with the username and password for the new account.

After the merchant signs up, use this API to retrieve the merchant’s Shipper ID and other account information.

Request URLs¶

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v1/developers/{developerId}/merchants/credentials
Production: https://shipping-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 account.
password	String	Required. The password for the merchant account.

Response Elements¶

Name	Data Type	Description
company	String	The merchant’s company.
developerId	String	Your Pitney Bowes developer ID.
email	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[Merchant Carrier Accounts 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.
merchantStatus	String	The merchant’s status. This is set to `ACTIVE`.
merchantStatusReason	String	This field is `null`.
merchantType	String	This indicates the merchant has an individual postage account. This is set to `INDIVIDUAL`.
paymentAccountNumber	String	The identifier for the PB Postage Account.
paymentServicesAccountId	String	A UUID that identifies the payment services account used to fund the merchant’s PB Postage Account. The payment services account has the merchant’s payment methods. A merchant can have one or more payment methods.
paymentServicesAccountIdActive	Boolean	If set to `true`, the merchant’s payment services account is active and can be used to fund postage.
postalReportingNumber	String	The unique ID used to identify the merchant. This is 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 website that converts milliseconds since the Epoch.
subscriptionAccount	String	Any subscription account that the merchant might have.
paymentMethod	String	The payment method for the merchant’s PB Postage Account. Possible values are: `LineOfCredit/Prepaid`: PB Line of Credit `CreditCard`: U.S. credit card `ACH`: Automated Clearing House

Merchant Carrier Accounts Object¶

The merchantCarrierAccounts array returns the following object.

Name	Data Type	Description
accountNumber	String	The merchant’s account number with the carrier.
carrierName	String	The carrier. Possible values: `FEDEX` `UPS`
deactivationDate	Number	If the carrier account has been removed, this field is set to the date of removal. 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 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]	The objects in this array display settings that correspond to settings in the merchant’s carrier account. Each object in the array is a name-value pair and contains the following fields: attributeName: The carrier account attribute. This field takes a String. attributeValue: The value of the carrier account attribute. This field takes a String.
registrationDate	Number	The date the merchant’s carrier account was registered 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¶

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@example.com",
    "password": "PAs5W0rD!"
}'

Sample Response¶

{
    "company": "null",
    "developerId": "24989977",
    "email": "john@example.com",
    "enterpriseAccount": "24345688",
    "fullName": "John Smith",
    "merchantCarrierAccounts": [ {
        "accountNumber": "<account>",
        "carrierName": "UPS",
        "deactivationDate": 0,
        "isActive": true,
        "isAuthorized": true,
        "merchantCarrierAccountAttributes": [ {
            "attributeName": "PASSWORD",
            "attributeValue": "<password>"
        },{
            "attributeName": "ACCOUNT_NUMBER",
            "attributeValue": "<account>"
        },{
            "attributeName": "KEY",
            "attributeValue": "<key>"
        },{
            "attributeName": "USER_ID",
            "attributeValue": "<user-id>"
        } ],
        "registrationDate": 1544289739845,
        "shipperCarrierAccountId": "<id-generated-by-pitney-bowes>"
    },
    ...
    ],
    "merchantStatus": "ACTIVE",
    "merchantType": "DEFAULT",
    "paymentAccountNumber": "24345678",
    "paymentServicesAccountId": "12345678-abdc-1234-abcd-efg123456789",
    "paymentServicesAccountIdActive": true,
    "postalReportingNumber": "902455555",
    "registeredDate": 1517961600000,
    "subscriptionAccount": "24345688",
    "paymentMethod": "ACH"
}

Error Codes¶

For a list of all error codes returned by the Ecommerce APIs, please see Error Codes.

Provide Signup URL