Create PayPal Transaction

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.

Try it in the API Explorer

Request Content

Send an altTransaction object, with the following:

      amount     decimal    required
     payerInfo     object    optional (see payerInfo)
     vaultedShopperId     integer    optional
     merchantTransactionId     string    optional
     softDescriptor     string    optional
     transactionDescription     string    optional
     currency     string    required
     taxReference     string    optional
     transactionMetaData     object    optional (see transactionMetaData)
     paypalTransaction     object    required (see paypalTransaction)

Response Details

If successful, the response HTTP status code is 200 OK.
The response contains the request properties plus these additions:

      vaultedShopperId
     paypalTransaction is returned with the paypalUrl and orderId (see paypalTransaction)
     processingInfo
     fraudResultInfo

Examples

Request Examples

curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "amount": 100,
    "softDescriptor": "ABC COMPANY",
    "currency": "USD",
    "paypalTransaction": {
        "cancelUrl": "http://www.cancelURL.com",
        "returnUrl": "http://www.returnURL.com"
    }
}

curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "amount": 100,
    "payerInfo": {
        "firstName": "John",
        "lastName": "Doe"
    },
    "softDescriptor": "ABC COMPANY",
    "currency": "USD",
    "paypalTransaction": {
        "cancelUrl": "http://www.cancelURL.com",
        "returnUrl": "http://www.returnURL.com"
    }
}

curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "amount": 100,
    "vaultedShopperId": 20781033,
    "softDescriptor": "ABC COMPANY",
    "currency": "USD",
    "paypalTransaction": {
        "cancelUrl": "http://www.cancelURL.com",
        "returnUrl": "http://www.returnURL.com"
    }
}

curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "amount": 100,
    "payerInfo": {
        "firstName": "John",
        "lastName": "Doe"
    },
    "merchantTransactionId": 3,
    "softDescriptor": "ABC COMPANY",
    "currency": "USD",
    "transactionMetaData": {"metaData": [
        {
            "metaValue": 20,
            "metaKey": "stateTaxAmount",
            "metaDescription": "State Tax Amount"
        },
        {
            "metaValue": 20,
            "metaKey": "cityTaxAmount",
            "metaDescription": "City Tax Amount"
        },
        {
            "metaValue": 10,
            "metaKey": "shippingAmount",
            "metaDescription": "Shipping Amount"
        }
    ]},
    "paypalTransaction": {
        "cancelUrl": "http://www.cancelURL.com",
        "returnUrl": "http://www.returnURL.com"
    }
}

curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "amount": 100,
    "payerInfo": {
        "firstName": "John",
        "lastName": "Doe"
    },
    "softDescriptor": "ABC COMPANY",
    "transactionDescription": "Product description",
    "currency": "USD",
    "paypalTransaction": {
        "cancelUrl": "http://www.cancelURL.com",
        "returnUrl": "http://www.returnURL.com"
    }
}

curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "amount": 100,
    "softDescriptor": "ABC COMPANY",
    "currency": "USD",
    "paypalTransaction": {
        "cancelUrl": "http://www.cancelURL.com",
        "inContext": true,
        "returnUrl": "http://www.returnURL.com"
    }
}

curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "amount": 100,
    "merchantTransactionId": "A3bn43",
    "softDescriptor": "ABC COMPANY",
    "currency": "USD",
    "paypalTransaction": {
        "cancelUrl": "http://www.cancelURL.com",
        "recurring": 1,
        "returnUrl": "http://www.returnURL.com"
    }
}

curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "amount": 100,
    "currency": "USD",
    "paypalTransaction": {"paypalSubscriptionId": 1234567}
}

curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "merchantTransactionId": "testtransaction1",
    "softDescriptor": "ABC COMPANY",
    "amount": "100.00",
    "currency": "USD",
    "payerInfo": {
      "firstName": "John",
      "lastName": "Doe"
    },
    "paypalTransaction": {
      "transactionType": "AUTH_ONLY",
      "returnUrl": "http://www.returnURL.com",
      "cancelUrl": "http://www.cancelURL.com",
      "maxAmount": "120.00"
    }
}

curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "merchantTransactionId": "testtransaction1",
    "softDescriptor": "ABC COMPANY",
    "amount": "100.00",
    "currency": "USD",
    "payerInfo": {
      "firstName": "John",
      "lastName": "Doe"
    },
    "paypalTransaction": {
      "transactionType": "SET_ORDER",
      "returnUrl": "http://www.returnURL.com",
      "cancelUrl": "http://www.cancelURL.com",
      "maxAmount": "120.00"
    }
}

curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "amount": 120.50,
    "payerInfo": {
        "firstName": "John",
        "lastName": "Doe"
    },
    "softDescriptor": "ABC COMPANY",
    "currency": "USD",
    "taxReference": "048deff0-a285-47e1-bc39-42f79bf0095b",
    "paypalTransaction": {
        "cancelUrl": "http://www.cancelURL.com",
        "returnUrl": "http://www.returnURL.com"
    }
}

Response Examples

{
    "amount": 100,
    "vaultedShopperId": 1234,
    "processingInfo": {"processingStatus": "PENDING"},
    "softDescriptor": "ABC COMPANY",
    "currency": "USD",
    "paypalTransaction": {
        "paypalUrl": "https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout&token=EC-3SH38585JS3540821",
        "orderId": 3979635
    }
}

{
    "amount": 100,
    "vaultedShopperId": 1234,
    "payerInfo": {
        "firstName": "John",
        "lastName": "Doe"
    },
    "processingInfo": {"processingStatus": "PENDING"},
    "softDescriptor": "ABC COMPANY",
    "currency": "USD",
    "paypalTransaction": {
        "paypalUrl": "https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout&token=EC-0SM33181BF217002W",
        "orderId": 3979589
    }
}

{
    "amount": 100,
    "vaultedShopperId": 20781033,
    "processingInfo": {"processingStatus": "PENDING"},
    "softDescriptor": "ABC COMPANY",
    "currency": "USD",
    "paypalTransaction": {
        "paypalUrl": "https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout&token=EC-9GY47037JY601890L",
        "orderId": 3979591
    }
}

{
    "amount": 100,
    "vaultedShopperId": 1234,
    "payerInfo": {
        "firstName": "John",
        "lastName": "Doe"
    },
    "merchantTransactionId": 3,
    "processingInfo": {"processingStatus": "PENDING"},
    "softDescriptor": "ABC COMPANY",
    "currency": "USD",
    "transactionMetaData": {"metaData": [
        {
            "metaValue": 20,
            "metaKey": "stateTaxAmount",
            "metaDescription": "State Tax Amount"
        },
        {
            "metaValue": 20,
            "metaKey": "cityTaxAmount",
            "metaDescription": "City Tax Amount"
        },
        {
            "metaValue": 10,
            "metaKey": "shippingAmount",
            "metaDescription": "Shipping Amount"
        }
    ]},
    "paypalTransaction": {
        "paypalUrl": "https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout&token=EC-7GY45732D90677524",
        "orderId": 3979657
    }
}

{
    "amount": 100,
    "vaultedShopperId": 1234,
    "payerInfo": {
        "firstName": "John",
        "lastName": "Doe"
    },
    "processingInfo": {"processingStatus": "PENDING"},
    "softDescriptor": "ABC COMPANY",
    "currency": "USD",
    "paypalTransaction": {
        "paypalUrl": "https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout&token=EC-0SM33181BF217002W",
        "orderId": 3979589
    }
}

{
    "amount": 100,
    "vaultedShopperId": 1234,
    "processingInfo": {"processingStatus": "PENDING"},
    "softDescriptor": "ABC COMPANY",
    "currency": "USD",
    "paypalTransaction": {
        "paypalUrl": "https://www.sandbox.paypal.com/checkoutnow?token=EC-4UU43831F40425709",
        "orderId": 3979635,
        "inContext": true
    }
}

{
    "amount": 100,
    "vaultedShopperId": 1234,
    "processingInfo": {"processingStatus": "PENDING"},
    "softDescriptor": "ABC COMPANY",
    "currency": "USD",
    "paypalTransaction": {
        "paypalUrl": "https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout",
        "orderId": 980111
    }
}

