Accept Satispay payments

DocsBeta

Last updated: Sept 19th, 3:21am

Satispay is a mobile app that helps users pay in stores and send money to friends and family.

Satispay is available in the following countries:

Seller Countries	Payment type	Payment flow	Currencies	Maximum amount	Refunds
Austria (`AT`) Belgium (`BE`) Cyprus (`CY`) Estonia (`EE`) Finland (`FI`) France (`FR`) Germany (`DE`) Greece (`GR`) Ireland (`IE`) Italy (`IT`) Latvia (`LV`) Lithuania (`LT`) Luxembourg (`LU`) Malta (`MT`) San Marino (`SM`) Slovakia (`SK`) Slovenia (`SI`) Spain (`ES`)	Wallet	Redirect	`EUR`	N/A	Within 90 days

How it works

Alternative,payment,methods,diagram

You add alternative payment methods to your checkout page.

Payer provides their personal details and selects an alternative payment method from your checkout page.

Payer is transferred from your checkout page to the third-party bank to authorize and confirm payment.

Payer returns to your site to see confirmation of purchase.

Know before you code

Complete the steps in Get started to get your sandbox account information from the Developer Dashboard:
- Client ID
- Client Secret
- Business account credentials

Make sure the preference for receiving payments in your PayPal business account is set to accept and convert them to the default currency. To verify, in your profile select Account Settings > Payment preferences > Block payments and select Update to mark this preference.

This client-side and server-side integration uses the following:

Make sure you're subscribed to the following webhook events:
- Listen for the CHECKOUT.ORDER.APPROVED webhook in order to retrieve order details.
- Listen for the PAYMENT.CAPTURE.PENDING, PAYMENT.CAPTURE.COMPLETED, and PAYMENT.CAPTURE.DENIED webhooks, which indicate payment capture status.

By adding funding sources to your checkout integration, you agree to the PayPal alternative payment methods agreement. This is in addition to the user agreement applicable to the country in which your business is physically located.

Integration steps for implementing alternate payment methods are similar. If an alternate payment method has been previously integrated, most of the code may be reused.

1. Offer Satispay on your checkout page

You'll need to create the user interface to offer Satispay and collect the payer's full name. Then you'll use the API calls described in the remainder of this topic to:

Create the order with Satispay as the payment method, the payer's full name, and the country_code.

Redirect the payer to Satispay.

Refer to Payment method icons for icons you to use on your checkout page.

2. Create an order with Satispay as the payment source

Use the payer information you captured from your user interface to create an order with Satispay as the payment source.

Sample request

API endpoint used: Create order

1curl --location --request POST 'https://api-m.sandbox.paypal.com/v2/checkout/orders' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer ACCESS-TOKEN' \
4--header 'PayPal-Request-Id: PAYPAL-REQUEST-ID' \
5--data-raw '{
6    "intent": "CAPTURE",
7    "payment_source": {
8        "satispay": {
9            "country_code": "IT",
10            "name": "John Doe"
11            "experience_context": {
12              "locale": "it-IT",
13              "return_url": "https://example.com/returnUrl",
14              "cancel_url": "https://example.com/cancelUrl"
15            }
16        }
17    },
18    "processing_instruction": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL",
19    "purchase_units": [
20    {
21      "invoice_id": "Invoice-12345",
22      "custom_id": "Custom-1234",
23      "amount": {
24        "currency_code": "EUR",
25        "value": "49.11"
26      },
27      "shipping": {
28        "name": {
29          "full_name": "John Doe"
30        },
31        "address": {
32          "address_line_1": "Lungotevere Arnaldo da Brescia, 15",
33          "address_line_2": "Floor 6",
34          "admin_area_2": "Roma",
35          "admin_area_1": "rm",
36          "postal_code": "00196",
37          "country_code": "IT"
38        }
39      }
40    }
41  ]
42}'

Modify the code

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 that you generate. The PAYPAL-REQUEST-ID helps prevent duplicate authorizations if the API call is disrupted. For more information about idempotent requests, see API idempotency.

intent - Set this value to CAPTURE.

payment_source - Specify satispay, and include the following:
- country_code
- name - The payer's full name.

experience_context - Specify the following:
- locale - The preferred language for returned errors
- return_url - The URL the buyer is returned to after approving the purchase with their selected payment method.
- cancel_url - The URL the buyer is returned to after canceling an approval with their selected payment method.

processing_instruction - Set this value to ORDER_COMPLETE_ON_PAYMENT_APPROVAL.

purchase_units: amount - Specify 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.

