PayPal Gateway Guide

PayPal fact sheet

Additional notes
Spreedly gives you full control over the look and feel of your payment page. If you are going to use PayPal as your payment gateway for accepting credit cards then you must have a PayPal Payments Pro account. Pro is the only PayPal account that supports having your own unique payments page/form. If PayPal Payments Pro isn’t offered in your region you have two options: - Find out if Payflow Pro is offered in your region. Payflow Pro will still allow you to completely control the payment form and checkout process. - Using the offsite payment flow will not allow you to completely control your payment page/form nor will it allow you to accept credit cards. You will however be able to offer Paypal as a payment type.
If offering PayPal as a payment type is important you can always use a traditional gateway like Stripe, Braintree, or PayMill for credit cards and then use PayPal Payments Standard as a secondary gateway for PayPal payments. If using special characters, please check the merchant settings in your Paypal dashboard and allow for these. Not doing so may result in a callback error from Spreedly, “Unverified call: probably not from PayPal”. Please reach out to Paypal Support with any questions about making changes to your merchant settings.

Additional notes

Spreedly gives you full control over the look and feel of your payment page. If you are going to use PayPal as your payment gateway for accepting credit cards then you must have a PayPal Payments Pro account. Pro is the only PayPal account that supports having your own unique payments page/form. If PayPal Payments Pro isn’t offered in your region you have two options:

- Find out if Payflow Pro is offered in your region. Payflow Pro will still allow you to completely control the payment form and checkout process.
- Using the offsite payment flow will not allow you to completely control your payment page/form nor will it allow you to accept credit cards. You will however be able to offer Paypal as a payment type.

If offering PayPal as a payment type is important you can always use a traditional gateway like Stripe, Braintree, or PayMill for credit cards and then use PayPal Payments Standard as a secondary gateway for PayPal payments.

If using special characters, please check the merchant settings in your Paypal dashboard and allow for these. Not doing so may result in a callback error from Spreedly, “Unverified call: probably not from PayPal”. Please reach out to Paypal Support with any questions about making changes to your merchant settings.

Adding a PayPal gateway

There are three different “modes” that you can use to authenticate with PayPal: Delegate, Signature, and Certificate. Which mode you decide to use is up to you; we’ve put them here in order of “ease to implement”.

Delegate mode

To use delegate mode you need to grant Spreedly API access to your PayPal account. To do that, go into your PayPal profile and click on “Request API Credentials”:

Next, choose “Set up PayPal API credentials and permissions” under Option 1:

Next, select “Grant API permission” under Option 1:

Now give “nathaniel_api1.spreedly.com” full permissions. Then check the following boxes:

Save & verify completion. Once the permissions are set up, all you need to do is pass the “delegate” mode and the email address of your PayPal account:

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>paypal</gateway_type>
        <mode>delegate</mode>
        <email>[email protected]</email>
      </gateway>'

<gateway>
  <token>DEkTB74m11BSKbzcraWJApwDxj8</token>
  <gateway_type>paypal</gateway_type>
  <name>PayPal</name>
  <description nil="true"/>
  <email>[email protected]</email>
  <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">true</supports_verify>
    <supports_reference_purchase type="boolean">true</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">true</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
    <supports_store type="boolean">false</supports_store>
    <supports_remove type="boolean">true</supports_remove>
    <supports_fraud_review type="boolean">true</supports_fraud_review>
    <supports_network_tokenization type="boolean">false</supports_network_tokenization>
    <supports_reference_authorization type="boolean">true</supports_reference_authorization>
  </characteristics>
  <credentials>
    <credential>
      <name>email</name>
      <value>[email protected]</value>
    </credential>
  </credentials>
  <gateway_settings>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>recurring</gateway_specific_field>
    <gateway_specific_field>notify_url</gateway_specific_field>
    <gateway_specific_field>custom</gateway_specific_field>
    <gateway_specific_field>soft_descriptor</gateway_specific_field>
    <gateway_specific_field>soft_descriptor_city</gateway_specific_field>
    <gateway_specific_field>allow_guest_checkout</gateway_specific_field>
    <gateway_specific_field>subtotal</gateway_specific_field>
    <gateway_specific_field>shipping</gateway_specific_field>
    <gateway_specific_field>handling</gateway_specific_field>
    <gateway_specific_field>tax</gateway_specific_field>
    <gateway_specific_field>no_shipping</gateway_specific_field>
    <gateway_specific_field>payment_details_item_type</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">2020-12-30T15:19:51Z</created_at>
  <updated_at type="dateTime">2020-12-30T15:19:51Z</updated_at>
  <mode>delegate</mode>
