Retrieve a Payment Iframe URL

HTTP Request

POST /v1/payment/render

Summary

This operation returns the URL for an iframe that handles merchant payment information. The iframe handles the information through a third-party payment service. Once the merchant submits payment information through the iframe, Pitney Bowes returns the tokenized payment information in a window post message, as described in this step of the Merchant Signup Tutorial. The operation is part of the Merchant Signup API. For step-by-step implementation of the API, see Merchant Signup.

Things to Consider

  1. You must retrieve the following merchant information before making this API call:
    • first and last name
    • address
    • company
    • phone number
    • email address
  2. The request’s renderType element determines the payment services the iframe will make available. It is recommended that you set this to purchase_power, which will let the merchant choose between PB Line of Credit and credit card.
  3. The token returned in the response’s accessToken field can be used to access the iframe only once.
  4. The token returned in the response’s accessToken field will also be used when you issue the Sign Up a Merchant API call. Make sure to record the token for use in that API call.
  5. You can optionally apply custom styles to the iframe by including the HTTPS URL of a style sheet in the request. The style sheet must be hosted over HTTPS or the iframe will not be able to use it and the UI will not render correctly.
  6. Once the merchant submits the iframe, Pitney Bowes returns a window post message with the merchant’s tokenized payment information. You must write code to capture this information, as described in this step of the Merchant Signup Tutorial.

Request URIs

Sandbox: https://api-sandbox.pitneybowes.com/shippingservices/v1/payment/render
Production: https://api.pitneybowes.com/shippingservices/v1/payment/render

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
hostUri String

Required. The URL of the web page where the iframe is rendered. This value is required to identify the host when Pitney Bowes returns the tokenized payment information in a window post message. The iframe works correctly only if this URL is accurate. Any accurate TLD will work, including localhost.

Examples:

  • dev08.net
  • localhost:4200
  • https://127.0.0.1/web/
renderType String

Required. Determines the payment services the iframe makes available. It is recommended that you set this to purchase_power.

Possible values:

  • purchase_power: Provides an iframe that lets the merchant choose between PB Line of Credit and credit card for the payment method. The iframe guides the merchant through the setup of the chosen payment method.
  • credit_card: Provides an iframe that prompts the merchant to enter a credit card as the payment method.
styleSheet String The HTTPS URL of the stylesheet to use when rendering the iframe. This is optional. If this element is omitted, a default style is used.
userInfo userInfo object This object contains the merchant’s name, address, company name, phone number, and email address.

Request Elements: userInfo Object

Name Data Type Description
email String Required. Email address.
phone String Required. Phone number.
firstName String First name
lastName String Last name
company String Required. Company name.
address Object Required. The merchant’s full address.
    addressLines Array[String] Required. Street address or P.O. Box. For a street address, include the apartment number if applicable.
    city String Required. City or town.
    state String Required. State or province. For US addresses, use the 2-letter state code.
    postalCode String Required. Postal/ZIP code. For US addresses, use either the 5-digit or 9-digit ZIP code.
    countryCode String Required. Two-character country code from the ISO country list.

Response Elements

Element Data Type Description
purchasePower Object This is returned if renderType was set to purchase_power. This object contains the URL for an iframe that lets the merchant choose between PB Line of Credit and credit card for the payment method. The iframe guides the merchant through the setup of the chosen payment method.
        renderType String Indicates that the URL is for an iframe.
        render String The URL for including the iframe in your application. The URL includes the access token. You can use the URL only once.
creditCard Object This is returned if renderType was set to credit_card.
        renderType String Indicates that the URL is for an iframe.
        render String The URL for including the iframe in your application. The URL includes the access token. You can use the URL only once.
accessToken String

The access token used to:

  • Access the iframe. You can use the token only once to access the iframe. To access the iframe, do not pass the token separately: the token is already appended to the iframe URL returned in the <render-type>.render field.
  • Sign up the merchant. Make sure to record the token for use in the Sign Up a Merchant API call.

Example

Sample Request

The following request sets renderType to purchase_power, which gives merchants a choice of payment method.

curl -X POST .../v1/payment/render \
–H "Authorization: Bearer <oauth_token>" \
-H "Accept-Language: en-US \
-H "Content-Type: application/json" \
-d '
{
    "hostUri": "https://example.com/",
    "renderType": "purchase_power",
    "userInfo": {
        "email": "johnsmith@example.com",
        "phone": "607-000-0000",
        "firstName": "John",
        "lastName": "Smith",
        "company": "Gadgets",
        "address": {
            "addressLines": ["120 Main St"],
            "city": "Cooperstown",
            "state": "NY",
            "postalCode": "13326",
            "countryCode": "US"
        }
    }
}'

Sample Response

{
    "purchasePower": {
        "renderType": "iframe",
        "render": "https://...pitneybowes.com/gfs?at=420b9704c81215140b5910f8ee64_1496251276473"
    },
    "accessToken": "420b9704c81215140b5910f8ee64_1496251276473"
}

Error Codes

Code Message
40000011 Missing value for hostUri
40000012 Invalid value for hostUri
40000021 Invalid value for styleSheet
40000051 Invalid value for email
40000071 Missing value for renderType.
40000072 Invalid value for renderType.
Note: For all PB Shipping APIs error codes, see Error Codes.