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>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:
General Credit gateway specific fields | |
---|---|
recipient_type | |
recipient_wallet | PAYPAL |
reference_id | general_credit_2020_100007 |
email_subject | You have a payout! |
email_message | You have received a payout! Thanks for using our service! |
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
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 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”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 Creditrecipient_wallet
Required for Payouts via General Creditreference_id
Used in general_credit transaction this represent the transaction id.email_subject
Required for Payouts via General Creditemail_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
- 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>