Advanced server flow

How it works

For a integration, you must implement the following parts:

Your payment server: sends the API requests to get available payment methods, make a payment, and send additional payment details.

Your client app: shows the the Component/Drop-in UI where the shopper makes the payment. The Component/Drop-id uses the data from the API responses fto 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 screen.

Your server uses the shopper's country and currency information from your client to get available payment methods.

The Component collects the shopper's payment details, handles the additional action, and shows the payment result to the shopper.

Your webhook server receives the notification containing the payment outcome.

Get available payment methods

When your shopper is ready to pay, get a list of the available payment methods based on their country, device, and the payment amount.

From your server, make a POST /paymentMethods request, providing the following parameters. While most parameters are optional, we recommend that you include them because Plexy uses these to tailor the list of payment methods for your shopper.

We use the optional parameters to tailor the list of available payment methods to your shopper.

Call startDropin to show the Drop-in, passing the following:

Parameter name	Required	Description
`merchantAccount`		Your merchant account name.
`amount`		The `currency` of the payment and its `value` in minor units.
`channel`		The platform where the payment is taking place. For example, when you set this to iOS, Plexy returns only the payment methods available for iOS.
`countryCode`		The shopper's country/region. Plexy returns only the payment methods available in this country.
`shopperLocale`		By default, the `shopperlocale` is set to en-US. To change the language, set this to the shopper's language and country code. Your client app also uses this locale.

For example, to get the available payment methods for a shopper in the Netherlands, for a payment of EUR 10:

curl https://api.plexypay.com/v2/paymentMethods \
-H 'x-api-key: PLEXY_API_KEY' \
-H 'content-type: application/json' \
-d '{
  "merchantAccount": "PLEXY_MERCHANT_ACCOUNT",
  "countryCode": "NL",
  "amount": {
    "currency": "EUR",
    "value": 1000
  },
  "channel": "Android",
  "shopperLocale": "nl-NL"
}'

Make a payment

When the shopper selects the Pay button or chooses to pay with a payment method that requires a redirection, Drop-in calls onSubmit.

From your server, make a POST /payments request specifying:

Parameter name	Required	Description
`merchantAccount`		Your merchant account name.
`amount`		The `currency` of the payment and its `value` in minor units.
`reference`		Your unique reference for this payment.
`paymentMethod`		The payment method from the `payload` of the `onSubmit` event from your client app.
`returnUrl`		The URL where the shopper should return to after a redirection.

For the following cases, you must include additional parameters in your request:

Integrating some payment methods. For more information, go to payment method integration guides.

Using our risk management features. For more information, see Required risk fields.

Native 3D Secure 2 authentication.

Tokenizing your shopper's payment details or making recurring payments.

Example of a payment request for EUR 10

curl https://api.plexypay.com/v2/payments \
-H 'x-api-key: PLEXY_API_KEY' \
-H 'content-type: application/json' \
-d '{
  "amount":{
    "currency":"EUR",
    "value":1000
  },
  "reference":"YOUR_ORDER_NUMBER",
  "paymentMethod":{hint:paymentMethod field of an object passed from your client app}STATE_DATA{/hint},
  "returnUrl":"my-app://plexy",
  "merchantAccount":"PLEXY_MERCHANT_ACCOUNT"
}'

Example response redirect payment method

{
  "resultCode": "RedirectShopper",
  "action": {
    "paymentMethodType": "ideal",
    "url": "https://sdk.plexypay.com/checkoutshopper/checkoutPaymentRedirect?redirectData=X6Xtf...",
    "method": "GET",
    "type": "redirect"
  }
}

Map the response to one of the following PaymentEvent objects:

Type	Description
`Finished`	The payment is finished.
`Action`	An additional action is required. Drop-in automatically handles the additional action.
`Error`	An error has occured.

Pass the object to your client. The onSubmit callback expects it.

Errors

If an error occurs, you get one of the following error codes:

Error code	Description	Action to take
canceledByShopper	The shopper canceled the payment.	Take the shopper back to the checkout page.
notSupported	The payment method isn't supported by the shopper's device.	Tell the shopper that the payment method isn't supported by their device.
noClientKey	No `clientKey` configured.	Tell the shopper that an error occurred.
noPayment	No `payment` information configured.	Tell the shopper that an error occurred.
invalidPaymentMethods	Can't parse the `paymentMethods` list, or the list is empty.	Tell the shopper that an error occurred.
noPaymentMethod	Can't find the selected payment method.	Tell the shopper that their selected payment method is currently unavailable.

Advanced server flow

How it works#

Get available payment methods#

Make a payment#

Example of a payment request for EUR 10#

Example response redirect payment method#

Errors#

How it works

Get available payment methods

Make a payment

Example of a payment request for EUR 10

Example response redirect payment method

Errors