Sign up a Merchant for a PB Postage Account

HTTP Request

POST /v1/developers/{developerId}/merchants/signup?token={token}

Summary

This operation applies if you use the Individual Postage Account model and if your merchants sign up for their PB Postage Accounts from within your application. This operation is part of the Merchant Signup API. For step-by-step implementation of the API, see Merchant Signup Tutorial.

Consideration

This operation uses information collected through the Payment Iframe API call, as described in the Merchant Signup Tutorial.

Request URIs

Sandbox: https://api-sandbox.pitneybowes.com/shippingservices/v1/developers/{developerId}/merchants/signup?token={token}
Production: https://api.pitneybowes.com/shippingservices/v1/developers/{developerId}/merchants/signup?token={token}

Path Parameter

Name Description
developerId
Required. Your Pitney Bowes developer ID.

Query Parameter

Name Description
token Required. The access token returned in the accessToken field of the Payment Iframe response.

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.
Accept-Language Language and country code. Default: en-US
X-PB-UnifiedErrorStructure Recommended. Set this to true to use the standard error object if an error occurs.

Request Elements

Name Data Type Description
contact Contact object Required. The merchant’s contact address. This can be different from the billing address.
billingContact Contact object

PB Line of Credit Only. The merchant’s billing address. This can be different from the contact address.

Required for PB Line of Credit.

paymentInfo Array[Payment Info object] Required. The merchant’s payment information, including information retrieved through the Payment Iframe API.
initialPostageBalance String

Credit Card Only. Set this to the value returned by the Payment Iframe in the postageDetails.initialPostageBalance field.

For more information on the iframe response, see this step in the Merchant Signup Tutorial.

refillAmount String

Set this to the value returned by the Payment Iframe in the postageDetails.refillAmount field.

For more information on the iframe response, see this step in the Merchant Signup Tutorial.

thresholdAmount String

Set this to the value returned by the Payment Iframe in the postageDetails.thresholdAmount field.

For more information on the iframe response, see this step in the Merchant Signup Tutorial.

merchantCustomAttribute Array[Object] This optional array consists of key-value pairs that define custom attributes for the merchant. Each key-value pair in the array defines a custom attribute and the attribute’s value.
    name String Name of the custom attribute. Maximum length is 64 characters.
    value String The attribute value. Maximum length is 64 characters.

Request Elements: Contact Object

Name Data Type Description
email String Required. Email address.
firstName String Required. First name.
lastName String Required. Last name.
company String Required. Company name.
phone String

Required. A valid phone number for the merchant.

For USPS, this must be a valid 10-digit number. The string should contain 10 numeric characters and no additional characters. For example: "8442566444"

addressLines Array[String]

Required. Street address, including the apartment number if applicable.

Note: For USPS, the address cannot be a P.O. Box.

cityTown String Conditional: The city or town. Required if postalCode is absent.
stateProvince String

Conditional: The state or province. For US addresses, use the 2-letter state code.

Required if postalCode is absent; otherwise optional. Note that in some cases where cityTown is a unique name within the country, this can be left out, even if postalCode is absent. But the best practice is to include this field whenever postalCode absent.

postalCode String

Conditional: The postal/ZIP code. For US addresses, use either the 5-digit or 9-digit ZIP code.

Required if you are creating a shipment. Optional if you are rating a package.

countryCode String Required. Two-character country code from the ISO country list.

Request Elements: Payment Info Object

Name
Data Type Description
paymentType String

Required. The payment type.

  • For PB Line of Credit, do one of the following:
    • Create one one paymentInfo object with this field set to POSTAGE_AND_SUBSCRIPTION.
    • Create two paymentInfo objects, one with this field set to SUBSCRIPTION and the other with this field set to POSTAGE.
  • For Credit Card payment, create two paymentInfo objects, one with this field set to SUBSCRIPTION and the other with this field set to POSTAGE.
paymentMethod String

