PayPal Gateway Guide

close

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
Regions:
Europe, North America

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:

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.

There are actually 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”:

Paypal Profile Page
Next, choose “Set up PayPal API credentials and permissions” under Option 1:
Paypal Select Credentials Page

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

Paypal Grant API Permission Page

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

Paypal Delegate API Permissions

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 'Ll6fAtoVSTyVMlJEmtpoJV8S:RKOCG5D8D3fZxDSg504D0IxU2XD4Io5VXmyzdCtTivHFTTSy' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>paypal</gateway_type>
        <mode>delegate</mode>
        <email>fred@example.com</email>
      </gateway>'

<gateway>
  <token>87HRcgt8DQ4Zyq1QECKyvrkwV8W</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_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_store type="boolean">false</supports_store>
    <supports_remove type="boolean">true</supports_remove>
    <supports_fraud_review type="boolean">true</supports_fraud_review>
    <supports_disburse type="boolean">true</supports_disburse>
  </characteristics>
  <credentials>
    <credential>
      <name>email</name>
      <value>fred@example.com</value>
    </credential>
  </credentials>
  <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>no_shipping</gateway_specific_field>
    <gateway_specific_field>email_subject</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>
  <created_at type="dateTime">2016-08-11T17:15:32Z</created_at>
  <updated_at type="dateTime">2016-08-11T17:15:33Z</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”:

Paypal Profile Page

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

Paypal Select Credentials Page

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

Paypal Request Credentials Page

Next, select “Request API signature”:

Paypal Select API Signature Page

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

Paypal Signature Page

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 'Ll6fAtoVSTyVMlJEmtpoJV8S:RKOCG5D8D3fZxDSg504D0IxU2XD4Io5VXmyzdCtTivHFTTSy' \
  -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>P7DKXTcDpQf7DPDYLZWKr4iKU1d</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_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_store type="boolean">false</supports_store>
    <supports_remove type="boolean">true</supports_remove>
    <supports_fraud_review type="boolean">true</supports_fraud_review>
    <supports_disburse type="boolean">true</supports_disburse>
  </characteristics>
  <credentials>
    <credential>
      <name>login</name>
      <value>login</value>
    </credential>
  </credentials>
  <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>no_shipping</gateway_specific_field>
    <gateway_specific_field>email_subject</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>
  <created_at type="dateTime">2016-08-11T17:15:39Z</created_at>
  <updated_at type="dateTime">2016-08-11T17:15:39Z</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”:

Paypal Profile Page

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

Paypal Select Credentials Page

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

Paypal Request Credentials Page

Next, select “Request API certificate”:

Paypal Select API Certificate Page

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

Paypal Certificate Credentials Page

Click “Done”.

Once you have your API login, password and pem certificate, you need to pass them all to Core. The curl for this is a bit tricky since the pem certificate has newlines in it. The newlines in the pem are necessary; 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 'Ll6fAtoVSTyVMlJEmtpoJV8S:RKOCG5D8D3fZxDSg504D0IxU2XD4Io5VXmyzdCtTivHFTTSy' \
  -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>LhioDIX40bbJyevdrOLq8L3P1XA</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_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_store type="boolean">false</supports_store>
    <supports_remove type="boolean">true</supports_remove>
    <supports_fraud_review type="boolean">true</supports_fraud_review>
    <supports_disburse type="boolean">true</supports_disburse>
  </characteristics>
  <credentials>
    <credential>
      <name>login</name>
      <value>login</value>
    </credential>
  </credentials>
  <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>no_shipping</gateway_specific_field>
    <gateway_specific_field>email_subject</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>
  <created_at type="dateTime">2016-08-11T17:15:32Z</created_at>
  <updated_at type="dateTime">2016-08-11T17:15:32Z</updated_at>
  <mode>certificate</mode>
</gateway>


Offsite Purchases, EChecks, IPN notifications

If you’re planning on allowing Paypal offsite payments, there is one setting you’ll need to adjust in your gateway settings to allow 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:

Paypal Profile Page

