Skip to main content
POST
/
v2
/
checkout
/
orders
Create order
curl --request POST \
  --url https://api-m.sandbox.paypal.com/v2/checkout/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "intent": "CAPTURE",
  "purchase_units": [
    {
      "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
      "amount": {
        "currency_code": "USD",
        "value": "100.00"
      }
    }
  ]
}'
{
  "create_time": "<string>",
  "update_time": "<string>",
  "id": "<string>",
  "payment_source": {
    "card": {
      "name": "<string>",
      "last_digits": "<string>",
      "brand": "VISA",
      "available_networks": [
        "VISA"
      ],
      "type": "CREDIT",
      "authentication_result": {
        "liability_shift": "NO",
        "three_d_secure": {
          "authentication_status": "Y",
          "enrollment_status": "Y"
        }
      },
      "attributes": {
        "vault": {
          "id": "<string>",
          "status": "VAULTED",
          "links": [
            {}
          ],
          "customer": {
            "id": "<string>",
            "email_address": "<string>",
            "phone": {},
            "name": {},
            "merchant_customer_id": "<string>"
          }
        }
      },
      "from_request": {
        "expiry": "<string>",
        "last_digits": "<string>"
      },
      "expiry": "<string>",
      "bin_details": {
        "bin": "<string>",
        "issuing_bank": "<string>",
        "bin_country_code": "<string>",
        "products": [
          "<string>"
        ]
      },
      "stored_credential": {
        "payment_initiator": "CUSTOMER",
        "payment_type": "ONE_TIME",
        "usage": "FIRST",
        "previous_network_transaction_reference": {
          "id": "<string>",
          "date": "<string>",
          "network": "VISA",
          "acquirer_reference_number": "<string>"
        }
      }
    },
    "paypal": {
      "email_address": "<string>",
      "account_id": "<string>",
      "account_status": "VERIFIED",
      "name": {
        "given_name": "<string>",
        "surname": "<string>"
      },
      "phone_type": "FAX",
      "phone_number": {
        "national_number": "<string>"
      },
      "birth_date": "<string>",
      "business_name": "<string>",
      "tax_info": {
        "tax_id": "<string>",
        "tax_id_type": "BR_CPF"
      },
      "address": {
        "address_line_1": "<string>",
        "address_line_2": "<string>",
        "admin_area_2": "<string>",
        "admin_area_1": "<string>",
        "postal_code": "<string>",
        "country_code": "<string>"
      },
      "attributes": {
        "vault": {
          "id": "<string>",
          "status": "VAULTED",
          "links": [
            {
              "href": "<any>",
              "rel": "<any>",
              "method": "<any>"
            }
          ],
          "customer": {
            "id": "<string>",
            "email_address": "<string>",
            "phone": {
              "phone_type": "FAX",
              "phone_number": {}
            },
            "name": {
              "given_name": "<string>",
              "surname": "<string>"
            },
            "merchant_customer_id": "<string>"
          }
        },
        "cobranded_cards": [
          {
            "labels": [
              "<string>"
            ],
            "payee": {
              "email_address": "<string>",
              "merchant_id": "<string>"
            },
            "amount": {
              "currency_code": "<any>",
              "value": "<any>"
            }
          }
        ]
      },
      "stored_credential": {
        "payment_initiator": "CUSTOMER",
        "charge_pattern": "IMMEDIATE",
        "usage_pattern": "IMMEDIATE",
        "usage": "DERIVED"
      },
      "experience_status": "NOT_STARTED"
    },
    "bancontact": {
      "name": "<string>",
      "country_code": "<string>",
      "bic": "<string>",
      "iban_last_chars": "<string>",
      "card_last_digits": "<string>"
    },
    "blik": {
      "name": "<string>",
      "country_code": "<string>",
      "email": "<string>",
      "one_click": {
        "consumer_reference": "<string>"
      }
    },
    "eps": {
      "name": "<string>",
      "country_code": "<string>",
      "bic": "<string>"
    },
    "giropay": {
      "name": "<string>",
      "country_code": "<string>",
      "bic": "<string>"
    },
    "ideal": {
      "name": "<string>",
      "country_code": "<string>",
      "bic": "<string>",
      "iban_last_chars": "<string>"
    },
    "swish": "<any>",
    "mybank": {
      "name": "<string>",
      "country_code": "<string>",
      "bic": "<string>",
      "iban_last_chars": "<string>"
    },
    "p24": {
      "name": "<string>",
      "email": "<string>",
      "country_code": "<string>",
      "payment_descriptor": "<string>",
      "method_id": "<string>",
      "method_description": "<string>"
    },
    "sofort": {
      "name": "<string>",
      "country_code": "<string>",
      "bic": "<string>",
      "iban_last_chars": "<string>"
    },
    "trustly": {
      "name": "<string>",
      "country_code": "<string>",
      "email": "<string>",
      "bic": "<string>",
      "iban_last_chars": "<string>"
    },
    "apple_pay": {
      "id": "<string>",
      "token": "<string>",
      "name": "<string>",
      "email_address": "<string>",
      "phone_number": {
        "national_number": "<string>"
      },
      "card": {
        "name": "<string>",
        "last_digits": "<string>",
        "brand": "VISA",
        "available_networks": [
          "VISA"
        ],
        "type": "CREDIT",
        "authentication_result": {
          "liability_shift": "NO",
          "three_d_secure": {
            "authentication_status": "Y",
            "enrollment_status": "Y"
          }
        },
        "attributes": {
          "vault": {
            "id": "<string>",
            "status": "VAULTED",
            "links": [
              {}
            ],
            "customer": {
              "id": "<string>",
              "email_address": "<string>",
              "phone": {},
              "name": {},
              "merchant_customer_id": "<string>"
            }
          }
        },
        "from_request": {
          "expiry": "<string>",
          "last_digits": "<string>"
        },
        "expiry": "<string>",
        "bin_details": {
          "bin": "<string>",
          "issuing_bank": "<string>",
          "bin_country_code": "<string>",
          "products": [
            "<string>"
          ]
        },
        "stored_credential": {
          "payment_initiator": "CUSTOMER",
          "payment_type": "ONE_TIME",
          "usage": "FIRST",
          "previous_network_transaction_reference": {
            "id": "<string>",
            "date": "<string>",
            "network": "VISA",
            "acquirer_reference_number": "<string>"
          }
        },
        "billing_address": {
          "address_line_1": "<string>",
          "address_line_2": "<string>",
          "admin_area_2": "<string>",
          "admin_area_1": "<string>",
          "postal_code": "<string>",
          "country_code": "<string>"
        },
        "country_code": "<string>"
      },
      "attributes": {
        "vault": {
          "id": "<string>",
          "status": "VAULTED",
          "customer": {
            "id": "<string>",
            "name": {
              "given_name": "<string>",
              "surname": "<string>"
            }
          },
          "links": [
            {
              "href": "<string>",
              "rel": "<string>",
              "method": "GET"
            }
          ]
        }
      },
      "stored_credential": {
        "payment_initiator": "CUSTOMER",
        "payment_type": "ONE_TIME",
        "usage": "FIRST",
        "previous_network_transaction_reference": {
          "id": "<string>",
          "date": "<string>",
          "network": "VISA",
          "acquirer_reference_number": "<string>"
        }
      }
    },
    "google_pay": {
      "name": "<string>",
      "email_address": "<string>",
      "phone_number": {
        "country_code": "<string>",
        "national_number": "<string>"
      },
      "card": {
        "name": "<string>",
        "last_digits": "<string>",
        "type": "CREDIT",
        "brand": "VISA",
        "billing_address": {
          "address_line_1": "<string>",
          "address_line_2": "<string>",
          "admin_area_2": "<string>",
          "admin_area_1": "<string>",
          "postal_code": "<string>",
          "country_code": "<string>"
        },
        "authentication_result": {
          "liability_shift": "NO",
          "three_d_secure": {
            "authentication_status": "Y",
            "enrollment_status": "Y"
          }
        }
      }
    },
    "venmo": {
      "email_address": "<string>",
      "account_id": "<string>",
      "user_name": "<string>",
      "name": {
        "given_name": "<string>",
        "surname": "<string>"
      },
      "phone_number": {
        "national_number": "<string>"
      },
      "address": {
        "address_line_1": "<string>",
        "address_line_2": "<string>",
        "admin_area_2": "<string>",
        "admin_area_1": "<string>",
        "postal_code": "<string>",
        "country_code": "<string>"
      },
      "attributes": {
        "vault": {
          "id": "<string>",
          "status": "VAULTED",
          "customer": {
            "id": "<string>",
            "name": {
              "given_name": "<string>",
              "surname": "<string>"
            }
          },
          "links": [
            {
              "href": "<string>",
              "rel": "<string>",
              "method": "GET"
            }
          ]
        }
      }
    },
    "crypto": "<any>"
  },
  "intent": "CAPTURE",
  "processing_instruction": "<any>",
  "payer": {
    "email_address": "<string>",
    "payer_id": "<string>",
    "name": {
      "given_name": "<string>",
      "surname": "<string>"
    },
    "phone": {
      "phone_type": "FAX",
      "phone_number": {}
    },
    "birth_date": "<string>",
    "tax_info": {
      "tax_id": "<string>",
      "tax_id_type": "BR_CPF"
    },
    "address": {
      "address_line_1": "<string>",
      "address_line_2": "<string>",
      "admin_area_2": "<string>",
      "admin_area_1": "<string>",
      "postal_code": "<string>",
      "country_code": "<string>"
    }
  },
  "purchase_units": [
    {
      "reference_id": "<string>",
      "amount": {
        "currency_code": "<string>",
        "value": "<string>",
        "breakdown": {
          "item_total": {
            "currency_code": "<any>",
            "value": "<any>"
          },
          "shipping": {
            "currency_code": "<any>",
            "value": "<any>"
          },
          "handling": {
            "currency_code": "<any>",
            "value": "<any>"
          },
          "tax_total": {
            "currency_code": "<any>",
            "value": "<any>"
          },
          "insurance": {
            "currency_code": "<any>",
            "value": "<any>"
          },
          "shipping_discount": {
            "currency_code": "<any>",
            "value": "<any>"
          },
          "discount": {
            "currency_code": "<string>",
            "value": "<string>"
          }
        }
      },
      "payee": {
        "email_address": "<string>",
        "merchant_id": "<string>"
      },
      "payment_instruction": {
        "platform_fees": [
          {
            "amount": "<any>",
            "payee": "<any>"
          }
        ],
        "disbursement_mode": "INSTANT",
        "payee_pricing_tier_id": "<string>",
        "payee_receivable_fx_rate_id": "<string>"
      },
      "description": "<string>",
      "custom_id": "<string>",
      "invoice_id": "<string>",
      "id": "<string>",
      "soft_descriptor": "<string>",
      "items": [
        {
          "name": "<string>",
          "unit_amount": {
            "currency_code": "<any>",
            "value": "<any>"
          },
          "tax": {
            "currency_code": "<any>",
            "value": "<any>"
          },
          "quantity": "<string>",
          "description": "<string>",
          "sku": "<string>",
          "url": "<string>",
          "category": "DIGITAL_GOODS",
          "image_url": "<string>",
          "upc": {
            "type": "UPC-A",
            "code": "<string>"
          },
          "billing_plan": {
            "billing_cycles": [
              "<any>"
            ],
            "setup_fee": {},
            "name": "<string>"
          }
        }
      ],
      "shipping": {
        "name": {
          "full_name": "<string>"
        },
        "email_address": "<string>",
        "phone_number": {
          "country_code": "<string>",
          "national_number": "<string>"
        },
        "type": "SHIPPING",
        "options": [
          {
            "id": "<string>",
            "label": "<string>",
            "type": "SHIPPING",
            "amount": {
              "currency_code": "<any>",
              "value": "<any>"
            },
            "selected": true
          }
        ],
        "address": {
          "address_line_1": "<string>",
          "address_line_2": "<string>",
          "admin_area_2": "<string>",
          "admin_area_1": "<string>",
          "postal_code": "<string>",
          "country_code": "<string>"
        },
        "trackers": [
          {
            "id": "<string>",
            "status": "CANCELLED",
            "items": [
              {
                "name": "<string>",
                "quantity": "<string>",
                "sku": "<string>",
                "url": "<string>",
                "image_url": "<string>",
                "upc": {}
              }
            ],
            "links": [
              {
                "href": "<any>",
                "rel": "<any>",
                "method": "<any>"
              }
            ],
            "create_time": "<string>",
            "update_time": "<string>"
          }
        ]
      },
      "supplementary_data": {
        "card": {
          "level_2": {
            "invoice_id": "<string>",
            "tax_total": {
              "currency_code": "<any>",
              "value": "<any>"
            }
          },
          "level_3": {
            "shipping_amount": {
              "currency_code": "<any>",
              "value": "<any>"
            },
            "duty_amount": {
              "currency_code": "<any>",
              "value": "<any>"
            },
            "discount_amount": {
              "currency_code": "<any>",
              "value": "<any>"
            },
            "shipping_address": {
              "address_line_1": "<string>",
              "address_line_2": "<string>",
              "admin_area_2": "<string>",
              "admin_area_1": "<string>",
              "postal_code": "<string>",
              "country_code": "<string>"
            },
            "ships_from_postal_code": "<string>",
            "line_items": [
              {
                "name": "<string>",
                "quantity": "<string>",
                "description": "<string>",
                "sku": "<string>",
                "url": "<string>",
                "image_url": "<string>",
                "upc": {
                  "type": "UPC-A",
                  "code": "<string>"
                },
                "billing_plan": {
                  "billing_cycles": [
                    "<any>"
                  ],
                  "setup_fee": {},
                  "name": "<string>"
                },
                "unit_amount": {
                  "currency_code": "<any>",
                  "value": "<any>"
                },
                "tax": {
                  "currency_code": "<any>",
                  "value": "<any>"
                },
                "commodity_code": "<string>",
                "discount_amount": {
                  "currency_code": "<any>",
                  "value": "<any>"
                },
                "total_amount": {
                  "currency_code": "<any>",
                  "value": "<any>"
                },
                "unit_of_measure": "<string>"
              }
            ]
          }
        },
        "risk": {
          "customer": {
            "ip_address": "<string>"
          }
        }
      },
      "payments": {
        "authorizations": [
          {
            "status": "CREATED",
            "status_details": {
              "reason": "PENDING_REVIEW"
            },
            "id": "<string>",
            "amount": {
              "currency_code": "<any>",
              "value": "<any>"
            },
            "invoice_id": "<string>",
            "custom_id": "<string>",
            "network_transaction_reference": {
              "id": "<string>",
              "date": "<string>",
              "network": "VISA",
              "acquirer_reference_number": "<string>"
            },
            "seller_protection": {
              "status": "ELIGIBLE",
              "dispute_categories": [
                "<any>"
              ]
            },
            "expiration_time": "<string>",
            "links": [
              {
                "href": "<any>",
                "rel": "<any>",
                "method": "<any>"
              }
            ],
            "create_time": "<string>",
            "update_time": "<string>",
            "processor_response": {
              "avs_code": "A",
              "cvv_code": "E",
              "response_code": "0000",
              "payment_advice_code": "01"
            }
          }
        ],
        "captures": [
          {
            "status": "COMPLETED",
            "status_details": {
              "reason": "BUYER_COMPLAINT"
            },
            "id": "<string>",
            "amount": {
              "currency_code": "<any>",
              "value": "<any>"
            },
            "invoice_id": "<string>",
            "custom_id": "<string>",
            "network_transaction_reference": {
              "id": "<string>",
              "date": "<string>",
              "network": "VISA",
              "acquirer_reference_number": "<string>"
            },
            "seller_protection": {
              "status": "ELIGIBLE",
              "dispute_categories": [
                "<any>"
              ]
            },
            "final_capture": false,
            "seller_receivable_breakdown": {
              "gross_amount": {
                "currency_code": "<any>",
                "value": "<any>"
              },
              "paypal_fee": {
                "currency_code": "<any>",
                "value": "<any>"
              },
              "paypal_fee_in_receivable_currency": {
                "currency_code": "<any>",
                "value": "<any>"
              },
              "net_amount": {
                "currency_code": "<any>",
                "value": "<any>"
              },
              "receivable_amount": {
                "currency_code": "<any>",
                "value": "<any>"
              },
              "exchange_rate": {
                "source_currency": "<string>",
                "target_currency": "<string>",
                "value": "<string>"
              },
              "platform_fees": [
                {
                  "amount": "<any>",
                  "payee": "<any>"
                }
              ]
            },
            "disbursement_mode": "INSTANT",
            "links": [
              {
                "href": "<any>",
                "rel": "<any>",
                "method": "<any>"
              }
            ],
            "processor_response": {
              "avs_code": "A",
              "cvv_code": "E",
              "response_code": "0000",
              "payment_advice_code": "01"
            },
            "create_time": "<string>",
            "update_time": "<string>"
          }
        ],
        "refunds": [
          {
            "status": "CANCELLED",
            "status_details": {
              "reason": "ECHECK"
            },
            "id": "<string>",
            "amount": {
              "currency_code": "<any>",
              "value": "<any>"
            },
            "invoice_id": "<string>",
            "custom_id": "<string>",
            "acquirer_reference_number": "<string>",
            "note_to_payer": "<string>",
            "seller_payable_breakdown": {
              "gross_amount": {
                "currency_code": "<any>",
                "value": "<any>"
              },
              "paypal_fee": {
                "currency_code": "<any>",
                "value": "<any>"
              },
              "paypal_fee_in_receivable_currency": {
                "currency_code": "<any>",
                "value": "<any>"
              },
              "net_amount": {
                "currency_code": "<any>",
                "value": "<any>"
              },
              "net_amount_in_receivable_currency": {
                "currency_code": "<any>",
                "value": "<any>"
              },
              "platform_fees": [
                {
                  "amount": "<any>",
                  "payee": "<any>"
                }
              ],
              "net_amount_breakdown": [
                {
                  "payable_amount": {},
                  "converted_amount": {},
                  "exchange_rate": {}
                }
              ],
              "total_refunded_amount": {
                "currency_code": "<any>",
                "value": "<any>"
              }
            },
            "payer": {
              "email_address": "<string>",
              "merchant_id": "<string>"
            },
            "links": [
              {
                "href": "<any>",
                "rel": "<any>",
                "method": "<any>"
              }
            ],
            "create_time": "<string>",
            "update_time": "<string>"
          }
        ]
      },
      "most_recent_errors": [
        "<any>"
      ]
    }
  ],
  "status": "CREATED",
  "links": [
    {
      "href": "<any>",
      "rel": "<any>",
      "method": "<any>"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Oauth 2.0 authentication

Headers

​
PayPal-Request-Id
string

The server stores keys for 6 hours. The API callers can request the times to up to 72 hours by speaking to their Account Manager. It is mandatory for all single-step create order calls (E.g. Create Order Request with payment source information like Card, PayPal.vault_id, PayPal.billing_agreement_id, etc).

Required string length: 1 - 108
​
PayPal-Partner-Attribution-Id
string
Required string length: 1 - 36
​
PayPal-Client-Metadata-Id
string
Required string length: 1 - 36
​
Prefer
string
default:return=minimal

The preferred server response upon successful completion of the request. Value is:<ul><li><code>return=minimal</code>. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the <code>id</code>, <code>status</code> and HATEOAS links.</li><li><code>return=representation</code>. The server returns a complete resource representation, including the current state of the resource.</li></ul>

Required string length: 1 - 25
​
PayPal-Auth-Assertion
string

An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see <a href="https://developer.paypal.com/api/rest/requests/#paypal-auth-assertion">PayPal-Auth-Assertion</a>.

Body

application/json

The order request details.

​
intent
enum<string>
required

The intent to either capture payment immediately or authorize a payment for an order after order creation.

Available options:
CAPTURE,
AUTHORIZE
​
purchase_units
Purchase Unit Request · object[]
required

An array of purchase units. Each purchase unit establishes a contract between a payer and the payee. Each purchase unit represents either a full or partial order that the payer intends to purchase from the payee.

Required array length: 1 - 10 elements
​
payer
object

DEPRECATED. The customer is also known as the payer. The Payer object was intended to only be used with the payment_source.paypal object. In order to make this design more clear, the details in the payer object are now available under payment_source.paypal. Please use payment_source.paypal. The customer who approves and pays for the order. The customer is also known as the payer.

​
payment_source
object

The payment source definition.

​
application_context
object

Customize the payer experience during the approval process for the payment with PayPal.

Response

A successful response to an idempotent request returns the HTTP 200 OK status code with a JSON response body that shows order details.

The order details. The date and time stamps that are common to authorized payment, captured payment, and refund transactions.

​
create_time
string<ppaas_date_time_v3>

The date and time when the transaction occurred, in Internet date and time format.

Required string length: 20 - 64
​
update_time
string<ppaas_date_time_v3>

The date and time when the transaction was last updated, in Internet date and time format.

Required string length: 20 - 64
​
id
string

The ID of the order.

​
payment_source
object

The payment source used to fund the payment.

​
intent
enum<string>

The intent to either capture payment immediately or authorize a payment for an order after order creation.

Available options:
CAPTURE,
AUTHORIZE
​
processing_instruction
any
​
payer
object

DEPRECATED. The customer is also known as the payer. The Payer object was intended to only be used with the payment_source.paypal object. In order to make this design more clear, the details in the payer object are now available under payment_source.paypal. Please use payment_source.paypal. The customer who approves and pays for the order. The customer is also known as the payer.

​
purchase_units
Purchase Unit · object[]

An array of purchase units. Each purchase unit establishes a contract between a customer and merchant. Each purchase unit represents either a full or partial order that the customer intends to purchase from the merchant.

Required array length: 1 - 10 elements
​
status
enum<string>

The order status.

Available options:
CREATED,
SAVED,
APPROVED,
VOIDED,
COMPLETED,
PAYER_ACTION_REQUIRED
​
links
Link Description · object[]

An array of request-related HATEOAS links. To complete payer approval, use the approve link to redirect the payer. The API caller has 6 hours (default setting, this which can be changed by your account manager to 24/48/72 hours to accommodate your use case) from the time the order is created, to redirect your payer. Once redirected, the API caller has 6 hours for the payer to approve the order and either authorize or capture the order. If you are not using the PayPal JavaScript SDK to initiate PayPal Checkout (in context) ensure that you include application_context.return_url is specified or you will get "We're sorry, Things don't appear to be working at the moment" after the payer approves the payment.

⌘I