Required. The payment method. Valid values:

  • PurchasePower: PB Line of Credit
  • CC: Credit card payment
ppPaymentDetails Object

PB Line of Credit Only. The tokenized payment information for a PB Line of Credit.

Required if the paymentMethod field is set to PurchasePower.

    encryptedTIN String The merchant’s encrypted TIN (Taxpayer Identification Number).
ccPaymentDetails Object

Credit Card Only. The credit card information, including the tokenized credit card number. This field is required if the paymentMethod field is set to CC.

All the fields in the ccPaymentDetails object are required fields.

    ccType String

The type of credit card, as specified by one of the following abbreviations:

  • Amex
  • MC
  • Visa
  • Disc
    ccTokenNumber String The tokenized credit card number.
    ccExpirationDate String The month and year the card expires, entered as the two-digit month and four-digit year separated by a backslash. For example: 06/2021
    cccvvNumber String The three- or four-digit Card Verification Value.
    ccAddress Object The address associated with the credit card account.
        addressLines Array[String] Street address or P.O. Box. Include apartment number if applicable. You can specify up to three address lines.
        cityTown String City or town.
        stateProvince String State or province.
        postalCode String Postal or ZIP code.
        countryCode String Two-character country code from the ISO country list.
        firstName String First name as it appears on the credit card.
        lastName String Last name as it appears on the credit card.

Response Elements

Name Data Type Description
processId String A Pitney Bowes ID associated with the merchant.
email String The merchant’s email address.
fullName String The merchant’s full name.
enterpriseAccount String An enterprise account number associated with the merchant.
subscriptionAccount String Any subscription account that the merchant might have.
paymentAccountNumber String The Pitney Bowes Customer Account number assigned to the merchant.
postalReportingNumber String

The unique ID used to identify the merchant. This is also called the Shipper ID.

Note: Use this value as the Shipper ID when rating or creating a shipment

registeredDate String The date the merchant enrolled.
merchantStatus String

The merchant’s status. Possible values are:

  • ACTIVE: The merchant’s postage account has been created.

  • SUSPENDED: The merchant’s postage account has been created but is pending validation of the payment method. Please contact PaymentsAPISupport@pb.com to validate the payment method.

    If you had set an initialPostageBalance when making the API call, the errors array will include an error, as no funds can be transferred to the merchant’s postage account until the payment method is validated.

errors Array[Object]

Any errors that occurred during creation of the merchant’s postage account.

Note: The array can display an error even if the merchant is successfully created. If the request had specified an initialPostageBalance but the payment method is pending validation after merchant creation, an error displays telling you that funds cannot yet be transferred to the merchant’s postage account.

Sample Requests

See the following examples:

PB Line of Credit Sample Request

curl -X POST .../v1/developers/<developer_id>/merchants/signup?token=40dac0a6ed4213e99192dc_1536260407158 \
-H "Authorization: Bearer dJZYG0f638m2Oh6wpcUCt54kO" \
-H "Accept-Language: en-US" \
-H "Content-Type: application/json" \
-d '
{
    "contact": {
        "addressLines": ["120 Main St"],
        "cityTown": "Cooperstown",
        "stateProvince": "NY",
        "postalCode": "13326",
        "countryCode": "US",
        "firstName": "John",
        "lastName": "Smith",
        "company": "Gadgets",
        "phone": "607-000-0000",
        "email": "johnsmith@example.net"
    },
    "billingContact": {
        "addressLines": ["500 Main St"],
        "cityTown": "Cooperstown",
        "stateProvince": "NY",
        "postalCode": "13326",
        "countryCode": "US",
        "firstName": "John",
        "lastName": "Smith",
        "company": "Gadgets",
        "phone": "607-000-0000",
        "email": "johnsmith@example.net"
    },
    "paymentInfo": [ {
        "paymentType": "POSTAGE_AND_SUBSCRIPTION",
        "paymentMethod": "PurchasePower",
        "ppPaymentDetails": {
            "encryptedTIN":"<encrypted_TIN>"
        }
    } ],
    "merchantCustomAttribute": [ {
        "name": "acct_US",
        "value": "A1234"
    },{
        "name": "acct_EUR",
        "value": "B5678"
    } ]
}'

