Accept Pix payments/
Accept Pix payments/
Create order

Create an order

DocsLimited

Last updated: Sept 11th, 10:05am

Create an order to begin the Pix payment process. You can configure the order for different capture flows:

  • Create order for manual capture - Requires a separate payment capture after buyer approval. You can either exclude processing_instruction or set it to NO_INSTRUCTION.
  • Create order for automatic capture - Capture happens immediately after buyer approval when processing_instruction is set to ORDER_COMPLETE_ON_PAYMENT_APPROVAL.

Choose the appropriate flow based on your integration needs. Manual capture provides more control over the payment process, while automatic capture streamlines the flow by combining order creation and payment capture.

Create order for manual capture

Use a valid access token and send a POST request to /v2/checkout/orders with request body parameters including intent, purchase_units with amount and currency (BRL only), and payment_source.pix object, and the PayPal-Request-Id header for idempotency.

On successful order creation, the PayPal server returns an order ID, Pix QR code, and a copy-and-paste string in the response. After the buyer completes the Pix payment, you need to capture payment.

Sample request and response

Select a tab to view either the sample request body for creating an order with manual capture flow or the sample response returned upon success.

  1. Sample request
  2. Sample response
1curl -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer <ACCESS_TOKEN>" \
4  -H "PayPal-Request-Id: <UNIQUE_REQUEST_ID>" \
5  -d '{
6    "intent": "CAPTURE",
7    "purchase_units": [
8        {
9        "invoice_id": "90210",
10        "amount": {
11            "currency_code": "BRL",
12            "value": "231.00",
13            "breakdown": {
14            "item_total": {
15                "currency_code": "BRL",
16                "value": "221.00"
17            },
18            "shipping": {
19                "currency_code": "BRL",
20                "value": "10.00"
21            }
22            }
23        },
24        "items": [
25            {
26            "name": "T-Shirt",
27            "description": "Super Fresh Shirt",
28            "unit_amount": {
29                "currency_code": "BRL",
30                "value": "21.00"
31            },
32            "quantity": "1",
33            "category": "PHYSICAL_GOODS",
34            "sku": "sku01",
35            "image_url": "https://example.com/static/images/items/1/tshirt_green.jpg",
36            "url": "https://example.com/url-to-the-item-being-purchased-1",
37            "upc": {
38                "type": "UPC-A",
39                "code": "123456789012"
40            }
41            },
42            {
43            "name": "Shoes",
44            "description": "Running, Size 10.5",
45            "sku": "sku02",
46            "unit_amount": {
47                "currency_code": "BRL",
48                "value": "100.00"
49            },
50            "quantity": "2",
51            "category": "PHYSICAL_GOODS",
52            "image_url": "https://example.com/static/images/items/1/shoes_running.jpg",
53            "url": "https://example.com/url-to-the-item-being-purchased-2",
54            "upc": {
55                "type": "UPC-A",
56                "code": "987654321012"
57            }
58            }
59        ]
60        }
61    ],
62    "payment_source": {
63        "pix": {
64            "name": "Jhon Smith",
65            "country_code": "BR",
66            "currency_code": "BRL",
67            "phone_number": "0123456789",
68            "email_id": "[email protected]",
69            "tax_info": {
70              "tax_id":"12312443",
71              "tax_id_type":"CPJ"
72            },
73            "qr_expiry": "3600",
74            "experience_context": {
75                "shipping_preference": "GET_FROM_FILE",
76                "return_url": "https://example.com/returnUrl",
77                "cancel_url": "https://example.com/cancelUrl"
78            }
79        }
80    }
81}'

Capture payment

For manual capture flow, after the buyer completes PIX payment and you receive the CHECKOUT.ORDER.APPROVED webhook, capture the payment to finalize the transaction.

Use a valid access token and send a POST request to /v2/checkout/orders/{order_id}/capture to capture the PIX payment. After capture completes, you'll receive a PAYMENT.CAPTURE.COMPLETED webhook notification with capture details and transaction information.


Response example

