PayPal Commerce Platform Gateway Guide

close

Services and Compatibility

Payment Gateway Company Name:
PayPal Commerce Platform
Services that work with Spreedly:
  • PayPal Commerce Platform
Supported operations:
Purchase, Authorize, Capture, Refund, Void
Supported payment types:
Credit Card, Paypal
Spreedly 3DS2 Global Supported
No
Gateway Specific 3DS1 Supported
No
Gateway Specific 3D2 Supported
No
Regions:
Asia Pacific, Europe, North America
API endpoint URL:
Multiple; contact success@spreedly.com for more information

Authentication and Security

Specific names for credentials:
Login, Password

Onboarding Merchants in:

Additional Notes

The Spreedly integration to the PayPal Commerce Platform offers two modes of transacting via PayPal

  • Via Spreedly’s offsite payment flow where a user uses a payment method stored at PayPal
  • Using direct credit card transactions from Spreedly’s vault

In both scenarios, it is necessary to reach out to your PayPal account manager to ensure your account is properly configured. The PayPal account manager may need to configure your account to accept raw credit card payment data.

Additionally, if you wish to have a customer’s billing address returned as part of the response, PayPal will need to enable this option. If it is not enabled, then the Spreedly Gateway Specific Response Fields (GSRF) can not be populated as the billing address will not be returned from PayPal to Spreedly.

Gateway Credentials

PayPal has the ability to set-up more than one application within in your configuration. Determine which application you would like to grant Spreedly access to by logging into the PayPal Dashboard and navigating to the My Apps & Credentials

Select the application you want to enable with Spreedly and you will be directed to the following:

You will need the Client Id and Secret when creating a new gateway setup with Spreedly.

Adding a Paypal Commerce Platform Gateway

To add a PayPal Commerce Platform gateway:


curl https://core.spreedly.com/v1/gateways.xml \
-u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
-H 'Content-Type: application/xml' \
-d '<gateway>
  <gateway_type>paypal_commerce_platform</gateway_type>
  <login>client id</login>
  <password>secret</password>
</gateway>'


<gateway>
  <token>2U5SpirSg8IWK5zHRIKwWEvH7mR</token>
  <gateway_type>paypal_commerce_platform</gateway_type>
  <name>PayPal Commerce Platform</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <login>client id</login>
  <characteristics>
    <supports_purchase type="boolean">true</supports_purchase>
    <supports_authorize type="boolean">true</supports_authorize>
    <supports_capture type="boolean">true</supports_capture>
    <supports_credit type="boolean">true</supports_credit>
    <supports_general_credit type="boolean">false</supports_general_credit>
    <supports_void type="boolean">true</supports_void>
    <supports_adjust type="boolean">false</supports_adjust>
    <supports_verify type="boolean">false</supports_verify>
    <supports_reference_purchase type="boolean">false</supports_reference_purchase>
    <supports_purchase_via_preauthorization type="boolean">true</supports_purchase_via_preauthorization>
    <supports_offsite_purchase type="boolean">true</supports_offsite_purchase>
    <supports_offsite_authorize type="boolean">true</supports_offsite_authorize>
    <supports_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
    <supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
    <supports_3dsecure_2_mpi_purchase type="boolean">false</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">false</supports_3dsecure_2_mpi_authorize>
    <supports_store type="boolean">false</supports_store>
    <supports_remove type="boolean">false</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_network_tokenization type="boolean">false</supports_network_tokenization>
    <supports_populate_mit_fields type="boolean">false</supports_populate_mit_fields>
    <supports_reference_authorization type="boolean">true</supports_reference_authorization>
  </characteristics>
  <credentials>
    <credential>
      <name>login</name>
      <value>client id</value>
    </credential>
  </credentials>
  <gateway_settings>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>notify_url</gateway_specific_field>
    <gateway_specific_field>recurring</gateway_specific_field>
    <gateway_specific_field>paypal_request_id</gateway_specific_field>
    <gateway_specific_field>soft_descriptor</gateway_specific_field>
    <gateway_specific_field>invoice_id</gateway_specific_field>
    <gateway_specific_field>custom_id</gateway_specific_field>
    <gateway_specific_field>shipping_method</gateway_specific_field>
    <gateway_specific_field>payment_group_id</gateway_specific_field>
    <gateway_specific_field>insurance</gateway_specific_field>
    <gateway_specific_field>tax_total</gateway_specific_field>
    <gateway_specific_field>handling</gateway_specific_field>
    <gateway_specific_field>shipping_discount</gateway_specific_field>
    <gateway_specific_field>discount</gateway_specific_field>
    <gateway_specific_field>item_total</gateway_specific_field>
    <gateway_specific_field>shipping</gateway_specific_field>
    <gateway_specific_field>landing_page</gateway_specific_field>
    <gateway_specific_field>payee_preferred</gateway_specific_field>
    <gateway_specific_field>user_action</gateway_specific_field>
    <gateway_specific_field>brand_name</gateway_specific_field>
    <gateway_specific_field>shipping_preference</gateway_specific_field>
    <gateway_specific_field>items</gateway_specific_field>
    <gateway_specific_field>payer</gateway_specific_field>
    <gateway_specific_field>application_context</gateway_specific_field>
    <gateway_specific_field>purchase_units</gateway_specific_field>
    <gateway_specific_field>order_only</gateway_specific_field>
    <gateway_specific_field>payee</gateway_specific_field>
    <gateway_specific_field>uuid</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>paypal</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">false</sandbox>
  <created_at type="dateTime">2021-09-08T18:29:51Z</created_at>
  <updated_at type="dateTime">2021-09-08T18:29:51Z</updated_at>