When you click that link, Paypal will bring you to an area where you can enable IPN notifications. You’ll want to enable them and specify the url such that your settings look like this:

Paypal IPN settings

This will allow Spreedly to hear about changes such as when the funds for an eCheck actually reach your account. And then Spreedly can notify you with an offsite callback.

Optional gateway specific fields

Recurring flag

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 use it like so:


curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.xml \
  -u 'Ll6fAtoVSTyVMlJEmtpoJV8S:RKOCG5D8D3fZxDSg504D0IxU2XD4Io5VXmyzdCtTivHFTTSy' \
  -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>
          </paypal>
        </gateway_specific_fields>
      </transaction>'

<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2016-08-11T17:15:36Z</created_at>
  <updated_at type="dateTime">2016-08-11T17:15:36Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>VRgNjMe2xNkXNRrysiWFp8sbRd0</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>
    </paypal>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>67</gateway_transaction_id>
  <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>8dvNMSuDr3kTlMIQxbkIaE5KNlX</gateway_token>
  <shipping_address>
    <name>Robert Lemke</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></error_code>
    <error_detail nil="true"/>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"/>
    <created_at type="dateTime">2016-08-11T17:15:36Z</created_at>
    <updated_at type="dateTime">2016-08-11T17:15:36Z</updated_at>
  </response>
  <api_urls>
  </api_urls>
  <payment_method>
    <token>UAwoPyWJhwZiYe2ZY1ri6ENAjLG</token>
    <created_at type="dateTime">2016-08-11T17:09:30Z</created_at>
    <updated_at type="dateTime">2016-08-11T17:15:36Z</updated_at>
    <email nil="true"/>
    <data nil="true"/>
    <storage_state>retained</storage_state>
    <test type="boolean">true</test>
    <last_four_digits>1111</last_four_digits>
    <first_six_digits>411111</first_six_digits>
    <card_type>visa</card_type>
    <first_name>Robert</first_name>
    <last_name>Lemke</last_name>
    <month type="integer">4</month>
    <year type="integer">2020</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>Robert Lemke</full_name>
    <eligible_for_card_updater nil="true"/>
    <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>b0a45066121c1f1a49b3a6ffc26caf2995db</fingerprint>
  </payment_method>
</transaction>


env = Spreedly::Environment.new('Ll6fAtoVSTyMlJEm', 'RKcG5D8D3fZxDSg504U2XD4Io5VXz')
env.purchase_on_gateway("LlkjmEk0xNkcWrNixXa1fvNoTP4", "56wyNnSmuA6CWYP7w0MiYCVIbW6", 4432,
  gateway_specific_fields: {
    paypal: {
      recurring: "Y",
    }
  }
)


#<Spreedly::Purchase:0x007fdcd2851d10
 @amount="4432",
 @created_at="2016-08-11T17:15:37Z",
 @currency_code="USD",
 @description="",
 @email="",
 @gateway_specific_fields={:paypal=>{:recurring=>"Y"}},
 @gateway_token="8dvNMSuDr3kTlMIQxbkIaE5KNlX",
 @gateway_transaction_id="49",
 @ip="",
 @merchant_location_descriptor="",
 @merchant_name_descriptor="",
 @message="Succeeded!",
 @on_test_gateway="true",
 @order_id="",
 @payment_method=
  #<Spreedly::CreditCard:0x007fdcd13a88f0
   @address1="",
   @address2="",
   @card_type="visa",
   @city="",
   @company="",
   @country="",
   @created_at="2016-08-11T17:09:30Z",
   @data="",
   @eligible_for_card_updater="",
   @email="",
   @errors=[],
   @fingerprint="b0a45066121c1f1a49b3a6ffc26caf2995db",
   @first_name="Robert",
   @first_six_digits="411111",
   @full_name="Robert Lemke",
   @last_four_digits="1111",
   @last_name="Lemke",
   @month="4",
   @number="XXXX-XXXX-XXXX-1111",
   @phone_number="",
   @state="",
   @storage_state="retained",
   @token="UAwoPyWJhwZiYe2ZY1ri6ENAjLG",
   @updated_at="2016-08-11T17:15:36Z",
   @verification_value="",
   @year="2020",
   @zip="">,
 @response=
  #<Spreedly::Response:0x007fdcd1399850
   @avs_code="",
   @avs_message="",
   @cancelled="false",
   @created_at="2016-08-11T17:15:37Z",
   @cvv_code="",
   @cvv_message="",
   @error_code="",
   @error_detail="",
   @fraud_review="",
   @message="Successful purchase",
   @pending="false",
   @success="true",
   @updated_at="2016-08-11T17:15:37Z">,
 @shipping_address=
  #<Spreedly::ShippingAddress:0x007fdcd13a00d8
   @address1="",
   @address2="",
   @city="",
   @country="",
   @name="Robert Lemke",
   @phone_number="",
   @state="",
   @zip="">,
 @state="succeeded",
 @succeeded="true",
 @token="8QOPqIu4kf19fLVoAGIDv9xFu5F",
 @updated_at="2016-08-11T17:15:37Z">

