PayPal Gateway Guide

Services and Compatibility

Payment Gateway Company Name:

PayPal

Services that work with Spreedly:

Paypal Payments Pro
Paypal Payments Standard (see notes)
Paypal Payments Advanced (see notes)

Supported operations:

Purchase, Authorize, Capture, Refund, Void, Verify

Supported payment types:

Credit Card, Paypal

Spreedly 3DS2 Global Supported

Yes

Gateway Specific 3DS2 Supported

Populate MIT GSF Support

Regions:

Asia Pacific, Europe, North America

API endpoint URL:

https://api-3t.paypal.com/2.0/

Authentication and Security

Specific names for credentials:: signature mode:
Login, Password, Signature; certificate mode:
Login, Password, PEM Certificate; delegate mode:
PayPal Email

Onboarding Merchants in:

Canada
New Zealand
United Kingdom
United States

Don’t see your preferred region? Contact Us

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.
Review our Offsite Payment Gateway documentation. 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.

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.

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>fred@example.com</email>
      </gateway>'


<gateway>
  <token>DEkTB74m11BSKbzcraWJApwDxj8</token>
  <gateway_type>paypal</gateway_type>
  <name>PayPal</name>
  <description nil="true"/>
  <email>fred@example.com</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>fred@example.com</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>

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>

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>

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.

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


env = Spreedly::Environment.new('C7cRfNJGODKh4Iu5Ox3PToKjniY', '4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ', base_url: 'https://core.spreedly.com')
env.purchase_on_gateway("LlkjmEk0xNkcWrNixXa1fvNoTP4", "56wyNnSmuA6CWYP7w0MiYCVIbW6", 4432,
  gateway_specific_fields: {
    paypal: {
      recurring: "Y",
      soft_descriptor: "Company Name",
      soft_descriptor_city: "New York",
      allow_guest_checkout: "true",
      no_shipping: "true",
      notify_url: "https://example.com/notify_me",
      custom: "A custom string",
      subtotal: 80,
      shipping: 5,
      handling: 5,
      tax: 10
    }
  }
)


#<Spreedly::Purchase:0x00007f9169a4baa8
@token="SxBwiW27R9hMCSzSj6AISwRHs2l",
@created_at="2019-10-29T15:28:01Z",
@updated_at="2019-10-29T15:28:01Z",
@state="succeeded",
@message="Succeeded!",
@succeeded="true",
@order_id="",
@ip="",
@description="",
@gateway_token="T11bJAANtTWnxl36GYjKWvbNK0g",
@gateway_transaction_id="49",
@email="",
@transaction_type="Purchase",
@merchant_name_descriptor="",
@merchant_location_descriptor="",
@on_test_gateway="true",
@currency_code="USD",
@callback_url="",
@stored_credential_initiator="",
@stored_credential_reason_type="",
@amount="4432",
@response,=
#<Spreedly::Response:0x00007f916c026b38
@success="true",
@pending="false",
@cancelled="false",
@fraud_review="",
@created_at="2019-10-29T15:28:01Z",
@updated_at="2019-10-29T15:28:01Z",
@message="Successful purchase",
@avs_code="",
@avs_message="",
@cvv_code="",
@cvv_message="",
@error_code="",
@error_detail="">,
@shipping_address,=
#<Spreedly::ShippingAddress:0x00007f9169a2b0a0
@name="Newfirst Newlast",
@address1="",
@address2="",
@city="",
@state="",
@zip="",
@country="",
@phone_number="">,
@gateway_specific_fields={:paypal=>{:recurring=>"Y", :soft_descriptor=>"Company Name", :soft_descriptor_city=>"New York", :allow_guest_checkout=>"true", :no_shipping=>"true", :notify_url=>"https://example.com/notify_me", :custom=>"A custom string", :subtotal=>"80", :shipping=>"5", :handling=>"5", :tax=>"10"}},
@gateway_specific_response_fields={},
@payment_method,=
#<Spreedly::CreditCard:0x00007f916b854cc0
@token="1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
@created_at="2017-06-26T17:04:38Z",
@updated_at="2019-10-29T15:28:01Z",
@email="joey@example.com",
@storage_state="retained",
@data="<my_payment_method_identifier>448</my_payment_method_identifier>\n      <extra_stuff>\n        <some_other_things>Can be anything really</some_other_things>\n      </extra_stuff>",
@payment_method_type="credit_card",
@first_name="Newfirst",
@last_name="Newlast",
@full_name="Newfirst Newlast",
@month="3",
@year="2032",
@number="XXXX-XXXX-XXXX-1111",
@last_four_digits="1111",
@first_six_digits="411111",
@card_type="visa",
@verification_value="",
@address1="",
@address2="",
@city="",
@state="",
@zip="",
@country="",
@phone_number="",
@company="",
@fingerprint="e3cef43464fc832f6e04f187df25af497994",
@eligible_for_card_updater="true",
@errors=[]>>

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

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>wax@example.com</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 like:

<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.

PayPal Gateway Guide

Show Payment Gateway Fact Sheet

Services and Compatibility

Authentication and Security

Onboarding Merchants in:

Additional Notes

Delegate mode

Signature mode

Certificate mode

Offsite purchases, ACHs, and IPN notifications

Gateway specific fields

Gateway specific response fields

Buyer information

Billing agreement ID

Sending email addresses