</gateway>

To learn more about creating and managing gateways in our Marketplace, review the Gateway user guide. For gateways not included in the Marketplace, review the steps below.

Create a gateway

Visit your Connections area to review all gateways and add new ones. When creating your gateways, select the gateway name and authentication mode (if prompted) before completing required fields. Select ☑️Sandbox to create a gateway in Sandbox mode, for processing test card data and transactions in your Spreedly environment.

For delegate mode, follow the above instructions before entering your email in the Email field.

Signature mode

To use signature mode you need to issue a PayPal signature. To do that, go into your PayPal profile and click on “Request API Credentials”:

Next, choose “Set up PayPal API credentials and permissions” under Option 1:

Next, select “Request API credentials” under Option 2:

Next, select “Request API signature”:

You should see the credentials; these are what you’ll need to plug in to Core:

Click “Done”. Once you have your API login, password and signature, just pass them in with a mode of signature:

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

<gateway>
  <token>XtLtE6Cz8OVG7Qhx0IW7JFTjRo6</token>
  <gateway_type>paypal</gateway_type>
  <name>PayPal</name>
  <description nil="true"/>
  <login>login</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">true</supports_verify>
    <supports_reference_purchase type="boolean">true</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">true</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
    <supports_store type="boolean">false</supports_store>
    <supports_remove type="boolean">true</supports_remove>
    <supports_fraud_review type="boolean">true</supports_fraud_review>
    <supports_network_tokenization type="boolean">false</supports_network_tokenization>
    <supports_reference_authorization type="boolean">true</supports_reference_authorization>
  </characteristics>
  <credentials>
    <credential>
      <name>login</name>
      <value>login</value>
    </credential>
  </credentials>
  <gateway_settings>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>recurring</gateway_specific_field>
    <gateway_specific_field>notify_url</gateway_specific_field>
    <gateway_specific_field>custom</gateway_specific_field>
    <gateway_specific_field>soft_descriptor</gateway_specific_field>
    <gateway_specific_field>soft_descriptor_city</gateway_specific_field>
    <gateway_specific_field>allow_guest_checkout</gateway_specific_field>
    <gateway_specific_field>subtotal</gateway_specific_field>
    <gateway_specific_field>shipping</gateway_specific_field>
    <gateway_specific_field>handling</gateway_specific_field>
    <gateway_specific_field>tax</gateway_specific_field>
    <gateway_specific_field>no_shipping</gateway_specific_field>
    <gateway_specific_field>payment_details_item_type</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">2020-12-30T15:19:50Z</created_at>
  <updated_at type="dateTime">2020-12-30T15:19:50Z</updated_at>
  <mode>signature</mode>
</gateway>

To learn more about creating and managing gateways in our Marketplace, review the Gateway user guide. For gateways not included in the Marketplace, review the steps below.

Create a gateway

In signature mode, supply your API username to the login field, along with your password and signature to create a new PayPal gateway.

Certificate mode

To use certificate mode you need to issue a PayPal certificate. To do that, go into your PayPal profile and click on “Request API Credentials”:

Next, choose “Set up PayPal API credentials and permissions” under Option 1:

Next, select “Request API credentials” under Option 2:

Next, select “Request API certificate”:

You should see the credentials; you will need to save the login and password and download the certificate:

Click “Done”. Once you have your API login, password and pem certificate, you need to pass them all to Core. When making your curl request, note that the pem certificate has necessary newlines in it. If you’re allowing your customers to enter their pem in your UI, we recommend a text area for it rather than a text field.

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
          <gateway_type>paypal</gateway_type>
          <mode>certificate</mode>
          <login>login</login>
          <password>password</password>
          <pem>-----BEGIN RSA PRIVATE KEY-----