This also works when using reference transactions.


curl https://core.spreedly.com/v1/transactions/7DShFlwqVtUvhyackYN2Jtw2UGn/purchase.xml \
  -u 'Ll6fAtoVSTyVMlJEmtpoJV8S:RKOCG5D8D3fZxDSg504D0IxU2XD4Io5VXmyzdCtTivHFTTSy' \
  -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">2016-08-11T17:15:37Z</created_at>
  <updated_at type="dateTime">2016-08-11T17:15:38Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>3obaPS81H7rUm93RLlO161HJKr6</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>52</gateway_transaction_id>
  <amount type="integer">80</amount>
  <currency_code>USD</currency_code>
  <message key="messages.transaction_succeeded">Succeeded!</message>
  <gateway_token>8dvNMSuDr3kTlMIQxbkIaE5KNlX</gateway_token>
  <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></error_code>
    <error_detail nil="true"/>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"/>
    <created_at type="dateTime">2016-08-11T17:15:37Z</created_at>
    <updated_at type="dateTime">2016-08-11T17:15:38Z</updated_at>
  </response>
  <api_urls>
  </api_urls>
  <reference_token>Ghyld8khRHqRJIyUFI3WGDSWJiV</reference_token>
</transaction>

Notify URL

Paypal allows you to specify an IPN listener for a specific payment using the notify_url attribute. You can specify it like so:


curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.xml \
  -u 'Ll6fAtoVSTyVMlJEmtpoJV8S:RKOCG5D8D3fZxDSg504D0IxU2XD4Io5VXmyzdCtTivHFTTSy' \
  -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>
            <notify_url>https://example.com/notify_me</notify_url>
          </paypal>
        </gateway_specific_fields>
      </transaction>'

<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2016-08-11T17:15:35Z</created_at>
  <updated_at type="dateTime">2016-08-11T17:15:35Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>Tzw4D94ZiU8oBROm5onFUEme39m</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>
      <notify_url>https://example.com/notify_me</notify_url>
    </paypal>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>66</gateway_transaction_id>
  <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>8dvNMSuDr3kTlMIQxbkIaE5KNlX</gateway_token>
  <shipping_address>
    <name>Robert Lemke</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></error_code>
    <error_detail nil="true"/>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"/>
    <created_at type="dateTime">2016-08-11T17:15:35Z</created_at>
    <updated_at type="dateTime">2016-08-11T17:15:35Z</updated_at>
  </response>
  <api_urls>
  </api_urls>
  <payment_method>
    <token>UAwoPyWJhwZiYe2ZY1ri6ENAjLG</token>
    <created_at type="dateTime">2016-08-11T17:09:30Z</created_at>
    <updated_at type="dateTime">2016-08-11T17:15:35Z</updated_at>
    <email nil="true"/>
    <data nil="true"/>
    <storage_state>retained</storage_state>
    <test type="boolean">true</test>
    <last_four_digits>1111</last_four_digits>
    <first_six_digits>411111</first_six_digits>
    <card_type>visa</card_type>
    <first_name>Robert</first_name>
    <last_name>Lemke</last_name>
    <month type="integer">4</month>
    <year type="integer">2020</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>Robert Lemke</full_name>
    <eligible_for_card_updater nil="true"/>
    <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>b0a45066121c1f1a49b3a6ffc26caf2995db</fingerprint>
  </payment_method>
