The Create PayPal Transaction request performs a transaction (purchase) using the PayPal payment method.
Getting started with PayPal in BlueSnap
Go to the PayPal Guide for a walkthrough of implementing the PayPal payment method via the API. To use PayPal, you will need to first connect your PayPal and BlueSnap account, as described in the guide.
Request Content
alt-transaction
container required, contains the following properties (see alt-transaction):
merchant-transaction-id
string optional
soft-descriptor
string optional
amount
decimal required
currency
string required
tax-reference
string optional
payer-info
container optional (see payer-info)
vaulted-shopper-id
integer optional
paypal-transaction
container required (see paypal-transaction)
transaction-description
string optional
transaction-meta-data
container optional (see transaction-meta-data)
Response Details
If successful, the response HTTP status code is 200 OK.
The response contains an alt-transaction
resource (see alt-transaction) with the request properties plus these additions:
vaulted-shopper-id
paypal-transaction
is returned with the paypal-url
and order-id
(see paypal-transaction)
processing-info
fraud-result-info
Examples
Request Examples
curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<?xml version="1.0" encoding="UTF-8"?>
<alt-transaction xmlns="http://ws.plimus.com">
<soft-descriptor>ABC COMPANY</soft-descriptor>
<amount>100.00</amount>
<currency>USD</currency>
<paypal-transaction>
<return-url>http://www.returnURL.com</return-url>
<cancel-url>http://www.cancelURL.com</cancel-url>
</paypal-transaction>
</alt-transaction>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<?xml version="1.0" encoding="UTF-8"?>
<alt-transaction xmlns="http://ws.plimus.com">
<soft-descriptor>ABC COMPANY</soft-descriptor>
<amount>100.00</amount>
<currency>USD</currency>
<payer-info>
<first-name>John</first-name>
<last-name>Doe</last-name>
</payer-info>
<paypal-transaction>
<return-url>http://www.returnURL.com</return-url>
<cancel-url>http://www.cancelURL.com</cancel-url>
</paypal-transaction>
</alt-transaction>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<?xml version="1.0" encoding="UTF-8"?>
<alt-transaction xmlns="http://ws.plimus.com">
<soft-descriptor>ABC COMPANY</soft-descriptor>
<amount>100.00</amount>
<currency>USD</currency>
<vaulted-shopper-id>20781033</vaulted-shopper-id>
<paypal-transaction>
<return-url>http://www.returnURL.com</return-url>
<cancel-url>http://www.cancelURL.com</cancel-url>
</paypal-transaction>
</alt-transaction>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<?xml version="1.0" encoding="UTF-8"?>
<alt-transaction xmlns="http://ws.plimus.com">
<merchant-transaction-id>3</merchant-transaction-id>
<soft-descriptor>ABC COMPANY</soft-descriptor>
<amount>100.00</amount>
<currency>USD</currency>
<payer-info>
<first-name>John</first-name>
<last-name>Doe</last-name>
</payer-info>
<paypal-transaction>
<return-url>http://www.returnURL.com</return-url>
<cancel-url>http://www.cancelURL.com</cancel-url>
</paypal-transaction>
<transaction-meta-data>
<meta-data>
<meta-key>stateTaxAmount</meta-key>
<meta-value>20.00</meta-value>
<meta-description>State Tax Amount</meta-description>
</meta-data>
<meta-data>
<meta-key>cityTaxAmount</meta-key>
<meta-value>20.00</meta-value>
<meta-description>City Tax Amount</meta-description>
</meta-data>
<meta-data>
<meta-key>shippingAmount</meta-key>
<meta-value>10.00</meta-value>
<meta-description>Shipping Amount</meta-description>
</meta-data>
</transaction-meta-data>
</alt-transaction>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<?xml version="1.0" encoding="UTF-8"?>
<alt-transaction xmlns="http://ws.plimus.com">
<soft-descriptor>ABC COMPANY</soft-descriptor>
<amount>100.00</amount>
<currency>USD</currency>
<payer-info>
<first-name>John</first-name>
<last-name>Doe</last-name>
</payer-info>
<paypal-transaction>
<return-url>http://www.returnURL.com</return-url>
<cancel-url>http://www.cancelURL.com</cancel-url>
</paypal-transaction>
<transaction-description>Product description</transaction-description>
</alt-transaction>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<?xml version="1.0" encoding="UTF-8"?>
<alt-transaction xmlns="http://ws.plimus.com">
<soft-descriptor>ABC COMPANY</soft-descriptor>
<amount>100.00</amount>
<currency>USD</currency>
<paypal-transaction>
<return-url>http://www.returnURL.com</return-url>
<cancel-url>http://www.cancelURL.com</cancel-url>
<in-context>true</in-context>
</paypal-transaction>
</alt-transaction>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<?xml version="1.0" encoding="UTF-8"?>
<alt-transaction xmlns="http://ws.plimus.com">
<merchant-transaction-id>A3bn43</merchant-transaction-id>
<soft-descriptor>ABC COMPANY</soft-descriptor>
<amount>100.00</amount>
<currency>USD</currency>
<paypal-transaction>
<return-url>http://www.returnURL.com</return-url>
<cancel-url>http://www.cancelURL.com</cancel-url>
<recurring>1</recurring>
</paypal-transaction>
</alt-transaction>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<?xml version="1.0" encoding="UTF-8"?>
<alt-transaction xmlns="http://ws.plimus.com">
<amount>100.00</amount>
<currency>USD</currency>
<paypal-transaction>
<paypal-subscription-id>1234567</paypal-subscription-id>
</paypal-transaction>
</alt-transaction>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<alt-transaction xmlns="http://ws.plimus.com">
<merchant-transaction-id>testtransaction1</merchant-transaction-id>
<soft-descriptor>ABC COMPANY</soft-descriptor>
<amount>100.00</amount>
<currency>USD</currency>
<payer-info>
<first-name>John</first-name>
<last-name>Doe</last-name>
</payer-info>
<paypal-transaction>
<transaction-type>AUTH_ONLY</transaction-type>
<return-url>http://www.returnURL.com</return-url>
<cancel-url>http://www.cancelURL.com</cancel-url>
<max-amount>120.00</max-amount>
</paypal-transaction>
</alt-transaction>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<alt-transaction xmlns="http://ws.plimus.com">
<merchant-transaction-id>testtransaction1</merchant-transaction-id>
<soft-descriptor>ABC COMPANY</soft-descriptor>
<amount>100.00</amount>
<currency>USD</currency>
<payer-info>
<first-name>John</first-name>
<last-name>Doe</last-name>
</payer-info>
<paypal-transaction>
<transaction-type>SET_ORDER</transaction-type>
<return-url>http://www.returnURL.com</return-url>
<cancel-url>http://www.cancelURL.com</cancel-url>
<max-amount>120.00</max-amount>
</paypal-transaction>
</alt-transaction>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<?xml version="1.0" encoding="UTF-8"?>
<alt-transaction xmlns="http://ws.plimus.com">
<soft-descriptor>ABC COMPANY</soft-descriptor>
<amount>120.50</amount>
<currency>USD</currency>
<tax-reference>048deff0-a285-47e1-bc39-42f79bf0095b</tax-reference>
<payer-info>
<first-name>John</first-name>
<last-name>Doe</last-name>
</payer-info>
<paypal-transaction>
<return-url>http://www.returnURL.com</return-url>
<cancel-url>http://www.cancelURL.com</cancel-url>
</paypal-transaction>
</alt-transaction>'
Response Examples
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<alt-transaction xmlns="http://ws.plimus.com">
<soft-descriptor>ABC COMPANY</soft-descriptor>
<amount>100.00</amount>
<currency>USD</currency>
<vaulted-shopper-id>1234</vaulted-shopper-id>
<paypal-transaction>
<paypal-url>https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout&token=EC-3SH38585JS3540821</paypal-url>
<order-id>3979635</order-id>
</paypal-transaction>
<processing-info>
<processing-status>PENDING</processing-status>
</processing-info>
</alt-transaction>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<alt-transaction xmlns="http://ws.plimus.com">
<soft-descriptor>ABC COMPANY</soft-descriptor>
<amount>100.00</amount>
<currency>USD</currency>
<vaulted-shopper-id>1234</vaulted-shopper-id>
<payer-info>
<first-name>John</first-name>
<last-name>Doe</last-name>
</payer-info>
<paypal-transaction>
<paypal-url>https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout&token=EC-0SM33181BF217002W</paypal-url>
<order-id>3979589</order-id>
</paypal-transaction>
<processing-info>
<processing-status>PENDING</processing-status>
</processing-info>
</alt-transaction>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<alt-transaction xmlns="http://ws.plimus.com">
<soft-descriptor>ABC COMPANY</soft-descriptor>
<amount>100.00</amount>
<currency>USD</currency>
<vaulted-shopper-id>20781033</vaulted-shopper-id>
<paypal-transaction>
<paypal-url>https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout&token=EC-9GY47037JY601890L</paypal-url>
<order-id>3979591</order-id>
</paypal-transaction>
<processing-info>
<processing-status>PENDING</processing-status>
</processing-info>
</alt-transaction>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<alt-transaction xmlns="http://ws.plimus.com">
<merchant-transaction-id>3</merchant-transaction-id>
<soft-descriptor>ABC COMPANY</soft-descriptor>
<amount>100.00</amount>
<currency>USD</currency>
<vaulted-shopper-id>1234</vaulted-shopper-id>
<payer-info>
<first-name>John</first-name>
<last-name>Doe</last-name>
</payer-info>
<paypal-transaction>
<paypal-url>https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout&token=EC-7GY45732D90677524</paypal-url>
<order-id>3979657</order-id>
</paypal-transaction>
<transaction-meta-data>
<meta-data>
<meta-key>stateTaxAmount</meta-key>
<meta-value>20.00</meta-value>
<meta-description>State Tax Amount</meta-description>
</meta-data>
<meta-data>
<meta-key>cityTaxAmount</meta-key>
<meta-value>20.00</meta-value>
<meta-description>City Tax Amount</meta-description>
</meta-data>
<meta-data>
<meta-key>shippingAmount</meta-key>
<meta-value>10.00</meta-value>
<meta-description>Shipping Amount</meta-description>
</meta-data>
</transaction-meta-data>
<processing-info>
<processing-status>PENDING</processing-status>
</processing-info>
</alt-transaction>
<?xml version="1.0" encoding="UTF-8"?>
<alt-transaction xmlns="http://ws.plimus.com">
<soft-descriptor>ABC COMPANY</soft-descriptor>
<amount>100.00</amount>
<currency>USD</currency>
<vaulted-shopper-id>1234</vaulted-shopper-id>
<payer-info>
<first-name>John</first-name>
<last-name>Doe</last-name>
</payer-info>
<paypal-transaction>
<paypal-url>https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout&token=EC-0SM33181BF217002W</paypal-url>
<order-id>3979589</order-id>
</paypal-transaction>
<processing-info>
<processing-status>PENDING</processing-status>
</processing-info>
</alt-transaction>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<alt-transaction xmlns="http://ws.plimus.com">
<soft-descriptor>ABC COMPANY</soft-descriptor>
<amount>100.00</amount>
<currency>USD</currency>
<vaulted-shopper-id>1234</vaulted-shopper-id>
<paypal-transaction>
<paypal-url>https://www.sandbox.paypal.com/checkoutnow?token=EC-4UU43831F40425709</paypal-url>
<order-id>3979635</order-id>
<in-context>true</in-context>
</paypal-transaction>
<processing-info>
<processing-status>PENDING</processing-status>
</processing-info>
</alt-transaction>
<?xml version="1.0" encoding="UTF-8"?>
<alt-transaction xmlns="http://ws.plimus.com">
<soft-descriptor>ABC COMPANY</soft-descriptor>
<amount>100.00</amount>
<currency>USD</currency>
<vaulted-shopper-id>1234</vaulted-shopper-id>
<paypal-transaction>
<paypal-url>https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout</paypal-url>
<order-id>980111</order-id>
</paypal-transaction>
<processing-info>
<processing-status>PENDING</processing-status>
</processing-info>
</alt-transaction>
<?xml version="1.0" encoding="UTF-8"?>
<alt-transaction xmlns="http://ws.plimus.com">
<transaction-id>38500786</transaction-id>
<amount>100.00</amount>
<currency>USD</currency>
<transaction-approval-date>10/01/2020</transaction-approval-date>
<transaction-approval-time>10:19:21</transaction-approval-time>
<vaulted-shopper-id>1234</vaulted-shopper-id>
<paypal-transaction>
<paypal-subscription-id>1234567</paypal-subscription-id>
</paypal-transaction>
<processing-info>
<processing-status>SUCCESS</processing-status>
</processing-info>
</alt-transaction>
<?xml version="1.0" encoding="UTF-8"?>
<alt-transaction xmlns="http://ws.plimus.com">
<merchant-transaction-id>A3bn43</merchant-transaction-id>
<soft-descriptor>ABC COMPANY</soft-descriptor>
<amount>100.00</amount>
<currency>USD</currency>
<payer-info>
<first-name>John</first-name>
<last-name>Doe</last-name>
</payer-info>
<vaulted-shopper-id>19587618</vaulted-shopper-id>
<paypal-transaction>
<paypal-url>https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout&token=EC-2FK36938XP960042T</paypal-url>
<order-id>4006145</order-id>
</paypal-transaction>
<processing-info>
<processing-status>PENDING</processing-status>
</processing-info>
</alt-transaction>
<?xml version="1.0" encoding="UTF-8"?>
<alt-transaction xmlns="http://ws.plimus.com">
<merchant-transaction-id>A3bn43</merchant-transaction-id>
<soft-descriptor>ABC COMPANY</soft-descriptor>
<amount>100.00</amount>
<currency>USD</currency>
<payer-info>
<first-name>John</first-name>
<last-name>Doe</last-name>
</payer-info>
<vaulted-shopper-id>19587618</vaulted-shopper-id>
<paypal-transaction>
<paypal-url>https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout&token=EC-2FK36938XP960042T</paypal-url>
<order-id>4006145</order-id>
</paypal-transaction>
<processing-info>
<processing-status>PENDING</processing-status>
</processing-info>
</alt-transaction>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<alt-transaction xmlns="http://ws.plimus.com">
<soft-descriptor>ABC COMPANY</soft-descriptor>
<amount>100.00</amount>
<currency>USD</currency>
<tax-reference>048deff0-a285-47e1-bc39-42f79bf0095b</tax-reference>
<vaulted-shopper-id>1234</vaulted-shopper-id>
<payer-info>
<first-name>John</first-name>
<last-name>Doe</last-name>
</payer-info>
<paypal-transaction>
<paypal-url>https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout&token=EC-0SM33181BF217002W</paypal-url>
<order-id>3979589</order-id>
</paypal-transaction>
<processing-info>
<processing-status>PENDING</processing-status>
</processing-info>
</alt-transaction>
Example Descriptions
For details about the above examples, see:
- Basic Create PayPal Transaction
- Create PayPal Transaction with payer info
- Create PayPal Transaction with vaulted shopper
- Create PayPal Transaction with Merchant Transaction ID and metadata
- Create PayPal Transaction with transaction description
- Create PayPal Transaction with In-Context checkout
- Create PayPal Transaction for initial subscription payment
- Create PayPal Transaction for recurring subscription payment
Basic Create PayPal Transaction
This example shows a basic Create PayPal Transaction request, containing the minimum required fields to process a single PayPal transaction. The request does not include any information about the shopper, so this may be a new shopper or a guest checkout.
Create PayPal Transaction with payer info
To perform a Create PayPal Transaction and send information about the shopper, you'll need to include the payer-info
property within the alt-transaction resource in your request. In this property, you can send information such as the shopper's first and last name, email, phone number, and address. See payer-info.
Above is an example of a Create PayPal Transaction request with the shopper's first and last name sent in the payer-info
property.
Create PayPal Transaction with vaulted shopper
To perform a Create PayPal Transaction with an existing vaulted shopper, you'll need to include the vaulted-shopper-id
property within the alt-transaction resource in your request.
Important: If you set the 'no-shipping' property (in the paypal-transaction resource) to 0 or 2, then the shopper's shipping address will be retrieved from PayPal, and the vaulted shopper will be automatically updated with that shipping address.
Above is an example of a Create PayPal Transaction request with an existing vaulted shopper with the ID 20781033.
Create PayPal Transaction with Merchant Transaction ID and metadata
You may wish to assign your own ID to each transaction, for example in order to track the transactions in your own internal systems. To do this, you will need to include the merchant-transaction-id
property within the alt-transaction resource in your request.
You can also send metadata for the transaction, such as a description of the item, or tax or shipping information. To do this, you will need to include the transaction-meta-data
property (a container for meta-data
key-value pairs) within the alt-transaction resource in your request.
Above is an example of a request that includes a Merchant Transaction ID (MTI), as well as metadata for the transaction, including state tax, city tax, and the shipping amount.
Create PayPal Transaction with transaction description
By default, the PayPal page will show the statement descriptor as the description of the product being purchased. If you prefer to show a different description, you can send it in the transaction-description
element.
Above is an example of a Create PayPal Transaction request with the transaction-description
.
Create PayPal Transaction with In-Context checkout
If you would like to enable In-Context PayPal checkout, set the in-context
property in the paypal-transaction resource to true.
Above is an example of a request with In-Context checkout enabled.
Create PayPal Transaction for initial subscription payment
If you are managing subscriptions yourself (or through a third party), you can use the PayPal payment method for subscription payments. In the initial subscription payment, include the recurring
property in the paypal-transaction resource, and set the value to 1.
Above is an example of an initial subscription payment with PayPal.
For more information, see the guide to processing merchant-managed PayPal subscriptions.
Create PayPal Transaction for recurring subscription payment
After you have processed an initial subscription payment using PayPal, you can then associate the recurring payments with the relevant subscription by including the paypal-subscription-id
in the paypal-transaction resource.
How to get the subscription ID
You can obtain the subscription ID in two ways:
- In the
subscriptionId
field in the Charge IPN that is sent once the initial payment is processed.
or- By sending a Retrieve PayPal Transaction request once the payment has been processed.
Above is an example of a recurring subscription payment with PayPal.
For more information, see the guide to processing merchant-managed PayPal subscriptions.
Back to Top
API Explorer
To test out a call, enter the XML portion of the request below and then click Try it!
Tip: Copy the XML portion from one of the example requests above, or use the XML code below as a starting point. You can enter different parameters and values to see how your test scenario would work. The request headers, including authorization, are already built in for you in this test area, so you should not include them here.
<alt-transaction xmlns="http://ws.plimus.com">
<soft-descriptor>ABC COMPANY</soft-descriptor>
<amount>100.00</amount>
<currency>USD</currency>
<paypal-transaction>
<return-url>http://www.returnURL.com</return-url>
<cancel-url>http://www.cancelURL.com</cancel-url>
</paypal-transaction>
</alt-transaction>