MIIEogIBAAKCAQEAn0hOiAqdiHgp94A/cB+YxqQTPJynzTHZmCGxKylRf4sd0Mrs
SD8kzhaGoUo4/KUSXuATjHpfnBbtHWWVzbN7V8y0457q0qo76jSQj8ce+bfOGatN
FPirNZ35Tw8W2o9v1GJeSEsRFCudd2kAoJOOF5Gf7quDzWk/0LpIcAb8sKZ7amNV
fQF4KIyoLF/wSdXA2A5KkuFBdenQcqjD3OwTk2lbQBeT1fuZYHjTK1T3id2/pHMZ
1aobTeXwnt+y+8W79TtiCYFCPpsjV3rmBxwflsshd+LbDpt6+fUhmNxIHA2NuJtd
I7a9XkNk7EehVZKKvc/MRm4hVxHJrgrvyI+i9QIDAQABAoIBADhTMmoLDu/+RiDe
ehBlK/o6dQ7++pumICMa7vKrVsV6ZV27FFjr81DpSExq2cIFgXyJUoBfmcWxmcHG
dXXbHSfMHL9NKA684hkM433kVQDLTZdoKwbadHiuV0XsuREqncoFyv9XhD+UuMdM
G0utQhb1iQ+2GRKfQFDIPutWnS698ZFJ8vVkPZbX/nNbnhM8Ct/8qyj6IyOJleJI
jAUNM1m9o9Ox1ggG6q2Ey2XaSzkamqK2b4xDm88Z0kGJUTvv67zQzydFa07HVLae
bWppGBZDghNjA4IsFjT3w++6D5rwSJEnXLfEkhs/GW19bMG53srlW3pCfkH7Rm0S
zr+RSYECgYEAz7kYbbDMc8VcYK5A9LFn8t1JgNAGE+oL/zvDVlVeDFDdM26hzvDe
VwN3vCqXIziXFAnlECWXU+NIYSdoNjJFMX38xapIw3hmEN153RPLd0bHckNyPd5q
GbLvL+Ohq9sSguvwDAPpJM7LO2xdEd/k0fATKqT1+2Mph8fQcyq/SFUCgYEAxE0j
7lsAZHImZopIR8uHOJwpVKmOgPBp6fW063lKnm4uScKSvy99fNDi/UeeWKjrhLeK
LgXNeR91vsvmJEIxdqEgXbzxZO8/pjB9ITL1blCo2KFElZNC6ArxNg66D1XIPs0R
UhV145bpkWJpuUHuLtCVzJgoVRfvR0Zq9dXaECECgYAC0iasxqvgHpwEjBlBuW8J
80tePnT2rEUBcFRUxdADJs36NtRntQmv8NIdcg6fYdNbaE7+CySk9P80oo5dvg0G
gQl/vbJDRU1NiVRwViZ7NjDbMmNIx851DuMEqXi2lsEHmiCmaR8vaseDxRL2fS3k
U/hOqfLVOSGFQIdqKPh0CQKBgAwNkH86JzQDrkfthbKi1JKtQ/xmzNEt8dLju1Aa
CnLf4Qe2YrxKdjILwWQ72YUoGg30Fw/sW0lsnRYx/teLGO5nxkz7JPdFmWri30wC
jP9RBI0ImeV1PU5yHY1sKhB2++yfOskHeE2ZHo5GtKcjXTSSqh/917wh1BdUQ40E
rHcBAoGAMtXp+rfxxBxQWZUpxFHgdWXPn+5MtkFtSUQ3QJD8HyIsRLc6YP1iggd8
pN+wWJY+cL31XAyqNA2GA8+vf2JD/pVHqHREbRXtrwuFN9SdWBO1SLTNPW2ni42E
L2qsUyUaOIRteOE0kUR3YkDrtGMr1n7KgRArpeDZSxssQJHX98U=
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
MIIEogIBAAKCAQEAn0hOiAqdiHgp94A/cB+YxqQTPJynzTHZmCGxKylRf4sd0Mrs
SD8kzhaGoUo4/KUSXuATjHpfnBbtHWWVzbN7V8y0457q0qo76jSQj8ce+bfOGatN
FPirNZ35Tw8W2o9v1GJeSEsRFCudd2kAoJOOF5Gf7quDzWk/0LpIcAb8sKZ7amNV
fQF4KIyoLF/wSdXA2A5KkuFBdenQcqjD3OwTk2lbQBeT1fuZYHjTK1T3id2/pHMZ
1aobTeXwnt+y+8W79TtiCYFCPpsjV3rmBxwflsshd+LbDpt6+fUhmNxIHA2NuJtd
I7a9XkNk7EehVZKKvc/MRm4hVxHJrgrvyI+i9QIDAQABAoIBADhTMmoLDu/+RiDe
ehBlK/o6dQ7++pumICMa7vKrVsV6ZV27FFjr81DpSExq2cIFgXyJUoBfmcWxmcHG
dXXbHSfMHL9NKA684hkM433kVQDLTZdoKwbadHiuV0XsuREqncoFyv9XhD+UuMdM
G0utQhb1iQ+2GRKfQFDIPutWnS698ZFJ8vVkPZbX/nNbnhM8Ct/8qyj6IyOJleJI
jAUNM1m9o9Ox1ggG6q2Ey2XaSzkamqK2b4xDm88Z0kGJUTvv67zQzydFa07HVLae
bWppGBZDghNjA4IsFjT3w++6D5rwSJEnXLfEkhs/GW19bMG53srlW3pCfkH7Rm0S
zr+RSYECgYEAz7kYbbDMc8VcYK5A9LFn8t1JgNAGE+oL/zvDVlVeDFDdM26hzvDe
VwN3vCqXIziXFAnlECWXU+NIYSdoNjJFMX38xapIw3hmEN153RPLd0bHckNyPd5q
GbLvL+Ohq9sSguvwDAPpJM7LO2xdEd/k0fATKqT1+2Mph8fQcyq/SFUCgYEAxE0j
7lsAZHImZopIR8uHOJwpVKmOgPBp6fW063lKnm4uScKSvy99fNDi/UeeWKjrhLeK
LgXNeR91vsvmJEIxdqEgXbzxZO8/pjB9ITL1blCo2KFElZNC6ArxNg66D1XIPs0R
UhV145bpkWJpuUHuLtCVzJgoVRfvR0Zq9dXaECECgYAC0iasxqvgHpwEjBlBuW8J
80tePnT2rEUBcFRUxdADJs36NtRntQmv8NIdcg6fYdNbaE7+CySk9P80oo5dvg0G
gQl/vbJDRU1NiVRwViZ7NjDbMmNIx851DuMEqXi2lsEHmiCmaR8vaseDxRL2fS3k
U/hOqfLVOSGFQIdqKPh0CQKBgAwNkH86JzQDrkfthbKi1JKtQ/xmzNEt8dLju1Aa
CnLf4Qe2YrxKdjILwWQ72YUoGg30Fw/sW0lsnRYx/teLGO5nxkz7JPdFmWri30wC
jP9RBI0ImeV1PU5yHY1sKhB2++yfOskHeE2ZHo5GtKcjXTSSqh/917wh1BdUQ40E
rHcBAoGAMtXp+rfxxBxQWZUpxFHgdWXPn+5MtkFtSUQ3QJD8HyIsRLc6YP1iggd8
pN+wWJY+cL31XAyqNA2GA8+vf2JD/pVHqHREbRXtrwuFN9SdWBO1SLTNPW2ni42E
L2qsUyUaOIRteOE0kUR3YkDrtGMr1n7KgRArpeDZSxssQJHX98U=
-----END CERTIFICATE-----
</pem>
      </gateway>'