</transaction>


env = Spreedly::Environment.new('Ll6fAtoVSTyMlJEm', 'RKcG5D8D3fZxDSg504U2XD4Io5VXz')
env.purchase_on_gateway("LlkjmEk0xNkcWrNixXa1fvNoTP4", "56wyNnSmuA6CWYP7w0MiYCVIbW6", 4432,
  gateway_specific_fields: {
    paypal: {
      notiify_url: "https://example.com/notify_me",
    }
  }
)


#<Spreedly::Purchase:0x007fad9585dd70
 @amount="4432",
 @created_at="2016-08-11T17:15:36Z",
 @currency_code="USD",
 @description="",
 @email="",
 @gateway_specific_fields=
  {:paypal=>{:notiify_url=>"https://example.com/notify_me"}},
 @gateway_token="8dvNMSuDr3kTlMIQxbkIaE5KNlX",
 @gateway_transaction_id="64",
 @ip="",
 @merchant_location_descriptor="",
 @merchant_name_descriptor="",
 @message="Succeeded!",
 @on_test_gateway="true",
 @order_id="",
 @payment_method=
  #<Spreedly::CreditCard:0x007fad9537c900
   @address1="",
   @address2="",
   @card_type="visa",
   @city="",
   @company="",
   @country="",
   @created_at="2016-08-11T17:09:30Z",
   @data="",
   @eligible_for_card_updater="",
   @email="",
   @errors=[],
   @fingerprint="b0a45066121c1f1a49b3a6ffc26caf2995db",
   @first_name="Robert",
   @first_six_digits="411111",
   @full_name="Robert Lemke",
   @last_four_digits="1111",
   @last_name="Lemke",
   @month="4",
   @number="XXXX-XXXX-XXXX-1111",
   @phone_number="",
   @state="",
   @storage_state="retained",
   @token="UAwoPyWJhwZiYe2ZY1ri6ENAjLG",
   @updated_at="2016-08-11T17:15:35Z",
   @verification_value="",
   @year="2020",
   @zip="">,
 @response=
  #<Spreedly::Response:0x007fad93b8d880
   @avs_code="",
   @avs_message="",
   @cancelled="false",
   @created_at="2016-08-11T17:15:36Z",
   @cvv_code="",
   @cvv_message="",
   @error_code="",
   @error_detail="",
   @fraud_review="",
   @message="Successful purchase",
   @pending="false",
   @success="true",
   @updated_at="2016-08-11T17:15:36Z">,
 @shipping_address=
  #<Spreedly::ShippingAddress:0x007fad953600e8
   @address1="",
   @address2="",
   @city="",
   @country="",
   @name="Robert Lemke",
   @phone_number="",
   @state="",
   @zip="">,
 @state="succeeded",
 @succeeded="true",
 @token="BTwjN1nZxtAoOKLbDJCZtkv8BHl",
 @updated_at="2016-08-11T17:15:36Z">

Custom

Paypal allows you to specify a custom attribute. You can specify it like so:


curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.xml \
  -u 'Ll6fAtoVSTyVMlJEmtpoJV8S:RKOCG5D8D3fZxDSg504D0IxU2XD4Io5VXmyzdCtTivHFTTSy' \
  -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>
            <custom>A custom string</custom>
          </paypal>
        </gateway_specific_fields>
      </transaction>'

