Sign up a Merchant from within your Application

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 postage accounts through your application. This operation is part of the Merchant Signup API. For step-by-step implementation of the API, see Merchant Signup.

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 Data Type Description
developerId String Required. Your Pitney Bowes developer ID.

Query Parameter

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

Request Headers

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.
Accept-Language String Language and country code. Default: en-US

Request Elements

Name Data Type Description
contact Contact object Required. The new merchant’s contact address. This can be different from the merchant’s billing address.
paymentInfo Array[Payment Info object] Required. The merchant’s payment information, including information retrieved through the Payment Iframe API.
initialPostageBalance String The initial balance transferred to the merchant’s PB Postage Account. Ensure the balance can cover the cost of the merchant’s first postage label.
refillAmount String The amount to add to the merchant’s PB Postage Account when the balance falls below the thresholdAmount value. The default value for this field is 400.
thresholdAmount String The PB Postage Account is refilled when the account balance falls below this value. The default value for this field is 100.
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

City or town.

Required if postalCode is absent.

stateProvince String

State or province. For US addresses, use the 2-letter state code.

Required if postalCode is absent. 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

Postal/ZIP code. For US addresses, use either the 5-digit or 9-digit ZIP code.

Required if cityTown and stateProvince are absent.

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. Possible values:

  • PurchasePower: PB Line of Credit
  • CC: Credit card payment
ppPaymentDetails Object PB Line of Credit Only. The merchant’s encrypted TIN and encrypted BPN. The object includes an encrypted BPN only if the merchant already has a PB Line of Credit account.
    encryptedTIN String The merchant’s encrypted TIN (Taxpayer Identification Number).
    encryptedBPN String The merchant’s encrypted BPN (Business Partner Number). This field applies only if the merchant already has a PB Line of Credit account.
ccPaymentDetails Object

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

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

Examples

This section provides the following examples:

Example: PB Line of Credit

Sample Request — PB Line of Credit

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"
    },
    "paymentInfo": [ {
        "paymentType": "POSTAGE_AND_SUBSCRIPTION",
        "paymentMethod": "PurchasePower",
        "ppPaymentDetails": {
            "encryptedTIN":"<encrypted_TIN>",
            "encryptedBPN":"<encrypted_BPN>"
        }
    } ],
    "merchantCustomAttribute": [ {
        "name": "acct_US",
        "value": "A1234"
    },{
        "name": "acct_EUR",
        "value": "B5678"
    } ],
    "initialPostageBalance": "100",
    "refillAmount": "200",
    "thresholdAmount": "100"
}'

Sample Response — PB Line of Credit

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

Example: Credit Card

Sample Request — Credit Card

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"
    }, ... ],
    "initialPostageBalance": "200",
    "refillAmount": "400",
    "thresholdAmount": "100"
}'

Sample Response — Credit Card

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

Example: Credit Card is Rejected or Pending Review

Sample Response if Credit Card 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

Code Message
SAAS-ERR-510 Subscription already exists for the merchant.
SAAS-ERR-1000 Initial postage cannot be triggered, merchant status is SUSPENDED
Note: For all PB Shipping APIs error codes, see Error Codes.