A successful capture returns HTTP status code 200 OK with order status COMPLETED:

    1{
    2    "id": "9L410655F4615111G",
    3    "status": "COMPLETED",
    4    "payment_source": {
    5        "pix": {
    6            "name": "Jhon Smith",
    7            "country_code": "BR"
    8        }
    9    },
    10    "purchase_units": [
    11        {
    12            "reference_id": "default",
    13            "payments": {
    14                "captures": [
    15                    {
    16                        "id": "38M5025413951612L",
    17                        "status": "COMPLETED",
    18                        "amount": {
    19                            "currency_code": "BRL",
    20                            "value": "123.00"
    21                        },
    22                        "final_capture": true,
    23                        "seller_protection": {
    24                            "status": "ELIGIBLE",
    25                            "dispute_categories": [
    26                                "ITEM_NOT_RECEIVED",
    27                                "UNAUTHORIZED_TRANSACTION"
    28                            ]
    29                        },
    30                        "seller_receivable_breakdown": {
    31                            "gross_amount": {
    32                                "currency_code": "BRL",
    33                                "value": "123.00"
    34                            },
    35                            "paypal_fee": {
    36                                "currency_code": "BRL",
    37                                "value": "4.18"
    38                            },
    39                            "net_amount": {
    40                                "currency_code": "BRL",
    41                                "value": "118.82"
    42                            }
    43                        },
    44                        "invoice_id": "Invoice-123456",
    45                        "custom_id": "Custom-12345",
    46                        "create_time": "2025-05-06T19:47:17Z",
    47                        "update_time": "2025-05-06T19:47:17Z"
    48                    }
    49                ]
    50            }
    51        }
    52    ]
    53}

    Create order for automatic capture

    Use a valid access token and send a POST request to /v2/checkout/orders with request body parameters including intent, purchase_units with amount and currency (BRL only), payment_source.pix object, processing_instruction set to ORDER_COMPLETE_ON_PAYMENT_APPROVAL and the PayPal-Request-Id header for idempotency. 

    On successful order creation, the PayPal server returns an order ID, Pix QR code, and a copy-and-paste string in the response. Payment is automatically captured when the buyer completes the Pix payment.

    Sample request and response

    Select a tab to view either the sample request body for creating an order with automatic capture flow or the sample response returned upon success.

    1. Sample request
    2. Sample response
    1curl -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
    2  -H "Content-Type: application/json" \
    3  -H "Authorization: Bearer <ACCESS_TOKEN>" \
    4  -H "PayPal-Request-Id: <UNIQUE_REQUEST_ID>" \
    5  -d '{
    6    "intent": "CAPTURE",
    7    "purchase_units": [
    8        {
    9        "invoice_id": "90210",
    10        "amount": {
    11            "currency_code": "BRL",
    12            "value": "231.00",
    13            "breakdown": {
    14            "item_total": {
    15                "currency_code": "BRL",
    16                "value": "221.00"
    17            },
    18            "shipping": {
    19                "currency_code": "BRL",
    20                "value": "10.00"
    21            }
    22            }
    23        },
    24        "items": [
    25            {
    26            "name": "T-Shirt",
    27            "description": "Super Fresh Shirt",
    28            "unit_amount": {
    29                "currency_code": "BRL",
    30                "value": "21.00"
    31            },
    32            "quantity": "1",
    33            "category": "PHYSICAL_GOODS",
    34            "sku": "sku01",
    35            "image_url": "https://example.com/static/images/items/1/tshirt_green.jpg",
    36            "url": "https://example.com/url-to-the-item-being-purchased-1",
    37            "upc": {
    38                "type": "UPC-A",
    39                "code": "123456789012"
    40            }
    41            },
    42            {
    43            "name": "Shoes",
    44            "description": "Running, Size 10.5",
    45            "sku": "sku02",
    46            "unit_amount": {
    47                "currency_code": "BRL",
    48                "value": "100.00"
    49            },
    50            "quantity": "2",
    51            "category": "PHYSICAL_GOODS",
    52            "image_url": "https://example.com/static/images/items/1/shoes_running.jpg",
    53            "url": "https://example.com/url-to-the-item-being-purchased-2",
    54            "upc": {
    55                "type": "UPC-A",
    56                "code": "987654321012"
    57            }
    58            }
    59        ]
    60        }
    61    ],
    62    "payment_source": {
    63        "pix": {
    64            "name": "Jhon Smith",
    65            "country_code": "BR",
    66            "currency_code": "BRL",
    67            "phone_number": "0123456789",
    68            "email_id": "[email protected]",
    69            "tax_info": {
    70              "tax_id":"12312443",
    71              "tax_id_type":"CPJ"
    72            },
    73            "qr_expiry": "3600",
    74            "experience_context": {
    75                "shipping_preference": "GET_FROM_FILE",
    76                "return_url": "https://example.com/returnUrl",
    77                "cancel_url": "https://example.com/cancelUrl"
    78            }
    79        }
    80    },
    81    "processing_instruction": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL"
    82}'

    Request and response parameters

    Select a tab to view either the required request parameters or the expected response parameters for order creation.

    Parameter name Description
    intent
    Required, string     		Indicates whether payment is captured immediately or authorized for later capture.

    For Pix payments, set to CAPTURE.
    payment_source.pix
    Required, object     		Details of the payment method.
    payment_source.pix.name
    Required, string     		Name of the buyer.
    payment_source.pix.country_code
    Required, string     		Country code for PIX payments. Must be BR for Brazil.
    payment_source.pix.currency_code
    Required, string     		Currency code for PIX payments. Must be BRL for Brazilian Real.
    payment_source.pix.phone_number
    Required, string     		Phone number of the buyer.
    payment_source.pix.email_id
    Required, string     		Email address of the buyer.
    payment_source.pix.tax_info
    Required, object     		Tax information for the buyer.
    payment_source.pix.tax_info.tax_id
    Required, string     		Tax identification number of the buyer.
    payment_source.pix.tax_info.tax_id_type
    Required, string     		Type of tax ID. Valid values: CPF (individual) or CNPJ (business).
    payment_source.pix.qr_expiry
    Required, string     		QR code expiration time in seconds. Must be between 600 seconds (10 minutes) and 259,200 seconds (72 hours).
    payment_source.pix.experience_context.shipping_preference
    Required, string     		Shipping preference for the payment.
    payment_source.pix.experience_context.return_url
    Required, string     		URL to redirect the buyer after payment approval.
    payment_source.pix.experience_context.cancel_url
    Required, string     		URL to redirect the buyer if they cancel the payment.
    purchase_units
    Required, array     		Lists the items or services the buyer is purchasing in the order.
    purchase_units.amount
    Required, object     		Total order amount and the currency code.

    For Pix payments, use BRL as the currency code.
    purchase_units.amount.currency_code
    Required, string     		Currency code for the payment. Must be BRL.
    purchase_units.amount.value
    Required, string     		Payment amount value. Must be in BRL currency to match the payment_source.pix configuration.
    processing_instruction
    Required, string     		Specifies how the order is finalized.

    Set to ORDER_COMPLETE_ON_PAYMENT_APPROVAL for automatic order completion when payment is received.

    You can either exclude processing_instruction or set it to NO_INSTRUCTION to capture the payment manually.
    ReferencePayPal.comPrivacyCookiesSupportLegalContact

    If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more