<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2016-08-11T17:15:33Z</created_at>
  <updated_at type="dateTime">2016-08-11T17:15:33Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>QPdOSjP3oPSlJImZEXZsIfKIybc</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>
      <custom>A custom string</custom>
    </paypal>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>46</gateway_transaction_id>
  <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>8dvNMSuDr3kTlMIQxbkIaE5KNlX</gateway_token>
  <shipping_address>
    <name>Robert Lemke</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></error_code>
    <error_detail nil="true"/>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"/>
    <created_at type="dateTime">2016-08-11T17:15:33Z</created_at>
    <updated_at type="dateTime">2016-08-11T17:15:33Z</updated_at>
  </response>
  <api_urls>
  </api_urls>
  <payment_method>
    <token>UAwoPyWJhwZiYe2ZY1ri6ENAjLG</token>
    <created_at type="dateTime">2016-08-11T17:09:30Z</created_at>
    <updated_at type="dateTime">2016-08-11T17:15:30Z</updated_at>
    <email nil="true"/>
    <data nil="true"/>
    <storage_state>retained</storage_state>
    <test type="boolean">true</test>
    <last_four_digits>1111</last_four_digits>
    <first_six_digits>411111</first_six_digits>
    <card_type>visa</card_type>
    <first_name>Robert</first_name>
    <last_name>Lemke</last_name>
    <month type="integer">4</month>
    <year type="integer">2020</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>Robert Lemke</full_name>
    <eligible_for_card_updater nil="true"/>
    <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>b0a45066121c1f1a49b3a6ffc26caf2995db</fingerprint>
  </payment_method>
</transaction>


env = Spreedly::Environment.new('Ll6fAtoVSTyMlJEm', 'RKcG5D8D3fZxDSg504U2XD4Io5VXz')
env.purchase_on_gateway("LlkjmEk0xNkcWrNixXa1fvNoTP4", "56wyNnSmuA6CWYP7w0MiYCVIbW6", 4432,
  gateway_specific_fields: {
    paypal: {
      custom: "A custom string",
    }
  }
)


#<Spreedly::Purchase:0x007fd17a855bf8
 @amount="4432",
 @created_at="2016-08-11T17:15:34Z",
 @currency_code="USD",
 @description="",
 @email="",
 @gateway_specific_fields={:paypal=>{:custom=>"A custom string"}},
 @gateway_token="8dvNMSuDr3kTlMIQxbkIaE5KNlX",
 @gateway_transaction_id="64",
 @ip="",
 @merchant_location_descriptor="",
 @merchant_name_descriptor="",
 @message="Succeeded!",
 @on_test_gateway="true",
 @order_id="",
 @payment_method=
  #<Spreedly::CreditCard:0x007fd178b3c7b0
   @address1="",
   @address2="",
   @card_type="visa",
   @city="",
   @company="",
   @country="",
   @created_at="2016-08-11T17:09:30Z",
   @data="",
   @eligible_for_card_updater="",
   @email="",
   @errors=[],
   @fingerprint="b0a45066121c1f1a49b3a6ffc26caf2995db",
   @first_name="Robert",
   @first_six_digits="411111",
   @full_name="Robert Lemke",
   @last_four_digits="1111",
   @last_name="Lemke",
   @month="4",
   @number="XXXX-XXXX-XXXX-1111",
   @phone_number="",
   @state="",
   @storage_state="retained",
   @token="UAwoPyWJhwZiYe2ZY1ri6ENAjLG",
   @updated_at="2016-08-11T17:15:33Z",
   @verification_value="",
   @year="2020",
   @zip="">,
 @response=
  #<Spreedly::Response:0x007fd178af5720
   @avs_code="",
   @avs_message="",
   @cancelled="false",
   @created_at="2016-08-11T17:15:34Z",
   @cvv_code="",
   @cvv_message="",
   @error_code="",
   @error_detail="",
   @fraud_review="",
   @message="Successful purchase",
   @pending="false",
   @success="true",
   @updated_at="2016-08-11T17:15:34Z">,
 @shipping_address=
  #<Spreedly::ShippingAddress:0x007fd178b3ff50
   @address1="",
   @address2="",
   @city="",
   @country="",
   @name="Robert Lemke",
   @phone_number="",
   @state="",
   @zip="">,
 @state="succeeded",
 @succeeded="true",
 @token="67hnipIBZqRZtbwUuTblQxVRjuw",
 @updated_at="2016-08-11T17:15:34Z">