Step result

A successful request results in the following:

A return status code of HTTP 200 OK.

A JSON response body that contains the order ID.

HATEOAS links.

Sample response

1{
2    "id": "5V159329PV571861D",
3    "status": "PAYER_ACTION_REQUIRED",
4    "payment_source": {
5        "satispay": {
6            "name": "John Doe",
7            "country_code": "IT"
8        }
9    },
10    "links": [
11        {
12            "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D",
13            "rel": "self",
14            "method": "GET"
15        },
16        {
17            "href": "https://www.sandbox.paypal.com/payment/satispay?token=5V159329PV571861D",
18            "rel": "payer-action",
19            "method": "GET"
20        }
21    ]
22}

In this sample, the order ID is 5V159329PV571861D.

3. Redirect payer to Satispay

In your user interface, attach the payer-action redirect URL returned in the Create Order response to the Satispay payment button. This sends the payer to their wallet to approve the purchase. After the payer approves the purchase, the payment is automatically captured.

In the previous sample, the redirect URL is: "https://www.sandbox.paypal.com/payment/satispay?token=5V159329PV571861D".

Step result

After completing the wallet transaction:

The payer is redirected to the return_url in the Create Order request.

The PAYMENT.CAPTURE.COMPLETED webhook event is triggered, indicating successful payment capture.

After unsuccessful bank approval, the payer is redirected to the cancel_url in the Create Order request.

4. Listen to webhooks to get the result of payment status

The following webhooks provide the result of order capture:

The PAYMENT.CAPTURE.COMPLETED webhook event indicates a successful order capture.

The PAYMENT.CAPTURE.DENIED webhook events indicate a failed order capture.

Optional: Use Show order details endpoint to determine the status of an order.
- The up HATEOAS link indicates the order associated with this capture.

For more information about webhooks, see:

Subscribe to checkout webhooks

Webhook Management API - Manage webhooks, list event notifications, and so on.

Checkout webhook events - Checkout payer approval-related webhooks.

Order webhook events - Other order-related webhooks.

Show order details endpoint - Determine the status of an order.

Sample `PAYMENT.CAPTURE.COMPLETED` webhook

1{
2  "id": "WH-9LK14475MF9937440-9EG47645TP521822L",
3  "event_version": "1.0",
4  "create_time": "2022-05-10T06:04:12.533Z",
5  "resource_type": "capture",
6  "resource_version": "2.0",
7  "event_type": "PAYMENT.CAPTURE.COMPLETED",
8  "summary": "Payment completed for 100.0 EUR",
9  "resource": {
10    "amount": {
11      "value": "100.00",
12      "currency_code": "EUR"
13    },
14    "supplementary_data": {
15      "related_ids": {
16        "order_id": "5V159329PV571861D"
17      }
18    },
19    "update_time": "2022-01-19T06:04:08Z",
20    "create_time": "2022-01-19T06:04:08Z",
21    "final_capture": true,
22    "seller_receivable_breakdown": {
23      "paypal_fee": {
24        "value": "3.80",
25        "currency_code": "EUR"
26      },
27      "gross_amount": {
28        "value": "100.00",
29        "currency_code": "EUR"
30      },
31      "net_amount": {
32        "value": "96.20",
33        "currency_code": "EUR"
34      }
35    },
36    "custom_id": "Custom-1234",
37    "invoice_id": "Invoice-12345",
38    "links": [
39      {
40        "method": "GET",
41        "rel": "self",
42        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J"
43      },
44      {
45        "method": "POST",
46        "rel": "refund",
47        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J/refund"
48      },
49      {
50        "method": "GET",
51        "rel": "up",
52        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D"
53      }
54    ],
55    "id": "5R102774VL663561J",
56    "status": "COMPLETED"
57  },
58  "links": [
59    {
60      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9LK14475MF9937440-9EG47645TP521822L",
61      "rel": "self",
62      "method": "GET"
63    },
64    {
65      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9LK14475MF9937440-9EG47645TP521822L/resend",
66      "rel": "resend",
67      "method": "POST"
68    }
69  ]
70}

Note: The order ID should match the resource.supplementary_data.related_ids.order_id parameter in the webhook payload.

Sample `PAYMENT.CAPTURE.DENIED` webhook