</gateway>

Stored credentials

For Paypal Commerce Platform, sending stored credential fields can be done using Spreedly’s first class support. Sending stored credential data is simple. For any Authorize or Purchase request, you need to include two fields which tell Spreedly a little bit more about the nature of the transaction:

  • stored_credential_initiator
  • stored_credential_reason_type

Learn more about how Spreedly enables seamless use of stored credentials by reviewing our Stored Credentials Guide.

Gateway Specific Fields

The PayPal Commerce Platform has numerous optional parameters available for a transaction. Please note the structure below as it is slightly more complex structure:

  • purchase_units
    • soft_descriptor
    • invoice_id
    • custom_id
    • shipping_method
    • breakdown
      • insurance
      • tax_total
      • handling
      • shipping_discount
      • discount
      • shipping
      • item_total
    • items
      • name
      • sku
      • category
      • quantity
      • tax
      • value
  • application_context
    • landing_page
    • user_action
    • brand_name
    • shipping_preference
  • payee
    • merchant_id
    • email
  • uuid

The follow describes the purpose and usage of each GSF available:

  • soft_descriptor The soft descriptor is the dynamic text used to construct the statement descriptor that appears on a payer’s card statement. Max length is 22 characters.
  • invoice_id Assign a unique invoice id to the PayPal order
  • custom_id Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports
  • shipping_method Text description of type of shipping used for order
  • uuid Allow a unique id to be associated with the order creation, done via the authorize() call, and passed in the header.

If you desire to show transaction level details instead of just a total amount on an order to PayPal, you can use the breakdown[] and items[] array. These two elements are dependent on one another and the sub-totals in these particular arrays must summarize to the order total you submit in the Spreedly amount attribute. For example, if the total purchase amount for a transaction is $100USD and the real breakdown is $90USD for the product and $10USD for taxes you will submit a breakdown like:

{
    "transaction": {
        "amount": "10000",
        "currency_code": "USD",
        "payment_method_token": "WhsZJQF38pRlQ0ipiEtpMp8MKN7",
        "redirect_url": "https://redirect.example.com/",
        "callback_url": "https://callback.example.com/",
        "gateway_specific_fields": {
            "paypal_commerce_platform": {
                 "purchase_units": {
                        "soft_descriptor": "Soft Descriptor",
                        "breakdown": {
                            "item_total":9000,
                            "tax_total": 1000
                        },
                        "items": [
                            {
                                "name": "Widget",
                                "tax": 1000,
                                "value": 9000
                            }
                        ]
                    }
            }
        }
    }
}

The ‘application_context’ values facilitate the end user experience as they login to PayPal in the offsite flow:

  • landing_page Spreedly defaults to LOGIN which indicates to PayPal for a basic user login flow. Other values are:

    • BILLING: Will prompt the user to enter credit card or other billing information to store at PayPal
    • NO_PREFERENCE: The customer is redirected to either a page to log in to PayPal and approve the payment or to a page to enter credit or debit card and other relevant billing information required to complete the purchase, depending on their previous interactions with PayPal.

  • user_action Spreedly defaults to CONTINUE which provides a “Continue” button for the user to click after selecting a payment method type at PayPal and a redirect back to the merchant site. It may be overridden with PAY_NOW which will alter the button to say “Pay Now” for the user to click on the PayPal screen after they select a payment method to use.

  • brand_name The text added here displays on the top of the page where the user is selecting the payment type they will be using, e.g. “My Company Name”

  • shipping_preference Displays the shipping address to the customer, enables the customer to choose an address on the PayPal site, restricts the customer from changing the address during the payment-approval process.

    The possible values are:

    • GET_FROM_FILE. Use the customer-provided shipping address on the PayPal site.
    • NO_SHIPPING. Redact the shipping address from the PayPal site. Recommended for digital goods.
    • SET_PROVIDED_ADDRESS. Use the merchant-provided address. The customer cannot change this address on the PayPal site.

curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/authorize.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
        <amount>100</amount>
        <currency_code>USD</currency_code>
        <gateway_specific_fields>
          <paypal_commerce_platform>
            <notify_url></notify_url>
            <recurring></recurring>
            <paypal_request_id></paypal_request_id>
            <purchase_units>
              <soft_descriptor></soft_descriptor>
              <invoice_id></invoice_id>
              <custom_id></custom_id>
              <shipping_method></shipping_method>
              <payment_group_id></payment_group_id>
              <breakdown>
                <insurance></insurance>
                <tax_total></tax_total>
                <handling></handling>
                <shipping_discount></shipping_discount>
                <discount></discount>
                <shipping></shipping>
                <item_total></item_total>
              </breakdown>
              <items>
                <name></name>
                <sku></sku>
                <category></category>
                <quantity></quantity>
                <tax></tax>
                <value></value>
              </items>
            </purchase_units>
            <payer></payer>
            <application_context>
              <landing_page></landing_page>
              <user_action></user_action>
              <brand_name></brand_name>
              <shipping_preference></shipping_preference>
              <payee_preferred></payee_preferred>
            </application_context>
            <payee>
              <merchant_id></merchant_id>
              <email></email>
            </payee>
            <uuid></uuid>
          </paypal_commerce_platform>
        </gateway_specific_fields>
      </transaction>'


<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2021-09-08T18:29:51Z</created_at>
  <updated_at type="dateTime">2021-09-08T18:29:51Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>3EOABM6a9kBLWUf2aj4d2lVB4Ko</token>
  <transaction_type>Authorization</transaction_type>
  <order_id nil="true"/>
  <ip nil="true"/>
  <description nil="true"/>
  <email nil="true"/>
  <merchant_name_descriptor nil="true"/>
  <merchant_location_descriptor nil="true"/>
  <merchant_profile_key nil="true"/>
  <gateway_specific_fields>
    <paypal_commerce_platform>
      <notify_url nil="true"/>
      <recurring nil="true"/>
      <paypal_request_id nil="true"/>
      <purchase_units>
        <soft_descriptor nil="true"/>
        <invoice_id nil="true"/>
        <custom_id nil="true"/>
        <shipping_method nil="true"/>
        <payment_group_id nil="true"/>
        <breakdown>
          <insurance nil="true"/>
          <tax_total nil="true"/>
          <handling nil="true"/>
          <shipping_discount nil="true"/>
          <discount nil="true"/>
          <shipping nil="true"/>
          <item_total nil="true"/>
        </breakdown>
        <items>
          <name nil="true"/>
          <sku nil="true"/>
          <category nil="true"/>
          <quantity nil="true"/>
          <tax nil="true"/>
          <value nil="true"/>
        </items>
      </purchase_units>
      <payer nil="true"/>
      <application_context>
        <landing_page nil="true"/>
        <user_action nil="true"/>
        <brand_name nil="true"/>
        <shipping_preference nil="true"/>
        <payee_preferred nil="true"/>
      </application_context>
      <payee>
        <merchant_id nil="true"/>
        <email nil="true"/>
      </payee>
      <uuid nil="true"/>
    </paypal_commerce_platform>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
    <payer nil="true"/>
    <first_name>Newfirst</first_name>
    <last_name>Newlast</last_name>
    <billing_street1 nil="true"/>
    <billing_city nil="true"/>
    <billing_state_or_province nil="true"/>
    <billing_country nil="true"/>
    <billing_zip nil="true"/>
    <shipping_name nil="true"/>
    <shipping_address nil="true"/>
  </gateway_specific_response_fields>
  <gateway_transaction_id>58</gateway_transaction_id>
  <gateway_latency_ms type="integer">1</gateway_latency_ms>
  <stored_credential_initiator nil="true"/>
  <stored_credential_reason_type nil="true"/>
  <populate_mit_fields type="boolean">false</populate_mit_fields>
  <warning nil="true"/>
  <application_id nil="true"/>
  <amount type="integer">100</amount>
  <currency_code>USD</currency_code>
  <retain_on_success type="boolean">false</retain_on_success>
  <payment_method_added type="boolean">false</payment_method_added>
  <smart_routed type="boolean">false</smart_routed>
  <message key="messages.transaction_succeeded">Succeeded!</message>
  <gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
  <gateway_type>test</gateway_type>
  <shipping_address>
    <name>Newfirst Newlast</name>
    <address1 nil="true"/>
    <address2 nil="true"/>
    <city nil="true"/>
    <state nil="true"/>
    <zip nil="true"/>
    <country nil="true"/>
    <phone_number nil="true"/>
  </shipping_address>
  <response>
    <success type="boolean">true</success>
    <message>Successful authorize</message>
    <avs_code nil="true"/>
    <avs_message nil="true"/>
    <cvv_code nil="true"/>
    <cvv_message nil="true"/>
    <pending type="boolean">false</pending>
    <result_unknown type="boolean">false</result_unknown>
    <error_code nil="true"/>
    <error_detail nil="true"/>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"/>
    <created_at type="dateTime">2021-09-08T18:29:51Z</created_at>
    <updated_at type="dateTime">2021-09-08T18:29:51Z</updated_at>
  </response>
  <api_urls>
  </api_urls>
  <payment_method>
    <token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
    <created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
    <updated_at type="dateTime">2021-09-07T17:09:47Z</updated_at>
    <email>joey@example.com</email>
    <data>
      <my_payment_method_identifier>448</my_payment_method_identifier>
      <extra_stuff>
        <some_other_things>Can be anything really</some_other_things>
      </extra_stuff>
    </data>
    <storage_state>retained</storage_state>
    <test type="boolean">true</test>
    <metadata>
      <key>string value</key>
    </metadata>
    <callback_url nil="true"/>
    <last_four_digits>1111</last_four_digits>
    <first_six_digits>411111</first_six_digits>
    <card_type>visa</card_type>
    <first_name>Newfirst</first_name>
    <last_name>Newlast</last_name>
    <month type="integer">3</month>
    <year type="integer">2032</year>
    <address1 nil="true"/>
    <address2 nil="true"/>
    <city nil="true"/>
    <state nil="true"/>
    <zip nil="true"/>
    <country nil="true"/>
    <phone_number nil="true"/>
    <company nil="true"/>
    <full_name>Newfirst Newlast</full_name>
    <eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
    <shipping_address1 nil="true"/>
    <shipping_address2 nil="true"/>
    <shipping_city nil="true"/>
    <shipping_state nil="true"/>
    <shipping_zip nil="true"/>
    <shipping_country nil="true"/>
    <shipping_phone_number nil="true"/>
    <payment_method_type>credit_card</payment_method_type>
    <errors>
    </errors>
    <verification_value></verification_value>
    <number>XXXX-XXXX-XXXX-1111</number>
    <fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
  </payment_method>
  <attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>

