Merchant Signup API

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 either activate a new PB Line of Credit account or identify an existing one. Once the account is verified, the API sends back the encrypted TIN for you to use when registering the merchant. If the merchant has an existing PB Line of Credit account, the API also sends back an encrypted BPN (Business Partner Number).
  • 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 for accessing the PB Shipping APIs

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 completes payment setup in the iframe, Pitney Bowes returns the tokenized payment information in a window post message. You must add code to capture both types of payment information: PB Line of Credit and Credit Card.

PB Line of Credit

If the merchant used PB Line of Credit as the payment method, the window post message returns the following payment information. You must add code to capture the encryptedTIN and encryptedBPN.

{
    "status": "Success",
    "paymentMethod": "PurchasePower",
    "ppPaymentDetails": {
        "encryptedTIN": "q3NDw9kIjFwQfCkn6jx+fj40Y2M4TiMjQwYzBiNYwYzJjNDYjgwMhOTk1Nw==",
        "encryptedBPN": "12345678"
    }
}

Credit Card

If the merchant used a credit card as the payment method, the window post message returns the following payment information. You must add code to capture the ccPaymentDetails object.

{
    "status": "Success",
    "paymentMethod": "CC",
    "ccPaymentDetails": {
        "ccType": "Visa",
        "ccTokenNumber": "-E803-1111-45SFN00000000G",
        "ccExpirationDate": "09/2020",
        "cccvvNumber": "497",
        "ccAddress": {
            "countryCode": "US",
            "firstName": "Joe",
            "lastName": "Jones",
            "cityTown": "Cooperstown",
            "stateProvince": "NY",
            "postalCode": "13326",
            "addressLines": [
                "120 Main St",
                "Suite # 1205",
                ""
            ]
        }
    }
}

Sample Code

The following is sample code to capture payment information:

<div id="resultPAN">
  <!–– code to receive the window post message ––>
</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.