{
    "amount": 100,
    "vaultedShopperId": 1234,
    "processingInfo": { "processingStatus": "SUCCESS" },
    "currency": "USD",
    "transactionApprovalDate": "09/29/2020",
    "transactionApprovalTime": "13:08:47",
    "transactionId": 38500786,
    "paypalTransaction": { "paypalSubscriptionId": 1234567 }
}

{
  "alt-transaction": {
    "-xmlns": "http://ws.plimus.com",
    "merchantTransactionId": "A3bn43",
    "softDescriptor": "ABC COMPANY",
    "amount": "100.00",
    "currency": "USD",
    "payerInfo": {
      "firstName": "John",
      "lastName": "Doe"
    },
    "vaultedShopperId": "19587618",
    "paypalTransaction": {
      "paypalUrl": "https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout&token=EC-2FK36938XP960042T",
      "orderId": "4006145"
    },
    "processingInfo": { "processingStatus": "PENDING" }
  }
}

{
  "alt-transaction": {
    "-xmlns": "http://ws.plimus.com",
    "merchantTransactionId": "A3bn43",
    "softDescriptor": "ABC COMPANY",
    "amount": "100.00",
    "currency": "USD",
    "payerInfo": {
      "firstName": "John",
      "lastName": "Doe"
    },
    "vaultedShopperId": "19587618",
    "paypalTransaction": {
      "paypalUrl": "https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout&token=EC-2FK36938XP960042T",
      "orderId": "4006145"
    },
    "processingInfo": { "processingStatus": "PENDING" }
  }
}

{
    "amount": 120.50,
    "vaultedShopperId": 1234,
    "payerInfo": {
        "firstName": "John",
        "lastName": "Doe"
    },
    "processingInfo": {"processingStatus": "PENDING"},
    "softDescriptor": "ABC COMPANY",
    "currency": "USD",
    "taxReference": "048deff0-a285-47e1-bc39-42f79bf0095b",
    "paypalTransaction": {
        "paypalUrl": "https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout&token=EC-0SM33181BF217002W",
        "orderId": 3979589
    }
}

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

📘
Important note about shopper's shipping information
The shopper's shipping information will only be sent if you set the noShipping property (in paypalTransaction) 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.

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. After the shopper approves the transaction, PayPal forwards the shopper's information and BlueSnap populates it in the newly created vaulted-shopper.

Create PayPal Transaction with payer info

To perform a Create PayPal Transaction and send information about the shopper, you'll need to include the payerInfo property within the altTransaction object. In this property, you can send information such as the shopper's first and last name, email, phone number, and address. See payerInfo.

Above is an example of a Create PayPal Transaction request with the shopper's first and last name sent in the payerInfo property.

Create PayPal Transaction with vaulted shopper

To perform a Create PayPal Transaction with an existing vaulted shopper, you'll need to include the vaultedShopperId property within the altTransaction object.

Important: If you set the noShipping property (in paypalTransaction) 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 merchantTransactionId property within the altTransaction object.

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 transactionMetaData property within the altTransaction object.

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

Above is an example of a Create PayPal Transaction request with the transactionDescription.

Create PayPal Transaction with In-Context checkout

If you would like to enable In-Context PayPal checkout, set the inContext property in the paypalTransaction object 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 paypalTransaction object, 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 paypalSubscriptionId in the paypalTransaction object.

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

API Explorer

To test out a call, enter the request content below and then click Try it!

Tip: Use the JSON code below as a starting point. You can enter different parameters 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.

{
    "amount": 100,
    "softDescriptor": "ABC COMPANY",
    "currency": "USD",
    "paypalTransaction": {
        "cancelUrl": "http://www.cancelURL.com",
        "returnUrl": "http://www.returnURL.com",
      	"transactionType": "SET_ORDER"
    }
}

Create PayPal Transaction

👍
Getting started with PayPal in BlueSnap

Request Content

Response Details

Examples

Request Examples

Response Examples

Example Descriptions

📘
Important note about shopper's shipping information

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

📘
How to get the subscription ID

API Explorer

👍Getting started with PayPal in BlueSnap

Request Content

Response Details

Examples

Request Examples

Response Examples

Example Descriptions

📘Important note about shopper's shipping information

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

📘How to get the subscription ID

API Explorer

👍
Getting started with PayPal in BlueSnap

📘
Important note about shopper's shipping information

📘
How to get the subscription ID