<gateway>
  <token>K09DZ1z6svNAGhsL3h1slKVZH7m</token>
  <gateway_type>paypal</gateway_type>
  <name>PayPal</name>
  <description nil="true"/>
  <login>login</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">true</supports_verify>
    <supports_reference_purchase type="boolean">true</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">true</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
    <supports_store type="boolean">false</supports_store>
    <supports_remove type="boolean">true</supports_remove>
    <supports_fraud_review type="boolean">true</supports_fraud_review>
    <supports_network_tokenization type="boolean">false</supports_network_tokenization>
    <supports_reference_authorization type="boolean">true</supports_reference_authorization>
  </characteristics>
  <credentials>
    <credential>
      <name>login</name>
      <value>login</value>
    </credential>
  </credentials>
  <gateway_settings>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>recurring</gateway_specific_field>
    <gateway_specific_field>notify_url</gateway_specific_field>
    <gateway_specific_field>custom</gateway_specific_field>
    <gateway_specific_field>soft_descriptor</gateway_specific_field>
    <gateway_specific_field>soft_descriptor_city</gateway_specific_field>
    <gateway_specific_field>allow_guest_checkout</gateway_specific_field>
    <gateway_specific_field>subtotal</gateway_specific_field>
    <gateway_specific_field>shipping</gateway_specific_field>
    <gateway_specific_field>handling</gateway_specific_field>
    <gateway_specific_field>tax</gateway_specific_field>
    <gateway_specific_field>no_shipping</gateway_specific_field>
    <gateway_specific_field>payment_details_item_type</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">2020-12-30T15:19:50Z</created_at>
  <updated_at type="dateTime">2020-12-30T15:19:50Z</updated_at>
  <mode>certificate</mode>
