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:

  1. You must provide the merchant with a URL to your signup page on Merchant Portal. See Provide a Signup URL.

  2. The merchant must use the URL to sign up for an account.

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

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

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

merchantCarrierAccounts
.accountNumber

String

The merchant’s account number with the carrier.

merchantCarrierAccounts
.carrierName

String

The carrier. Possible values:

  • FEDEX

  • UPS

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

merchantCarrierAccounts
.isActive

Boolean

If true, the carrier account is active. If false, the merchant has removed the carrier account.

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

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

merchantCarrierAccounts
.merchantCarrierAccountAttributes
.attributeName

String

The carrier account attribute.

merchantCarrierAccounts
.merchantCarrierAccountAttributes
.attributeValue

String

The value of the carrier account attribute.

merchantCarrierAccounts
.registrationDate

Number

The date the merchant’s carrier account was registered with Pitney Bowes, shown as milliseconds since the Unix Epoch.

merchantCarrierAccounts
.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:

  • ACTIVE

  • INACTIVE

merchantStatusReason

String

For an inactive merchant, the reason the merchant was deactivated.

For an active merchant, this field is null.

merchantType

String

Indicates the type of merchant:

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.

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.

paymentMethod

String

When returned by the Authorize a Merchant API, this indicates 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

paymentKey

String

Note

This field will be removed in 2022.

If the merchant uses ACH as the payment method, this returns the ACH payment key. Otherwise this field is null.

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.