Soft Descriptors

Paypal allows you to specify soft_descriptor and soft_descriptor_city like so:


curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.xml \
  -u 'Ll6fAtoVSTyVMlJEmtpoJV8S:RKOCG5D8D3fZxDSg504D0IxU2XD4Io5VXmyzdCtTivHFTTSy' \
  -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>
            <soft_descriptor>Company Name</soft_descriptor>
            <soft_descriptor_city>New York</soft_descriptor_city>
          </paypal>
        </gateway_specific_fields>
      </transaction>'

<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2016-08-11T17:15:38Z</created_at>
  <updated_at type="dateTime">2016-08-11T17:15:38Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>GwkcIzCjwkWEYnyCMrGA6Tb9VF</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>
      <soft_descriptor>Company Name</soft_descriptor>
      <soft_descriptor_city>New York</soft_descriptor_city>
    </paypal>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>55</gateway_transaction_id>
  <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>8dvNMSuDr3kTlMIQxbkIaE5KNlX</gateway_token>
  <shipping_address>
    <name>Robert Lemke</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></error_code>
    <error_detail nil="true"/>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"/>
    <created_at type="dateTime">2016-08-11T17:15:38Z</created_at>
    <updated_at type="dateTime">2016-08-11T17:15:38Z</updated_at>
  </response>
  <api_urls>
  </api_urls>
  <payment_method>
    <token>UAwoPyWJhwZiYe2ZY1ri6ENAjLG</token>
    <created_at type="dateTime">2016-08-11T17:09:30Z</created_at>
    <updated_at type="dateTime">2016-08-11T17:15:37Z</updated_at>
    <email nil="true"/>
    <data nil="true"/>
    <storage_state>retained</storage_state>
    <test type="boolean">true</test>
    <last_four_digits>1111</last_four_digits>
    <first_six_digits>411111</first_six_digits>
    <card_type>visa</card_type>
    <first_name>Robert</first_name>
    <last_name>Lemke</last_name>
    <month type="integer">4</month>
    <year type="integer">2020</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>Robert Lemke</full_name>
    <eligible_for_card_updater nil="true"/>
    <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>b0a45066121c1f1a49b3a6ffc26caf2995db</fingerprint>
  </payment_method>
</transaction>


env = Spreedly::Environment.new('Ll6fAtoVSTyMlJEm', 'RKcG5D8D3fZxDSg504U2XD4Io5VXz')
env.purchase_on_gateway("LlkjmEk0xNkcWrNixXa1fvNoTP4", "56wyNnSmuA6CWYP7w0MiYCVIbW6", 4432,
  gateway_specific_fields: {
    paypal: {
      soft_descriptor: "Company Name",
      soft_descriptor_city: "New York"
    }
  }
)


#<Spreedly::Purchase:0x007f89b4321bb8
 @amount="4432",
 @created_at="2016-08-11T17:15:39Z",
 @currency_code="USD",
 @description="",
 @email="",
 @gateway_specific_fields=
  {:paypal=>
    {:soft_descriptor=>"Company Name", :soft_descriptor_city=>"New York"}},
 @gateway_token="8dvNMSuDr3kTlMIQxbkIaE5KNlX",
 @gateway_transaction_id="60",
 @ip="",
 @merchant_location_descriptor="",
 @merchant_name_descriptor="",
 @message="Succeeded!",
 @on_test_gateway="true",
 @order_id="",
 @payment_method=
  #<Spreedly::CreditCard:0x007f89b435c718
   @address1="",
   @address2="",
   @card_type="visa",
   @city="",
   @company="",
   @country="",
   @created_at="2016-08-11T17:09:30Z",
   @data="",
   @eligible_for_card_updater="",
   @email="",
   @errors=[],
   @fingerprint="b0a45066121c1f1a49b3a6ffc26caf2995db",
   @first_name="Robert",
   @first_six_digits="411111",
   @full_name="Robert Lemke",
   @last_four_digits="1111",
   @last_name="Lemke",
   @month="4",
   @number="XXXX-XXXX-XXXX-1111",
   @phone_number="",
   @state="",
   @storage_state="retained",
   @token="UAwoPyWJhwZiYe2ZY1ri6ENAjLG",
   @updated_at="2016-08-11T17:15:38Z",
   @verification_value="",
   @year="2020",
   @zip="">,
 @response=
  #<Spreedly::Response:0x007f89b43316f8
   @avs_code="",
   @avs_message="",
   @cancelled="false",
   @created_at="2016-08-11T17:15:39Z",
   @cvv_code="",
   @cvv_message="",
   @error_code="",
   @error_detail="",
   @fraud_review="",
   @message="Successful purchase",
   @pending="false",
   @success="true",
   @updated_at="2016-08-11T17:15:39Z">,
 @shipping_address=
  #<Spreedly::ShippingAddress:0x007f89b435ff30
   @address1="",
   @address2="",
   @city="",
   @country="",
   @name="Robert Lemke",
   @phone_number="",
   @state="",
   @zip="">,
 @state="succeeded",
 @succeeded="true",
 @token="Wa0JyUgcmbPQLOG3J3ILgDxRUnS",
 @updated_at="2016-08-11T17:15:39Z">

