Create a payment

To create an Express Checkout payment, set the payment intent to sale and include a list of items in the transaction object. The items enable buyers to see the transaction total when they check out at PayPal. If you omit items from the request, the PayPal windows do not display the transaction total.

You can optionally reference a web experience profile, by ID.

Request parameters

After you collect payment details from the buyer, include these details in the JSON payload of a create payment request:

Parameter Description
intent Set to one of the following:
  • sale. Makes an immediate Express Checkout payment.
  • authorize. Places the funds on hold for a later payment.
  • order. Indicates that the buyer has consented to a future purchase. Funds are authorized and captured at a later time without placing the funds on hold.
Authorizations are guaranteed for up to three days, though you can attempt to capture an authorization for up to 29 days. After the three-day honor period authorization expires, you can reauthorize the payment.
experience_profile_id Optionally, specify the PayPal-generated ID for a web experience profile.
redirect_urls Specify the return and cancel URLs:
  • return_url. The URL on your website to which to redirect a buyer when he or she approves a payment.
  • cancel_url. The URL on your website to which to redirect a buyer when he or she cancels a payment.
payment_method Set to paypal to choose the PayPal payment method.
transactions Specify an array that contains a transaction object with transaction information. The buyer must confirm this information later. You can update the transaction amount later to adjust for shipping fees, tax, and so on.
Include a list of items in the transaction object. The items enable buyers to see the transaction total when they check out at PayPal. If you omit items from the request, the PayPal windows do not display the transaction total.

Request

This sample Express Checkout payment request includes the ID of a web experience profile, redirect URLs, transaction details, and an item list:

curl -v https://api.sandbox.paypal.com/v1/payments/payment \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer Access-Token' \\
  -d '{
  "intent": "sale",
  "experience_profile_id":"experience_profile_id",
  "redirect_urls":
  {
    "return_url": "https://example.com",
    "cancel_url": "https://example.com"
  },
  "payer":
  {
    "payment_method": "paypal"
  },
  "transactions": [
  {
    "amount":
    {
      "total": "4.00",
      "currency": "USD",
      "details":
      {
        "subtotal": "2.00",
        "shipping": "1.00",
        "tax": "2.00",
        "shipping_discount": "-1.00"
      }
    },
    "item_list":
    {
      "items": [
      {
        "quantity": "1",
        "name": "item 1",
        "price": "1",
        "currency": "USD",
        "description": "item 1 description",
        "tax": "1"
      },
      {
        "quantity": "1",
        "name": "item 2",
        "price": "1",
        "currency": "USD",
        "description": "item 2 description",
        "tax": "1"
      }]
    },
    "description": "The payment transaction description.",
    "invoice_number": "merchant invoice",
    "custom": "merchant custom data"
  }]
}'

Response

A successful call returns a payment object with the state set to created and a set of HATEOAS links that enable you to complete operations that are related to this request:

{
  "id": "PAY-3WY97586JG9277715K3H2SOA",
  "intent": "sale",
  "state": "created",
  "payer":
  {
    "payment_method": "paypal"
  },
  "transactions": [
  {
    "amount":
    {
      "total": "4.00",
      "currency": "USD",
      "details":
      {
        "subtotal": "2.00",
        "tax": "2.00",
        "shipping": "1.00",
        "shipping_discount": "-1.00"
      }
    },
    "description": "This is the payment transaction description.",
    "custom": "merchant custom data",
    "invoice_number": "merchant invoice",
    "item_list":
    {
      "items": [
      {
        "name": "item 1",
        "description": "item 1 description",
        "price": "1.00",
        "currency": "USD",
        "tax": "1.00",
        "quantity": 1
      },
      {
        "name": "item 2",
        "description": "item 2 description",
        "price": "1.00",
        "currency": "USD",
        "tax": "1.00",
        "quantity": 1
      }]
    },
    "related_resources": [

    ]
  }],
  "create_time": "2016-02-26T01:24:08Z",
  "links": [
  {
    "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-3WY97586JG9277715K3H2SOA",
    "rel": "self",
    "method": "GET"
  },
  {
    "href": "https://www.sandbox.paypal.com/checkoutnow?token=EC-7YM73725XF342733W",
    "rel": "approval_url",
    "method": "REDIRECT"
  },
  {
    "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-3WY97586JG9277715K3H2SOA/execute",
    "rel": "execute",
    "method": "POST"
  }]
}

To start the checkout flow, pass the id to the client.

Note: For legacy integrations, you typically redirect the buyer to the "approval_url" under links. PayPal recommends that you use the client-side JavaScript integration instead.

Next

Execute the payment.