</gateway>

To learn more about creating and managing gateways in our Marketplace, review the Gateway user guide. For gateways not included in the Marketplace, review the steps below.

Create a gateway

For certificate mode, enter your API username into the login field, along with password and paste in your pem to create a new PayPal gateway.

Offsite purchases, ACHs, and IPN notifications

If you allow Paypal offsite payments, you’ll need to change the language encoding configuration in your account from windows-1252 to UTF-8. You will also need to adjust your gateway settings to enable Spreedly to hear about the state of payments as their status changes over time. To make the change, you’ll notice the following link in your Profile settings:

When you click that link, Paypal will bring you to an area where you can enable IPN notifications. You’ll want to enable notifications and specify the notification URL as https://core.spreedly.com/paypal/ipn/dev/null. This will allow Spreedly to hear about changes such as when the funds for an ACH actually reach your account. And then Spreedly can notify you with an offsite callback.

Syncing transactions

Spreedly supports updating the status of transactions that have been initiated at the Paypal gateway. Paypal currently supports using gateway_transaction_id for updates. The gateway_transaction_id would be the payment unique identifier. See our documentation for more information.

Gateway specific fields

When interacting with a PayPal gateway to run transactions, there are some gateway specific fields you can specify when making a purchase or authorize call.

Paypal allows a special recurring flag to be used to indicate that you have a billing agreement in place with your customer. This flag may lower your decline rates.

You can specify an IPN listener for a specific payment using the notify_url attribute.

The custom attribute allows you to specify any custom string to send along with the transaction.

Paypal allows you to set no_shipping to true to prevent shipping info being displayed when you’re using offsite payments with Paypal Express.

To allow your customers to checkout with PayPal Express without signing in, set allow_guest_checkout to true. For this to work, please ensure that you have “PayPal Account Optional” turned ON for your gateway account.

The subtotal, shipping, handling, and tax fields can be sent to specify these values for the transaction. In order to use any of these fields, all four fields must be sent and should add up to the order total.

The payment_details_item_type fields can be used to specify the details about each individual item in an order. These fields are supported for both PayPal and PayPal Express. For offsite transactions, this should show the line items on the PayPal Express hosted payment page.

These gateway specific fields may be added as shown in this example:

curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.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>
            <recurring>Y</recurring>
            <soft_descriptor>Company Name</soft_descriptor>
            <soft_descriptor_city>New York</soft_descriptor_city>
            <allow_guest_checkout>true</allow_guest_checkout>
            <no_shipping>true</no_shipping>
            <notify_url>https://example.com/notify_me</notify_url>
            <custom>A custom string</custom>
            <subtotal>80</subtotal>
            <shipping>5</shipping>
            <handling>5</handling>
            <tax>10</tax>
            <payment_details_item_type>
              <items>
                <name>Item one name</name>
                <number>1</number>
                <quantity>1</quantity>
                <item_amount>50</item_amount>
                <description>Item one description</description>
              </items>
              <items>
                <name>Item two name</name>
                <number>2</number>
                <quantity>1</quantity>
                <item_amount>50</item_amount>
                <description>Item two description</description>
              </items>
            </payment_details_item_type>
          </paypal>
        </gateway_specific_fields>
      </transaction>'