No Shipping

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


curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.xml \
  -u 'Ll6fAtoVSTyVMlJEmtpoJV8S:RKOCG5D8D3fZxDSg504D0IxU2XD4Io5VXmyzdCtTivHFTTSy' \
  -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>
            <no_shipping>true</no_shipping>
          </paypal>
        </gateway_specific_fields>
      </transaction>'

<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2016-08-11T17:15:34Z</created_at>
  <updated_at type="dateTime">2016-08-11T17:15:34Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>FrHsXpnm7AxWkTiF0715seDvD66</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>
      <no_shipping>true</no_shipping>
    </paypal>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>60</gateway_transaction_id>
  <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>8dvNMSuDr3kTlMIQxbkIaE5KNlX</gateway_token>
  <shipping_address>
    <name>Robert Lemke</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></error_code>
    <error_detail nil="true"/>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"/>
    <created_at type="dateTime">2016-08-11T17:15:34Z</created_at>
    <updated_at type="dateTime">2016-08-11T17:15:34Z</updated_at>
  </response>
  <api_urls>
  </api_urls>
  <payment_method>
    <token>UAwoPyWJhwZiYe2ZY1ri6ENAjLG</token>
    <created_at type="dateTime">2016-08-11T17:09:30Z</created_at>
    <updated_at type="dateTime">2016-08-11T17:15:34Z</updated_at>
    <email nil="true"/>
    <data nil="true"/>
    <storage_state>retained</storage_state>
    <test type="boolean">true</test>
    <last_four_digits>1111</last_four_digits>
    <first_six_digits>411111</first_six_digits>
    <card_type>visa</card_type>
    <first_name>Robert</first_name>
    <last_name>Lemke</last_name>
    <month type="integer">4</month>
    <year type="integer">2020</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>Robert Lemke</full_name>
    <eligible_for_card_updater nil="true"/>
    <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>b0a45066121c1f1a49b3a6ffc26caf2995db</fingerprint>
  </payment_method>
</transaction>


env = Spreedly::Environment.new('Ll6fAtoVSTyMlJEm', 'RKcG5D8D3fZxDSg504U2XD4Io5VXz')
env.purchase_on_gateway("LlkjmEk0xNkcWrNixXa1fvNoTP4", "56wyNnSmuA6CWYP7w0MiYCVIbW6", 4432,
  gateway_specific_fields: {
    paypal: {
      no_shipping: "true"
    }
  }
)