Gateway specific response fields

Error information

The issue gateway specific response field returns the specific error that PayPal Commerce Platform sends to Spreedly when an error occurs.

Buyer information

If you’re using Paypal with offsite payments, Paypal shares some additional information about transactions. In particular, you can determine the following fields about a buyer after a purchase and after an authorization. Please note, this feature is not enabled by default and it is a setting that the PayPal Account Manager will need to enable for your account:

  • payer
  • first_name
  • last_name
  • street1
  • city_name
  • state_or_province
  • postal_code
  • country
  • shipping name (first and last)
  • shipping address
  • email
  • merchant_id

You can find this information in gateway_specific_response_fields. For example, a transaction could have something like this:

<transaction>
  <token>XspZooGud4SNm5Id9iwHHpWReIs</token>
  <transaction_type>OffsiteAuthorization</transaction_type>
  <gateway_specific_response_fields>
    <paypal_commerce_platform>
      <payer>wax@example.com</payer>
      <first_name>Waxillium</first_name>
      <last_name>Ladrian</last_name>
      <billing_street1>3911 Main Street</billing_street1>
      <billing_city>Wanaque</billing_city>
      <billing_state_or_province>NJ</billing_state_or_province>
      <billing_zip>28592-8851</billing_zip>
      <billing_country>US</billing_country>
      <shipping_name>Waxillium</shipping_name>
      <shipping_address>
        <address_line_1>3911 Main Street</address_line_1>
        <admin_area_2>Wanaque</admin_area_2>
        <admin_area_1>NJ</admin_area_1>
        <postal_code>28592-8851</postal_code>
        <country_code>US</country_code>
      </shipping_address>
      <email>test@example.com</email>
      <merchant_id>MI12ABC890XYZ</merchant_id>
      <issue>TAX_MISMATCH</issue>
    </paypal_commerce_platform>
  </gateway_specific_response_fields>
</transaction>