• Documentation
• PayPal Commerce Platform

PayPal Commerce Platform Gateway Guide

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>YovvB1bIN56lvJedMbTBiqGg4CG</token>
  <gateway_type>paypal_commerce_platform</gateway_type>
  <name>PayPal Commerce Platform</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <sub_merchant_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">true</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_offsite_synchronous_authorize type="boolean">false</supports_offsite_synchronous_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_inquire_by_order_id type="boolean">false</supports_inquire_by_order_id>
    <supports_transaction_retry type="boolean">false</supports_transaction_retry>
    <supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
    <supports_reference_authorization type="boolean">true</supports_reference_authorization>
    <supports_stored_credentials type="boolean">true</supports_stored_credentials>
  </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_field>recipient_type</gateway_specific_field>
    <gateway_specific_field>recipient_wallet</gateway_specific_field>
    <gateway_specific_field>reference_id</gateway_specific_field>
    <gateway_specific_field>email_subject</gateway_specific_field>
    <gateway_specific_field>email_message</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>
  <mode>default</mode>
  <created_at type="dateTime">2022-12-04T00:20:28Z</created_at>
  <updated_at type="dateTime">2022-12-04T00:20:28Z</updated_at>
</gateway>

Payouts via General Credit

Performing payouts to a Paypal or Venmo recipient on Paypal Commerce Platform can be done using the General Credit transaction type. However, some additional Gateway Specific Fields are required:

• recipient_type The ID type that identifies the payment receiver.

  The possible values for recipient_type are:

  • EMAIL. An unencrypted email. Value is a string of up to 127 single-byte characters.
  • PHONE. An unencrypted phone number.
  • PAYPAL_ID. An encrypted PayPal account number.

• recipient_wallet The wallet where the recipient receives the payout. Payouts to Venmo recipients require a ‘note’ string and a US mobile phone number.

  The possible values for recipient_wallet are:

  • PAYPAL. PayPal Wallet.
  • VENMO. Venmo Wallet.
  • RECIPIENT_SELECTED. Recipient selects how to receive payment from payment options.

• reference_id Used in general_credit transaction this represent the transaction id.

• email_subject The email message that PayPal sends when the payout item completes. The message is the same for all recipients. Value is an alphanumeric string of up to 1000 single-byte characters.

• email_message The subject line for the email that PayPal sends when payment for a payout item completes. The subject line is the same for all recipients. Value is an alphanumeric string of up to 255 single-byte characters.

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
• order_only
• recipient_type
• recipient_wallet
• reference_id
• email_subject
• email_message

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.
• order_only
  • If order_only:true attribute is set during an authorize() call, Spreedly will still initiate the PayPal offsite flow with Paypal, however, only a new order will be created at PayPal. Spreedly will not automatically perform a subsequent authorization on the order after a user authenticates and approves the order at PayPal.
  • To authorize the stand-alone order at PayPal, an authorization by reference call will need to be made. To complete the authorization of the order, the Spreedly transaction token from the first authorization call will be passed back to Spreedly like: https://core.spreedly.com/v1/transactions/{authorization token}/authorize.json. It is important to note that:
    • The original amount from the order must be passed.
    • A callback URL must be passed.

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”

• recipient_type The ID type that identifies the payment receiver. this field is required and have a max value of up to 127 single-byte characters.

  The possible values for recipient_type are:

  • EMAIL. An unencrypted email. Value is a string of up to 127 single-byte characters.
  • PHONE. An unencrypted phone number.
  • PAYPAL_ID. An encrypted PayPal account number.

• recipient_wallet It is an optional field and represent the wallet where the recipient receives the general credit. General Credit to Venmo recipients require a 'note’ string and a US mobile phone number.

  The possible values for recipient_wallet are:

  • PAYPAL. PayPal Wallet.
  • VENMO. Venmo Wallet.
  • RECIPIENT_SELECTED. Recipient selects how to receive payment from payment options.

• reference_id It is an optional field that represent the transaction id.

• email_message It is an optional field that represent the message that PayPal sends when the general credit completes. The message is the same for all recipients..

• email_subject The subject line for the email that PayPal sends when a general credit completes. The subject line is the same for all recipients. Value is an alphanumeric string of up to 255 single-byte characters.

• 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 for shipping_preference 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.

• recipient_type Required for Payouts via General Credit

• recipient_wallet Required for Payouts via General Credit

• reference_id Used in general_credit transaction this represent the transaction id.

• email_subject Required for Payouts via General Credit

• email_message Required for Payouts via General Credit

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>
            <recipient_type></recipient_type>
            <recipient_wallet></recipient_wallet>
            <reference_id></reference_id>
            <email_subject></email_subject>
            <email_message></email_message>
          </paypal_commerce_platform>
        </gateway_specific_fields>
      </transaction>'

<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2022-12-04T00:24:49Z</created_at>
  <updated_at type="dateTime">2022-12-04T00:24:50Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>NYyFzxf1a31zI93U1l6Q8r7PJuR</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"/>
      <recipient_type nil="true"/>
      <recipient_wallet nil="true"/>
      <reference_id nil="true"/>
      <email_subject nil="true"/>
      <email_message nil="true"/>
    </paypal_commerce_platform>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>51</gateway_transaction_id>
  <sub_merchant_key nil="true"/>
  <gateway_latency_ms type="integer">4</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>
  <local_amount nil="true"/>
  <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>7tY7mfrjxCbC0Q2CRhAH118eeB9</gateway_token>
  <gateway_type>test</gateway_type>
  <shipping_address>
    <name>Siobhan Schinner</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">2022-12-04T00:24:50Z</created_at>
    <updated_at type="dateTime">2022-12-04T00:24:50Z</updated_at>
  </response>
  <api_urls>
  </api_urls>
  <payment_method>
    <token>YG8bfuWeZftCmn0oxj2D46UMViU</token>
    <created_at type="dateTime">2022-12-03T23:53:59Z</created_at>
    <updated_at type="dateTime">2022-12-04T00:14:19Z</updated_at>
    <email nil="true"/>
    <data nil="true"/>
    <storage_state>retained</storage_state>
    <test type="boolean">true</test>
    <metadata nil="true"/>
    <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>Siobhan</first_name>
    <last_name>Schinner</last_name>
    <month type="integer">4</month>
    <year type="integer">2027</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>Siobhan Schinner</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"/>
    <issuer_identification_number>41111111</issuer_identification_number>
    <click_to_pay type="boolean">false</click_to_pay>
    <payment_method_type>credit_card</payment_method_type>
    <errors>
    </errors>
    <verification_value></verification_value>
    <number>XXXX-XXXX-XXXX-1111</number>
    <fingerprint nil="true"/>
  </payment_method>
  <attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>

Please refer to using a payment method for more information on how to send GSFs

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
• national_number

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>
      <national_number>0011234567890</national_number>
    </paypal_commerce_platform>
  </gateway_specific_response_fields>
</transaction>