Create an order

DocsLimited

Last updated: Oct 1st, 9:20am

Create an order to begin the Afterpay payment process.

Automatic capture occurs immediately after buyer approval, streamlining the payment process. You can choose when to provide payment source details by including them during order creation (single-step) or adding them separately after creating the order (multi-step).

Single-step flow

Include payment source details directly in the create order request for a streamlined integration.

Use a valid access token and send a POST request to /v2/checkout/orders with request body parameters including intent set to CAPTURE, purchase_units with amount and currency (USD or GBP only), invoice_id (mandatory for Afterpay), payment_source with Afterpay details, and processing_instruction set to ORDER_COMPLETE_ON_PAYMENT_APPROVAL.

On successful order creation, complete the Afterpay payment with these steps:

Review order response: PayPal returns order ID with PAYER_ACTION_REQUIRED status and payer-action link

Redirect your buyer: Send the buyer to the payer-action URL to complete payment on Afterpay's platform

Monitor payment status: Buyer approves payment and order status automatically changes to COMPLETED

Payment captured: The payment is automatically captured upon buyer approval (no additional capture call needed for Afterpay)
Notify the buyer: Display order confirmation and send receipt or tracking information to complete the purchase experience.

Sample request
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  "processing_instruction": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL",
8  "payment_source": {
9    "afterpay": {
10      "name": {
11        "given_name": "John",
12        "surname": "Doe"
13      },
14      "email_address": "[email protected]",
15      "billing_address": {
16        "address_line_1": "2211 N 1st St.",
17        "admin_area_1": "CA",
18        "admin_area_2": "San Jose",
19        "postal_code": "95131",
20        "country_code": "US"
21      },
22      "experience_context": {
23        "return_url": "https://www.example.com/returnUrl",
24        "cancel_url": "https://www.example.com/cancelUrl"
25      }
26    }
27  },
28  "purchase_units": [
29    {
30      "reference_id": "default",
31      "amount": {
32        "breakdown": {
33            "item_total": {
34                "currency_code": "USD",
35                "value": "24.10"
36            },
37            "tax_total": {
38                "currency_code": "USD",
39                "value": "2.00"
40            }
41        },
42        "currency_code": "USD",
43        "value": "26.10"
44      },
45      "payee": {
46        "merchant_id": "M683SLY6MTM78",
47        "email_address": "[email protected]"
48      },
49      "custom_id": "Custom-1234",
50      "invoice_id": "Invoice-{{$timestamp}}",
51      "shipping": {
52        "name": {
53          "full_name": "Luke Skywalker"
54        },
55        "address": {
56          "address_line_1": "10025 Alterra Pkwy",
57          "address_line_2": "Suite 2400",
58          "admin_area_1": "TX",
59          "admin_area_2": "Austin",
60          "postal_code": "78758",
61          "country_code": "US"
62        }
63      },
64      "items": [
65        {
66          "name": "Shirt",
67          "quantity": "1",
68          "supplementary_data": [],
69          "postback_data": [],
70          "unit_amount": {
71            "currency_code": "USD",
72            "value": "12.05"
73          },
74          "tax": {
75            "currency_code": "USD",
76            "value": "1.00"
77          }
78        },
79        {
80          "name": "Trouser",
81          "quantity": "1",
82          "supplementary_data": [],
83          "postback_data": [],
84          "unit_amount": {
85            "currency_code": "USD",
86            "value": "12.05"
87          },
88          "tax": {
89            "currency_code": "USD",
90            "value": "1.00"
91          }
92        }
93      ]
94    }
95  ]
96}

Multi-step flow

For more flexibility, you can create the order first, then add payment source details in a separate step.

Use a valid access token and send a POST request to /v2/checkout/orders with request body parameters including intent set to CAPTURE, purchase_units with amount and currency (USD or GBP only), invoice_id (mandatory for Afterpay), and processing_instruction set to ORDER_COMPLETE_ON_PAYMENT_APPROVAL.

On successful order creation, complete the Afterpay payment with these steps:

Review order response: PayPal returns order ID with CREATED status and confirm link

