Merchant Signup Tutorial

Overview

The Merchant Signup API allows merchants to sign up for their own PB Postage Accounts directly within your application without your application having to handle a merchant’s electronic-payment information. The API provides an iframe that uses third-party payment services to securely handle merchant payment information and to ensure PCI compliance. The API includes operations to retrieve the iframe URL and to sign up the merchant. This page provides steps for implementing Merchant Signup.

A merchant’s payment options include:

  • PB Line of Credit: The merchant enters a Taxpayer Identification Number (TIN) to activate a new PB Line of Credit account. Once the account is verified, the API sends back the encrypted TIN for you to use when registering the merchant.
  • Credit Card: The merchant enters a credit card number. If the merchant enters a valid credit card number, the API sends back a tokenized version of the credit card number for you to use when registering the merchant.

To implement Merchant Signup, use the steps below. The following image displays the API calls involved.

Merchant Signup

1. Retrieve the OAuth token

Invoke the Token Authentication API to retrieve the OAuth token.

2. Capture user information

Before invoking the Payment Iframe API, your application must capture the following information from the merchant:

  • First name
  • Last name
  • Company name
  • Address, including the street address (deliverable address), city, state, postal code, and country
  • Phone number
  • Email address

The iframe will use this information when the merchant selects a payment method.

3. Retrieve the payment iframe URL

Invoke the Payment Iframe API to retrieve the iframe URL. For example, invoke the API when the merchant clicks a payment button within your application. When issuing the API call, include the user information that you captured in the previous step.

Pitney Bowes recommends setting the renderType to purchase_power, which provides an iframe that lets a merchant choose between PB Line of Credit and credit card as the payment method.

Important: The response for the Payment Iframe API includes an access token that you will use later when issuing the Sign Up a Merchant API. Be sure to record this token.

4. Render the payment iframe on your page

Render the iframe using the URL returned by the Payment Iframe API in the response’s purchasePower.render field.

5. Add code to capture the merchant’s payment information

Once the merchant submits the payment iframe, Pitney Bowes uses a postMessage() to return the tokenized payment information. You must add code to capture the payment information.

This step describes:

PB LINE OF CREDIT

If the merchant uses PB Line of Credit as the payment method, the postMessage() returns an object with the following elements. Your code must capture the paymentMethod, locBillingAddress, ppPaymentDetails, and postageDetails:

Name Type Description
status String Indicates success.
paymentMethod String Indicates the merchant used PB Line of Credit as the payment method.
locBillingAddress Object The merchant’s billing address. This might differ from the contact address.
ppPaymentDetails Object The tokenized payment information for the PB Line of Credit account.
postageDetails Object The refill settings that the merchant selected for the PB Postage Account.
fraudStatus String

Indicates whether the payment method is validated. Possible values are:

  • Approved
  • Rejected
  • Pending Review

If the value is Rejected or Pending Review you can sign up the merchant but the merchant cannot print labels until the payment method is validated.

Example:

{
    "status": "Success",
    "paymentMethod": "PurchasePower",
    "locBillingAddress": {
        "firstName": "William",
        "lastName": "Wilson",
        "company": "Gadgets",
        "phone": "8470000000",
        "email": "shop@example.com",
        "address": {
            "addressLines": ["9 West Jackson Ave,Ste 103"],
            "city": "Lake Forest",
            "state": "IL",
            "postalCode": "60045",
            "countryCode": "US"
        }
    },
    "ppPaymentDetails": {
        "encryptedTIN": "q3NDw9kIjFwQfCkn6jx+fj40Y2M4TiMjQwYzBiNYwYzJjNDYjgwMhOTk1Nw=="
    },
    "postageDetails": {
        "refillAmount": "400",
        "thresholdAmount": "100"
    },
    "fraudStatus": "Approved"
}

CREDIT CARD

If the merchant uses a credit card as the payment method, the postMessage() returns an object with the following elements. Your code must capture the paymentMethod, ccPaymentDetails and postageDetails:

Name Type Description
status String Indicates success.
paymentMethod String Indicates the merchant used a credit card as the payment method.
ccPaymentDetails Object The credit card billing information, including the tokenized credit card number.
postageDetails Object The initial balance and refill settings that the merchant selected for the PB Postage Account.
fraudStatus String

Indicates whether the payment method is validated. Possible values are:

  • Approved
  • Rejected
  • Pending Review

If the value is Pending Review, you can sign up the merchant but the merchant cannot print labels until validation completes.

Example:

{
    "status": "Success",
    "paymentMethod": "CC",
    "ccPaymentDetails": {
        "ccType": "Visa",
        "ccTokenNumber": "-E803-1111-45SFN00000000G",
        "ccExpirationDate": "12/2023",
        "cccvvNumber": "123",
        "ccAddress": {
            "countryCode": "US",
            "firstName": "Joe",
            "lastName": "Jones",
            "cityTown": "Cooperstown",
            "stateProvince": "NY",
            "postalCode": "13326",
            "addressLines": [
                "120 Main St",
                "Suite # 1205",
                ""
            ]
        }
    },
    "postageDetails": {
        "initialPostageBalance": "100",
        "refillAmount": "400",
        "thresholdAmount": "100"
    },
    "fraudStatus": "Approved"
}

SAMPLE CODE TO CAPTURE PAYMENT INFORMATION

The following is sample code to capture payment information. For security, make sure the event listener validates the event origin.

<div id="resultPAN">
  <!–– code to capture information from the postMessage() ––>
</div>

<script>

function addListener() {
  window.addEventListener('message', listener);
}

function ppListener(event) {
  document.getElementById('resultPAN').innerHTML = event.data;
  console.log('event.data : ' + event.data);
    let responseData = event.data;
    if ( typeof(responseData) === 'string' ) {
      responseData = (JSON.parse(responseData));
    }
  console.log(responseData);
}

</script>

6. Create the merchant

Issue the Sign Up a Merchant API call to create the merchant and create the merchant’s PB Postage Account. Enter the payment information in the paymentInfo object.