PB Line of Credit Sample Response

{
    "processId": "947123332",
    "email": "johnsmith@example.net",
    "fullName": "John Smith",
    "enterpriseAccount": "23456789",
    "subscriptionAccount": "7890123",
    "paymentAccountNumber": "23456789",
    "postalReportingNumber": "9024989977",
    "registeredDate": "2018-08-31",
    "merchantStatus": "ACTIVE",
    "errors": []
}

Credit Card Sample Request

curl -X POST .../v1/developers/<developer_id>/merchants/signup?token=9630ff87-bf3a-4afa-ba9d-51c08b02b7ab \
-H "Authorization: Bearer dJZYG0f638m2Oh6wpcUCt54kO" \
-H "Accept-Language: en-US" \
-H "Content-Type: application/json" \
-d '
{
    "contact": {
        "addressLines": ["120 Main St"],
        "cityTown": "Cooperstown",
        "stateProvince": "NY",
        "postalCode": "13326",
        "countryCode": "US",
        "firstName": "John",
        "lastName": "Smith",
        "company": "Gadgets",
        "phone": "607-000-0000",
        "email": "johnsmith@example.net"
    },
    "paymentInfo": [ {
        "paymentType": "SUBSCRIPTION",
        "paymentMethod": "CC",
        "ccPaymentDetails": {
            "ccType": "Amex",
            "ccTokenNumber": "AW234e",
            "ccExpirationDate": "03/2022",
            "cccvvNumber": "123",
            "ccAddress": {
                "addressLines": ["120 Main St"],
                "cityTown": "Cooperstown",
                "stateProvince": "NY",
                "postalCode": "13326",
                "countryCode": "US",
                "firstName": "John",
                "lastName": "Smith"
            }
        }
    }, {
        "paymentType": "POSTAGE",
        "paymentMethod": "CC",
        "ccPaymentDetails": {
            "ccType": "Amex",
            "ccTokenNumber": "AW234e",
            "ccExpirationDate": "03/2022",
            "cccvvNumber": "123",
            "ccAddress": {
                "addressLines": ["120 Main St"],
                "cityTown": "Cooperstown",
                "stateProvince": "NY",
                "postalCode": "13326",
                "countryCode": "US",
                "firstName": "John",
                "lastName": "Smith"
            }
        }
    } ],
    "merchantCustomAttribute": [ {
        "name": "CC_US",
        "value": "abc123"
    }, ... ]
}'

Credit Card Sample Response

{
    "processId": "947522336",
    "email": "johnsmith@example.net",
    "fullName": "John Smith",
    "enterpriseAccount": "2345678",
    "subscriptionAccount": "3456789",
    "paymentAccountNumber": "1234567",
    "postalReportingNumber": "9024989911",
    "registeredDate": "2018-08-31",
    "merchantStatus": "ACTIVE",
    "errors": []
}

Sample Response for a Credit Card that is Rejected or Pending Review

{
    "processId": "955740412",
    "email": "johnsmith@example.net",
    "fullName": "John Smith",
    "enterpriseAccount": "2345678",
    "subscriptionAccount": "3456789",
    "paymentAccountNumber": "1234567",
    "postalReportingNumber": "9026417989",
    "registeredDate": "2018-08-31",
    "merchantStatus": "SUSPENDED",
    "errors": [
        {
            "errorCode": "SAAS-ERR-1000",
            "errorDescription": "Initial postage cannot be triggered, merchant status is SUSPENDED"
        }
    ]
}

Error Codes

For error codes specific to this API, please see SAAS-ERR Error Codes.

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