Sample request
Response example

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  "processing_instruction": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL",
8  "purchase_units": [
9    {
10      "reference_id": "default",
11      "amount": {
12        "breakdown": {
13            "item_total": {
14                "currency_code": "USD",
15                "value": "24.10"
16            },
17            "tax_total": {
18                "currency_code": "USD",
19                "value": "2.00"
20            }
21        },
22        "currency_code": "USD",
23        "value": "26.10"
24      },
25      "payee": {
26        "merchant_id": "M683SLY6MTM78",
27        "email_address": "[email protected]"
28      },
29      "custom_id": "Custom-1234",
30      "invoice_id": "Invoice-{{$timestamp}}",
31      "shipping": {
32        "name": {
33          "full_name": "Luke Skywalker"
34        },
35        "address": {
36          "address_line_1": "10025 Alterra Pkwy",
37          "address_line_2": "Suite 2400",
38          "admin_area_1": "TX",
39          "admin_area_2": "Austin",
40          "postal_code": "78758",
41          "country_code": "US"
42        }
43      },
44      "items": [
45        {
46          "name": "Shirt",
47          "quantity": "1",
48          "supplementary_data": [],
49          "postback_data": [],
50          "unit_amount": {
51            "currency_code": "USD",
52            "value": "12.05"
53          },
54          "tax": {
55            "currency_code": "USD",
56            "value": "1.00"
57          }
58        },
59        {
60          "name": "Trouser",
61          "quantity": "1",
62          "supplementary_data": [],
63          "postback_data": [],
64          "unit_amount": {
65            "currency_code": "USD",
66            "value": "12.05"
67          },
68          "tax": {
69            "currency_code": "USD",
70            "value": "1.00"
71          }
72        }
73      ]
74    }
75  ]
76}

Add payment source details: Send POST request to /v2/checkout/orders/{order_id}/confirm-payment-source with complete payment_source.afterpay object

Sample request
Sample response

1curl -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/{order_id}/confirm-payment-source \ 
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer <ACCESS_TOKEN>" \
4  -H "PayPal-Request-Id: <UNIQUE_REQUEST_ID>" \
5  -d '{
6    "payment_source": {
7        "afterpay": {
8            "name": {
9                "given_name": "John",
10                "surname": "Doe"
11                },
12            "email_address": "[email protected]",
13            "billing_address": {
14                "address_line_1": "2211 N 1st St.",
15                "admin_area_1": "CA",
16                "postal_code": "95131",
17                "country_code": "US"
18            },
19            "experience_context": {
20                "locale": "en-US",
21                "intent": "BUY",
22                "acquiring_channel": "ECOMMERCE",
23                "return_url": "https://www.example.com/returnUrl",
24                "cancel_url": "https://www.example.com/cancelUrl"
25            }
26        }
27    }
28}

Redirect your buyer: After confirmation, send the buyer to the payer-action URL returned in Step 2 to complete payment on Afterpay's platform

Monitor payment status: Buyer approves payment and capture occurs automatically

Payment captured: The payment is automatically captured upon buyer approval

Notify the buyer: Display order confirmation and send receipt or tracking information to complete the purchase experience

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	Payment capture timing. For Afterpay payments, must be set to `CAPTURE`.
`processing_instruction` Required, string	Order processing method. Must be set to `ORDER_COMPLETE_ON_PAYMENT_APPROVAL` for automatic capture.
`payment_source` Required, object	Payment method for the order. Must contain an `afterpay` object.
`payment_source.afterpay` Required, object	Details of the Afterpay payment method.
`payment_source.afterpay.name` Required, object	Name of the buyer.
`payment_source.afterpay.name.given_name` Required, string	First name of the buyer.
`payment_source.afterpay.name.surname` Required, string	Last name of the buyer.
`payment_source.afterpay.email_address` Required, string	Email address of the buyer.
`payment_source.afterpay.billing_address` Required, object	Billing address of the buyer.
`payment_source.afterpay.billing_address.address_line_1` Required, string	Street address of the buyer.
`payment_source.afterpay.billing_address.admin_area_1` Required, string	State or province code. Valid values: US states (e.g., CA, TX)
`payment_source.afterpay.billing_address.admin_area_2` Required, string	City name of the billing address.
`payment_source.afterpay.billing_address.postal_code` Required, string	Postal or ZIP code of the billing address.
`payment_source.afterpay.billing_address.country_code` Required, string	Country code for Afterpay payments. Valid values: `US` (United States) or `GB` (United Kingdom).
`payment_source.afterpay.experience_context` Required, object	Configuration for the buyer's checkout experience.
`payment_source.afterpay.experience_context.return_url` Required, string	URL to redirect the buyer after payment approval.
`payment_source.afterpay.experience_context.cancel_url` Required, string	URL to redirect the buyer for cancelled or failed payment.
`purchase_units` Required, array	Array containing purchase details for the order.
`purchase_units[].reference_id` string	Reference ID for the purchase unit. Defaults to `default`.
`purchase_units[].amount` Required, object	Total amount and currency for the purchase.
`purchase_units[].amount.currency_code` Required, string	Three-character currency code for Afterpay payments. Valid values: `USD` (US Dollar) or `GBP` (British Pound).
`purchase_units[].amount.value` Required, string	Total amount value.
`purchase_units[].amount.breakdown` object	Breakdown of the total amount by category.
`purchase_units[].invoice_id` Required, string	Merchant's invoice number.
`purchase_units[].custom_id` string	Custom identifier for merchant tracking.
`purchase_units[].payee` object	Recipient of the payment.
`purchase_units[].shipping` Recommended, object	Shipping information for the order.
`purchase_units[].items` Recommended, array	Array of line item details for the purchase.

Create an order

Single-step flow

Multi-step flow

Request and response parameters

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