PayPal via Widget

This page includes the steps necessary to integrate PayPal using the DEUNA Widget.

Use the V1 endpoint for the Paypal widget.

📘

For more information, refer to the Payments API.

Make a purchase with the widget

V1 purchases require an existing order before processing a payment.

1. Create an order_token

To make a purchase, you must create a DEUNA order.

Make a request to the Create an Order endpoint.

The API returns an order_token, which is used throughout the entire flow.

2. Create user

Create a user with DEUNA to get an authorization token to perform the purchase later.

Make a request to the Create a User endpoint.

The API returns a user token, which is required to follow the next steps.

📘

OTP is recommended to get a new token each time a customer confirms through the SMS or Email the code. You can use an External Authentication login to manage the user auth tokens by your own without request them the OTP. Talk to your Sales Engineer for further guidance.

If the email does not exist, then a new user is created.

If the email used already exists:

  1. Then the API returns the message user already exists.
  2. Request the OTP and login with the OTP to obtain a fresh user token.
  3. You can now use thetoken for the next steps.

3. Get payment methods

Confirm the payment methods to obtain the PayPal Wallet configuration.

Make a request to the Get Payment Methods endpoint.

Request

curl --location '{{base_url}}/merchants/orders/{{order_token}}/payments-methods' \
--header 'x-api-key: {{merchant_private_key}}' \
--header 'Authorization: Bearer {{user_token}}'

Response

{
  "data": [
    {
      "enabled": true,
      "method_type": "wallet",
      "processor_name": "paypal_wallet", // PayPal Wallet identifier
      "exclude_cvv": false,
      "stored_payment_methods": [
        {
          "payment_method": "adb1ef51-e073-49f5-ba3b-a7e42344fd15",
          "account_identifier": "[email protected]"
        }
      ],
      "id": "58745b8e-7127-44ea-84ef-656b3ffc611b", // Payment method ID
      "authorization": {
        "required": true, // true | false
        "flow": "consent"
      }
    }
  ]
}

4. Perform a V1 purchase

Now that you have the payment method available, finish the payment process.

Purchase without vaulting

Make a request to the V1 Purchase endpoint.

Here is a list of required fields for PayPal Wallet:

FieldDescriptionValue
specific_fields.callbacks.on_successRedirect URL after authorizing the purchase with your PayPal Wallet account.https://example.com/
method_typeDEUNA payment method type.wallet
processor_namePayPal Wallet payment method identifier.paypal_wallet

Request

{
  "token": "{{order-token}}",
  "method_type": "wallet", // required for PayPal Wallet
  "processor_name": "paypal_wallet", // required for PayPal Wallet
  "email": "[email protected]",
  "device_id": "xxxxxxx", // PayPal device ID, used in STC
  "specific_fields": {
    "callbacks": {
      "on_success": "https://example.com" // required for PayPal Wallet
    }
  }
}

Purchase with vaulting

Make a request to the V1 Purchase endpoint.

Here is a list of required fields for PayPal Wallet:

FieldDescriptionValue
method_typeDEUNA payment method type.wallet
processor_namePayPal Wallet payment method identifier.paypal_wallet
payment_methodPayPal account token.6fe9a045-9a46-4b25-8b60-d5a9586494c5
payment_method_idPayPal Wallet payment method ID returned in the id field of the Get Payment Methods response.58745b8e-7127-44ea-84ef-656b3ffc611b
  • Request
    {
      "token": "{{order-token}}",
      "method_type": "wallet", // required for PayPal Wallet
      "processor_name": "paypal_wallet", // required for PayPal Wallet
      "email": "[email protected]",
      "payment_method": "{{payment_method}}", // required
      "payment_method_id": "{{payment_method_id}}", // required
      "device_id": "xxxxxxx", // PayPal device ID, used in STC
      "specific_fields": {
        "callbacks": {
          "on_success": "https://example.com" // required for PayPal Wallet
        }
      }
    }
    

Widget payments

The DEUNA widget allows for two payment processes for the PayPal Widget in DEUNA, which are documented in this guide. Each process is started depending on the attributes of the user who makes the purchase.

  • Express process: Completes the payment in the shortest possible time.
  • General process: Allows different payment methods.

Express

The express flow is initialized when the widget detects a single payment method experience. This flow allows the user to complete their payment in the shortest possible time.

Once the user gives consent to save their PayPal account, the payment is made automatically and with a single click.

PayPal Redirect View

New or guest user with vaulting disabled

The guest flow is defined for new users, registered users who are not authenticated or when the merchant has disabled the Vaulting feature. In this case, the checkout payment process is initialized, where the user will enter their PayPal account to make the payment but it will not be saved.

If the user is new, then their data is registered so that they can authenticate themselves for a future purchase and save their PayPal account for future payments.

Express - Checkout

Authenticated user without PayPal account saved

If the user is logged in but does not have a PayPal account saved, then the vaulting payment process is initiated and the user is redirected to the PayPal site where they will make the payment and give their consent to save their account and use it for future purchases.

Authenticated user with PayPal account saved

If the user has authenticated and already has a PayPal account saved, then the payment is processed immediately because they have previously given their consent.

Express - One Click

General

The general flow is enabled when the widget detects an experience with multiple payment methods.

The user will have a greater role because they are able to manage their accounts, that is, they are able to add multiple accounts or delete one that they no longer use.

Authenticated users also have the possibility to select payment installments depending on whether the merchant requires or allows them.

New or guest user with vaulting disabled

When the user is an unauthenticated/new user or the merchant has disabled the Vaulting feature:

  1. The user clicks the PayPal button
  2. The checkout payment process initiates
  3. The user must authenticate themselves in PayPal and make the payment.

In this process, the account is not saved because there is no previous identification of the user, and their data will already be registered (if they are new) so that in a future purchase they will have the possibility of authenticating themselves and giving consent to save their PayPal account.

Payment Widget View - PayPal

Purchase example

Here is an example of a user making a purchase with PayPal in DEUNA:

Widget - New user

Authenticated user without PayPal accounts saved

When the user has authenticated and has no saved accounts:

  1. The vaulting payment process is initiated and the user is redirected to PayPal.
  2. The user makes the payment on PayPal's site.
  3. The user give their consent to save their account and/or use it for future transactions.

If the merchant requires payment installments, then the user will have to select them after authorizing the payment in PayPal.

Authenticated user with PayPal accounts saved

If the user is logged in and has saved PayPal accounts, then they can select any account to make the payment. The user can also delete any accounts or save a new one.

If the merchant offers payment installments, then these are displayed with the account selected for payment and if the user wants to use a new PayPal account, they will have to select the installments after authorizing the payment in PayPal.

Single account view

This is an example of a user with a single PayPal account in DEUNA:

Payment Widget View - Single PayPal account

Multiple accounts view

This is an example of a user with multiple PayPal accounts in DEUNA:

Payment Widget View - Multiple PayPal accounts

Purchase example

This is an example of a user making a purchase with PayPal in DEUNA:

Widget - One Click