On this page
No Headings
Last updated: July 8, 2026
Note: The integration steps for implementing alternative payment methods are similar. If you've integrated another alternative payment method before, you can likely reuse that code with adjustments for this payment method.
PAYMENT.CAPTURE.PENDING – Listen for this webhook as an indication that payment initiation was successful, the payment is in a pending state, and is waiting for the buyer to complete the payment. You'll act on this webhook in the Redirect buyer for purchase approval step.
PAYMENT.CAPTURE.COMPLETED – Listen for this webhook as an indication that the buyer has completed the payment, which can take up to seven days. You can ship the order to the buyer at this point. You'll act on this webhook in the Fulfill the order step.
PAYMENT.CAPTURE.DENIED - Listen for this webhook as an indication that the Multibanco payment instruction has expired or the payer didn't complete the payment on time. You can cancel the order at this point. You'll act on this webhook in the Fulfill the order step.
After you receive each webhook, fetch the latest order details using Show order details. The up HATEOAS link in the webhook payload indicates the order associated with the capture.
You'll need to create the user interface to offer Trustly and collect the buyer's information, then you'll use the API calls described in the remainder of this topic to:
full_name, country_code, and trustly as the payment source.Refer to Payment method icons for icons you can use and download locations.
Use the buyer information you captured from your user interface to create an order with Trustly as the payment source.
API endpoint used: Create order
curl -v -X POST 'https://api-m.sandbox.paypal.com/v2/checkout/orders' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS-TOKEN' \
-H 'PayPal-Request-Id: PAYPAL-REQUESTID' \
-d '{
"intent": "CAPTURE",
"purchase_units": [
{
"reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
"amount": {
"currency_code": "EUR",
"value": "100.00"
}
}
],
"payment_source": {
"trustly": {
"country_code": "NL",
"name": "Firstname Lastname"
}
},
"processing_instruction": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL",
"application_context": {
"locale": "en-NL",
"return_url": "https://example.com/returnUrl",
"cancel_url": "https://example.com/cancelUrl"
}
}'After you copy the code in the sample request, modify the following:
ACCESS-TOKEN - Your access token.PayPal-Request-Id - Replace the sample ID with a unique ID you generate. This ID helps prevent duplicate authorizations in the event that the API call is disrupted. See also: API idempotency.intent - Set this value to CAPTURE.payment_source - Specify trustly as the payment method, and include the following:
country_code - the 2-character country code for the payer's location.name - The payer's full name.email - The payer's email.application_context - Specify the following:
locale - The preferred language for returned errors.return_url - The URL the buyer is returned to after approving or canceling the purchase with their selected payment method.cancel_url - The URL is a placeholder for future reference for now.processing_instruction - Set this value to ORDER_COMPLETE_ON_PAYMENT_APPROVAL.purchase_units: amount - Pass the value of the order and the currency code.Note: Change or add other parameters in the Create order request body to create an order that reflects the actual order details.
A successful request results in the following:
200 OK.payer-action HATEOAS URL in the next step, Redirect buyer for purchase approval. See also: HATEOAS links.In your user interface, attach the payer-action redirect URL returned in the Create order response to the Trustly payment button.
In the sample, the redirect URL is: "https://www.sandbox.paypal.com/payment/trustly?token=5O190127TN364715T".
COMPLETED, which means the order was created successfully.PENDING status is present in the response parameter purchase_units[0].payments.captures[0]. The up HATEOAS link indicates the order associated with this capture.PAYMENT.CAPTURE.PENDING webhook event is triggered, which indicates that payment initiation was successful, the payment is in a pending state, and is waiting for the buyer to complete the payment.{
"id": "WH-4TV11484PJ0099250-1WB8208433136945G",
"event_version": "1.0",
"create_time": "2023-10-19T11:50:35.619Z",
"resource_type": "capture",
"resource_version": "2.0",
"event_type": "PAYMENT.CAPTURE.PENDING",
"summary": "Payment pending for EUR 15.39 EUR",
"resource": {
"id": "892032536L382192T",
"amount": {
"currency_code": "EUR",
"value": "15.39"
},
"final_capture": true,
"invoice_id": "Invoice-12345",
"custom_id": "Custom-1234",
"status": "PENDING",
"status_details": {
"reason": "OTHER"
},
"supplementary_data": {
"related_ids": {
"order_id": "5O190127TN364715T"
}
},
"payee": {
"email_address": "payee@example.com",
"merchant_id": "1111111111111"
},
"create_time": "2023-10-19T11:50:31Z",
"update_time": "2023-10-19T11:50:31Z",
"links": [
{
"href": "https://api-m.sandbox.paypal.com/v2/payments/captures/892032536L382192T",
"rel": "self",
"method": "GET"
},
{
"href": "https://api-m.sandbox.paypal.com/v2/payments/captures/892032536L382192T/refund",
"rel": "refund",
"method": "POST"
},
{
"href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
"rel": "up",
"method": "GET"
}
]
},
"links": [
{
"href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-4TV11484PJ0099250-1WB8208433136945G",
"rel": "self",
"method": "GET"
},
{
"href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-4TV11484PJ0099250-1WB8208433136945G/resend",
"rel": "resend",
"method": "POST"
}
]
}After the buyer authorizes the payment, and the payment completes:
return_url mentioned in the Create order request.COMPLETED.PAYMENT.CAPTURE.COMPLETED webhook event is triggered, which indicates that payment capture was successful. You can ship the order to the buyer at this point.Note: Once the buyer authorizes the payment, payment completion happens within 7 days, depending on the bank used for the payment. You should wait until payment completion to ship the goods.
If the payment is not successful:
cancel_url mentioned in the Create order request.DENIED.PAYMENT.CAPTURE.DENIED webhook event is triggered, which indicates that the payment capture wasn't successful. You shouldn't fulfill the order.See Subscribe to checkout webhooks for more information.
Here are some additional resources as you create webhook handler code:
{
"id": "WH-81H706078A5332206-4WN94402WA949352E",
"event_version": "1.0",
"zts": 1481046241,
"create_time": "2023-10-19T12:18:27.538Z",
"resource_type": "capture",
"resource_version": "2.0",
"event_type": "PAYMENT.CAPTURE.COMPLETED",
"summary": "Payment completed for EUR 15.39 EUR",
"resource": {
"id": "892032536L382192T",
"amount": {
"currency_code": "EUR",
"value": "15.39"
},
"final_capture": true,
"status": "COMPLETED",
"status_details": {
"reason": "OTHER"
},
"payee": {
"email_address": "payee@example.com",
"merchant_id": "1111111111111"
},
"create_time": "2023-10-19T11:50:31Z",
"update_time": "2023-10-19T12:18:22Z",
"links": [
{
"href": "https://api-m.sandbox.paypal.com/v2/payments/captures/892032536L382192T",
"rel": "self",
"method": "GET"
},
{
"href": "https://api-m.sandbox.paypal.com/v2/payments/captures/892032536L382192T/refund",
"rel": "refund",
"method": "POST"
},
{
"href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
"rel": "up",
"method": "GET"
}
]
},
"links": [
{
"href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-81H706078A5332206-4WN94402WA949352E",
"rel": "self",
"method": "GET"
},
{
"href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-81H706078A5332206-4WN94402WA949352E/resend",
"rel": "resend",
"method": "POST"
}
]
}Notes:
resource.supplementary_data.related_ids.order_id parameter in the webhook payload.Alternatively, if your app misses the webhook needed to capture the order, you can get the order capture result by sending a GET call to the Show order details endpoint of the Orders v2 API.
Important: Exercise caution when polling for order capture results using the Show order details endpoint. PayPal enforces rate limits on API requests.
A successful request returns the HTTP 200 OK status code with a JSON response body that returns a COMPLETED status.
curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/9R480625CB7539041 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ACCESS-TOKEN"A successfully captured order has the following:
COMPLETED, which means the order was captured successfully.COMPLETED status is present in the response parameter purchase_units[0].payments.captures[0].up HATEOAS link indicates the order associated with this capture.This section shows how to handle payment responses.
After a successful payment, notify the buyer of a successful transaction. You can do this by sending a confirmation email.
If Step 2 is unsuccessful and returns an HTTP 422 UNPROCESSABLE_ENTITY status code, the JSON response body should contain an error code in the issue parameter. Use this information to display the appropriate error message to the buyer.
API endpoint used: Create order
curl -L -X POST 'https://api-m.sandbox.paypal.com/v2/checkout/orders' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS-TOKEN' \
-H 'PayPal-Request-Id: PAYPAL-REQUESTID' \
--data-raw '{
"intent": "CAPTURE",
"purchase_units": [
{
"reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
"amount": {
"currency_code": "SEK",
"value": "100.00"
}
}
],
"payment_source": {
"trustly": {
"country_code": "NL",
"name": "Firstname Lastname"
}
},
"processing_instruction": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL",
"application_context": {
"locale": "en-NL",
"return_url": "https://example.com/returnUrl",
"cancel_url": "https://example.com/cancelUrl"
}
}'An unsuccessful request returns a JSON response body that includes:
422 Unprocessable Entity.details.issue parameter.details.description parameter.CHECKOUT.PAYMENT-APPROVAL.REVERSED webhook as an indication that an approved order wasn't captured for certain reasons resulting in a cancellation of the order and a refund the buyer's account. Then notify your buyer of the problem and the reversed order.