PayPal Commerce Platform Gateway Guide
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, General Credit
- Supported payment types:
- Credit Card, Paypal
- Spreedly 3DS2 Global Supported
- No
- Gateway Specific 3DS2 Supported
- No
- Populate MIT GSF Support
- 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:
-
Australia
-
Austria
-
Belgium
-
Bulgaria
-
Canada
-
Cyprus
-
Czechia
-
Denmark
-
Estonia
-
Finland
-
France
-
Greece
-
Hungary
-
Italy
-
Latvia
-
Liechtenstein
-
Lithuania
-
Luxembourg
-
Malta
-
Netherlands
-
Norway
-
Poland
-
Portugal
-
Romania
-
Slovakia
-
Slovenia
-
Spain
-
Sweden
-
United States
-
United Kingdom
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
uuid
order_only
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 ordercustom_id
Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reportsshipping_method
Text description of type of shipping used for orderuuid
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
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>
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
- 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>