<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2019-10-29T15:28:01Z</created_at>
  <updated_at type="dateTime">2019-10-29T15:28:01Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>YbQjpbiAechlZDC8aEOzjb8LyQW</token>
  <transaction_type>Purchase</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"/>
  <gateway_specific_fields>
    <paypal>
      <recurring>Y</recurring>
      <soft_descriptor>Company Name</soft_descriptor>
      <soft_descriptor_city>New York</soft_descriptor_city>
      <allow_guest_checkout>true</allow_guest_checkout>
      <no_shipping>true</no_shipping>
      <notify_url>https://example.com/notify_me</notify_url>
      <custom>A custom string</custom>
      <subtotal>80</subtotal>
      <shipping>5</shipping>
      <handling>5</handling>
      <tax>10</tax>
      <payment_details_item_type>
        <items type="array">
          <item>
            <name>Item one name</name>
            <number>1</number>
            <quantity>1</quantity>
            <item_amount>50</item_amount>
            <description>Item one description</description>
          </item>
          <item>
            <name>Item two name</name>
            <number>2</number>
            <quantity>1</quantity>
            <item_amount>50</item_amount>
            <description>Item two description</description>
          </item>
        </items>
      </payment_details_item_type>
    </paypal>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>64</gateway_transaction_id>
  <gateway_latency_ms type="integer">10</gateway_latency_ms>
  <stored_credential_initiator nil="true"/>
  <stored_credential_reason_type nil="true"/>
  <warning 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>
  <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 purchase</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">2019-10-29T15:28:01Z</created_at>
    <updated_at type="dateTime">2019-10-29T15:28:01Z</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">2019-10-29T15:28:00Z</updated_at>
    <email>[email protected]</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>

In addition, the recurring flag can be used with reference transactions.

curl https://core.spreedly.com/v1/transactions/KS3oZgWXCfFeirK16anYbijLxR/purchase.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <amount>80</amount>
        <gateway_specific_fields>
          <paypal>
            <recurring>Y</recurring>
          </paypal>
        </gateway_specific_fields>
      </transaction>'

<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2019-10-29T15:28:01Z</created_at>
  <updated_at type="dateTime">2019-10-29T15:28:01Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>GguPhw7th3SioNohPEZvQODWZzz</token>
  <transaction_type>PurchaseViaReference</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"/>
  <gateway_specific_fields>
    <paypal>
      <recurring>Y</recurring>
    </paypal>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>45</gateway_transaction_id>
  <gateway_latency_ms type="integer">0</gateway_latency_ms>
  <stored_credential_initiator nil="true"/>
  <stored_credential_reason_type nil="true"/>
  <warning nil="true"/>
  <amount type="integer">80</amount>
  <currency_code>USD</currency_code>
  <message key="messages.transaction_succeeded">Succeeded!</message>
  <gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
  <gateway_type>test</gateway_type>
  <shipping_address>
    <name nil="true"/>
    <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 purchase</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">2019-10-29T15:28:01Z</created_at>
    <updated_at type="dateTime">2019-10-29T15:28:01Z</updated_at>
  </response>
  <api_urls>
  </api_urls>
  <reference_token>ONL7QUzV5gnuc8OMJK3rlm6MEf</reference_token>
</transaction>

Gateway specific response fields

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 a purchase via preauth:

payer
first_name
last_name
street1
street2
city_name
state_or_province
postal_code
country

You can determine the following fields about a buyer after an authorization:

billing street
billing city
billing state
billing country code
billing country
billing postal code

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>Purchase</transaction_type>
  <gateway_specific_response_fields>
    <paypal>
      <payer>[email protected]</payer>
      <first_name>Waxillium</first_name>
      <last_name>Ladrian</last_name>
      <street1>3911 Main Street</street1>
      <street2>Apartment 3</street2>
      <city_name>Wanaque</city_name>
      <state_or_province>NJ</state_or_province>
      <postal_code>28592-8851</postal_code>
      <country>US</country>
    </paypal>
  </gateway_specific_response_fields>
</transaction>

Billing agreement ID

billing_agreement_id from a purchase (or a purchase via preauth) transaction is included under gateway_specific_response_fields and shows up as:

<transaction>
  <token>XspZooGud4SNm5Id9iwHHpWReIs</token>
  <transaction_type>Purchase</transaction_type>
  <gateway_specific_response_fields>
    <paypal>
      <billing_agreement_id>B-6HS9055508963942J</billing_agreement_id>
    </paypal>
  </gateway_specific_response_fields>
</transaction>

Sending email addresses

Paypal expects email to be passed as part of the address. If the address is not sent, the email will not be sent either. If you don’t collect a customer address as part of your transaction flow, but still want the email parameter to be passed, you can populate the address section with default details.