1{
2  "id": "WH-9LK14475MF9937440-9EG47645TP521822L",
3  "event_version": "1.0",
4  "create_time": "2022-05-10T06:04:12.533Z",
5  "resource_type": "capture",
6  "resource_version": "2.0",
7  "event_type": "PAYMENT.CAPTURE.DENIED",
8  "summary": "Payment denied for EUR 100.0 EUR",
9  "resource": {
10    "amount": {
11      "value": "100.00",
12      "currency_code": "EUR"
13    },
14    "supplementary_data": {
15      "related_ids": {
16        "order_id": "5V159329PV571861D"
17      }
18    },
19    "update_time": "2022-05-10T06:04:08Z",
20    "create_time": "2022-05-10T06:04:08Z",
21    "final_capture": true,
22    "seller_receivable_breakdown": {
23      "paypal_fee": {
24        "value": "3.80",
25        "currency_code": "EUR"
26      },
27      "gross_amount": {
28        "value": "100.00",
29        "currency_code": "EUR"
30      },
31      "net_amount": {
32        "value": "96.20",
33        "currency_code": "EUR"
34      }
35    },
36    "links": [
37      {
38        "method": "GET",
39        "rel": "self",
40        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J"
41      },
42      {
43        "method": "POST",
44        "rel": "refund",
45        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J/refund"
46      },
47      {
48        "method": "GET",
49        "rel": "up",
50        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D"
51      }
52    ],
53    "id": "5R102774VL663561J",
54    "status": "DECLINED"
55  },
56  "links": [
57    {
58      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9LK14475MF9937440-9EG47645TP521822L",
59      "rel": "self",
60      "method": "GET"
61    },
62    {
63      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9LK14475MF9937440-9EG47645TP521822L/resend",
64      "rel": "resend",
65      "method": "POST"
66    }
67  ]
68}

Note: The order ID should match the resource.supplementary_data.related_ids.order_id parameter in the webhook payload.

You can also get the order capture result from the Show order details endpoint.

Note: Rate limits apply on API requests for order capture results using the Show order details endpoint.

Sample request

1curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer ACCESS-TOKEN"

Sample response

1{
2  "id": "5V159329PV571861D",
3  "intent": "CAPTURE",
4  "status": "COMPLETED",
5  "payment_source": {
6    "satispay": {
7      "name": "John Doe",
8      "country_code": "IT"
9    }
10  },
11  "processing_instruction": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL",
12  "purchase_units": [
13    {
14      "reference_id": "default",
15      "amount": {
16        "currency_code": "EUR",
17        "value": "100.00"
18      },
19      "payments": {
20        "captures": [
21          {
22            "id": "5R102774VL663561J",
23            "status": "COMPLETED",
24            "amount": {
25              "currency_code": "EUR",
26              "value": "100.00"
27            },
28            "final_capture": true,
29            "seller_receivable_breakdown": {
30              "gross_amount": {
31                "currency_code": "EUR",
32                "value": "100.00"
33              },
34              "paypal_fee": {
35                "currency_code": "EUR",
36                "value": "3.80"
37              },
38              "net_amount": {
39                "currency_code": "EUR",
40                "value": "96.20"
41              }
42            },
43            "links": [
44              {
45                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J",
46                "rel": "self",
47                "method": "GET"
48              },
49              {
50                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J/refund",
51                "rel": "refund",
52                "method": "POST"
53              },
54              {
55                "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D",
56                "rel": "up",
57                "method": "GET"
58              }
59            ]
60          }
61        ]
62      }
63    }
64  ],
65  "links": [
66    {
67      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D",
68      "rel": "self",
69      "method": "GET"
70    }
71  ]
72}

Step result

A successful request returns the HTTP 200 OK status code with a JSON response body that returns a COMPLETED status.

A captured order has the following:

A COMPLETED order status, which means the order was captured successfully.

A capture with COMPLETED status is present in the response parameter purchase_units[0].payments.captures[0].

The up HATEOAS link indicates the order associated with this capture.

5. Notify payer of success

After a successful payment, notify the payer of a successful transaction.

Next steps

Test in PayPal sandbox, then go live in PayPal's production environment.

Accept Satispay payments

How it works

Know before you code

1. Offer Satispay on your checkout page

2. Create an order with Satispay as the payment source

Sample request

Modify the code

Step result

Sample response

3. Redirect payer to Satispay

Step result

4. Listen to webhooks to get the result of payment status

Sample PAYMENT.CAPTURE.COMPLETED webhook

Sample PAYMENT.CAPTURE.DENIED webhook

Sample request

Sample response

Step result

5. Notify payer of success

Next steps

Sample `PAYMENT.CAPTURE.COMPLETED` webhook

Sample `PAYMENT.CAPTURE.DENIED` webhook