#<Spreedly::Purchase:0x007fabde0f5d98
 @amount="4432",
 @created_at="2016-08-11T17:15:35Z",
 @currency_code="USD",
 @description="",
 @email="",
 @gateway_specific_fields={:paypal=>{:no_shipping=>"true"}},
 @gateway_token="8dvNMSuDr3kTlMIQxbkIaE5KNlX",
 @gateway_transaction_id="56",
 @ip="",
 @merchant_location_descriptor="",
 @merchant_name_descriptor="",
 @message="Succeeded!",
 @on_test_gateway="true",
 @order_id="",
 @payment_method=
  #<Spreedly::CreditCard:0x007fabddab0960
   @address1="",
   @address2="",
   @card_type="visa",
   @city="",
   @company="",
   @country="",
   @created_at="2016-08-11T17:09:30Z",
   @data="",
   @eligible_for_card_updater="",
   @email="",
   @errors=[],
   @fingerprint="b0a45066121c1f1a49b3a6ffc26caf2995db",
   @first_name="Robert",
   @first_six_digits="411111",
   @full_name="Robert Lemke",
   @last_four_digits="1111",
   @last_name="Lemke",
   @month="4",
   @number="XXXX-XXXX-XXXX-1111",
   @phone_number="",
   @state="",
   @storage_state="retained",
   @token="UAwoPyWJhwZiYe2ZY1ri6ENAjLG",
   @updated_at="2016-08-11T17:15:34Z",
   @verification_value="",
   @year="2020",
   @zip="">,
 @response=
  #<Spreedly::Response:0x007fabdda718f0
   @avs_code="",
   @avs_message="",
   @cancelled="false",
   @created_at="2016-08-11T17:15:35Z",
   @cvv_code="",
   @cvv_message="",
   @error_code="",
   @error_detail="",
   @fraud_review="",
   @message="Successful purchase",
   @pending="false",
   @success="true",
   @updated_at="2016-08-11T17:15:35Z">,
 @shipping_address=
  #<Spreedly::ShippingAddress:0x007fabdda90160
   @address1="",
   @address2="",
   @city="",
   @country="",
   @name="Robert Lemke",
   @phone_number="",
   @state="",
   @zip="">,
 @state="succeeded",
 @succeeded="true",
 @token="Xjtu1KtPVhmXxOukh47CfUppDGv",
 @updated_at="2016-08-11T17:15:35Z">

Payment Details Item Type

PayPal offers PaymentDetailsItemType fields to specify the line items with a transaction. For offsite transactions, this should show the line items on the PayPal Express hosted payment page. You can set those fields using the gateway specific fields below.


curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.xml \
  -u 'Ll6fAtoVSTyVMlJEmtpoJV8S:RKOCG5D8D3fZxDSg504D0IxU2XD4Io5VXmyzdCtTivHFTTSy' \
  -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>
            <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">2017-06-16T15:14:40Z</created_at>
  <updated_at type="dateTime">2017-06-16T15:14:40Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>2vlK4zwJ7lrq1elc83wEfBSo6vo</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>
      <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>65</gateway_transaction_id>
  <gateway_latency_ms type="integer">0</gateway_latency_ms>
  <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>1iVJHuBNyZKcMDPcV5hTsCUwx3R</gateway_token>
  <shipping_address>
    <name>Cierra Blanda</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></error_code>
    <error_detail nil="true"/>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"/>
    <created_at type="dateTime">2017-06-16T15:14:40Z</created_at>
    <updated_at type="dateTime">2017-06-16T15:14:40Z</updated_at>
  </response>
  <api_urls>
  </api_urls>
  <payment_method>
    <token>NeH7lJndA7DdFlb6FAoN7AoIv6R</token>
    <created_at type="dateTime">2017-06-16T15:10:47Z</created_at>
    <updated_at type="dateTime">2017-06-16T15:14:39Z</updated_at>
    <email nil="true"/>
    <data nil="true"/>
    <storage_state>retained</storage_state>
    <test type="boolean">true</test>
    <last_four_digits>1111</last_four_digits>
    <first_six_digits>411111</first_six_digits>
    <card_type>visa</card_type>
    <first_name>Cierra</first_name>
    <last_name>Blanda</last_name>
    <month type="integer">4</month>
    <year type="integer">2020</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>Cierra Blanda</full_name>
    <eligible_for_card_updater nil="true"/>
    <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 nil="true"/>
  </payment_method>
</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 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>