Session server flow

How it works

For a Drop-in integration, you must implement the following parts:

Your payment server: sends the API request to create a payment session.

Your client app: shows the Drop-in UI where the shopper makes the payment. Drop-in uses the data from the API responses to handle the payment flow and additional actions on your client app.

Your webhook server: receives webhooks that include the outcome of each payment.

The parts of your integration work together to complete the payment flow:

The shopper goes to the checkout page.

Your server uses the shopper's country and currency information from your client to create a payment session.

Your client creates an instance of Drop-in using the session data from the server.

Drop-in shows the available payment methods, collects the shopper's payment details, handles additional actions, and presents the payment result to the shopper.

Your webhook server receives the notification containing the payment outcome.

If you are integrating these parts separately, you can start at the corresponding part of this integration guide:

Create a payment session

A payment session is a resource with information about a payment flow initiated by the shopper. This resource has all the information required to handle all the stages of a payment flow. You can configure this resource with information like available payment methods, payment amount, or line items.

To create a payment session, make a POST /sessions request, including:

Parameter name	Required	Description
`merchantAccount`		Your merchant account name.
`amount`		The `currency` and `value` of the payment, in minor units. This is used to filter the list of available payment methods to your shopper
`returnUrl`		The URL where the shopper should return to after a redirection
`reference`		Your unique reference for the payment. Minimum length: three characters.
`expiresAt`		The session expiry date in ISO8601 format, for example 2023-11-23T12:25:28Z, or 2023-05-27T20:25:28+08:00. When not specified, the expiry date is set to 1 hour after session creation. You cannot set the session expiry to more than 24 hours after session creation.
`countryCode`		The shopper's country/region. This is used to filter the list of available payment methods to your shopper.
`shopperReference`		Unique ID of customer in your system. Needed for displaying saved payment methods.
`transactionType`		default: `sale`, if set to `validation` will validate customers card.
`channel`		The platform where the payment is taking place. Use iOS or Android. Strongly recommended because this field is used for 3D Secure.
`shopperLocale`		The language that the payment methods will appear in. Set it to the shopper's language and country code. The default is en-US. Drop-in also uses this locale, if it is available.
`shopperEmail`		The shopper's email address. Strongly recommended because this field is used in a number of risk checks, and for 3D Secure.
`shopperReference`		Your reference to uniquely identify this shopper. Minimum length: three characters. Do not include personally identifiable information, for example name or email address. Strongly recommended because this field is used in a number of risk checks.

`returnUrl`

The URL where the shopper should return to after a redirection.

iOS: Use the custom URL scheme for your app. You also need to:

Add the return URL handler to your AppDelegate in your native iOS layer.

Configure the custom URL scheme in your Info.plist file.

iOS example: com.mydomain.plexycheckout://

Android: Use the combination of:

plexycheckout:// scheme
Your package name

Use the PlexyCheckout.instance.getReturnUrl() method to get the value, or hardcode the string.

Android example: plexycheckout://com.adyen.plexy_checkout_example

Format: Maximum 1024 characters.

💡

The URL must not include personally identifiable information (PII), for example name or email address.

Example request to create a session for a 10 EUR payment with iOS

curl https://api.plexypay.com/v2/sessions \
-H 'x-api-key: PLEXY_API_KEY' \
-H 'content-type: application/json' \
-d '{
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "amount": {
      "value": 1000,
      "currency": "EUR"
  },
  "returnUrl": "my-app://plexy",
  "reference": "YOUR_PAYMENT_REFERENCE",
  "countryCode": "KZ"
}'

The response contains:

sessionData: the payment session data.

id: a unique identifier for the session data.

The request body.

Pass the response to your client app, putting it in the sessionResponse object.

HTTP 201 /sessions response body

{
    "amount": {
        "currency": "EUR",
        "value": 1000
    },
    "countryCode": "NL",
    "expiresAt": "2021-08-24T13:35:16+02:00",
    "id": "CSD9CAC34EBAE225DD",
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "reference": "YOUR_PAYMENT_REFERENCE",
    "returnUrl": "my-app://plexy",
    "sessionData": "Ab02b4c.."
}

Session server flow

How it works#

Create a payment session#

returnUrl#

Example request to create a session for a 10 EUR payment with iOS#

HTTP 201 /sessions response body#

How it works

Create a payment session

`returnUrl`

Example request to create a session for a 10 EUR payment with iOS

HTTP 201 /sessions response body