Guides
Start typing to search…

Payments with Plugsurfing's PSP

Note: The information on this page is only applicable when Plugsurfing is the acting payment provider (see Payment integration options for more details).

Plugsurfing is using Stripe as the PSP (Payment Service Provider).

🚧

This functionality is being updated and some details below are subject to change.

Create a payment method

To create a Stripe credit card payment method there are a number of steps involved. This includes integrating with both Stripe and Plugsurfing to successfully complete this flow.

These are the steps involved in a payment method setup:

sequenceDiagram
    participant EMP App
    participant EMP BE
    participant Drive API
    participant Stripe

    note over EMP App:1. Retrieve publishable API key, unless it's cached
    EMP App->>EMP BE:GET - publishable API key
    activate EMP App
    activate EMP BE
    note over EMP BE:Retrieve publishable API key, unless it's cached
    EMP BE->>Drive API:GET - publishable API key
    activate Drive API
    Drive API-->>EMP BE:return
    deactivate Drive API
    EMP BE-->>EMP App:return
    deactivate EMP BE
    deactivate EMP App

    note over EMP App:2. Create SetupIntent to be used with Stripe client-side library

    EMP App->>EMP BE: GET - Create SetupIntent
    activate EMP App
    activate EMP BE
    EMP BE->>Drive API:GET - Create SetupIntent
    activate Drive API
    Drive API-->>EMP BE:return
    deactivate Drive API
    EMP BE-->>EMP App:return
    deactivate EMP BE
    deactivate EMP App

    note over EMP App:3.Use Stripe client-side library with the publishable API key

    activate EMP App
    EMP App->>EMP App: Collect PaymentMethod details
    EMP App->>Stripe: Confirm SetupIntent with client-secret
    activate Stripe
    Stripe-->>EMP App:return
    deactivate EMP App
    deactivate Stripe

    note over EMP App:4.Associate the newly created PaymentMethod.id to a user

    EMP App->>EMP BE: POST - Create credit-card on user with PaymentMethod id
    activate EMP App
    activate EMP BE
    EMP BE->>Drive API:GET - Create credit-card on user with PaymentMethod id
    activate Drive API
    Drive API-->>EMP BE:return
    deactivate Drive API
    EMP BE-->>EMP App:return
    deactivate EMP BE
    deactivate EMP App
  1. Get a publishable API key to be used towards the Stripe SDK. This is what makes Stripe identify the correct Stripe Platform, Meaning a Plugsurfing managed platform.
  2. Get a Stripe SetupIntent via Plugsurfing.
  3. Use Stripe client-side library to:
    1. Collect the Stripe PaymentMethod details.
    2. Confirm the SetupIntent with the PaymentMethod details, client-secret, and the publishable API key.
  4. Post the PaymentMethod id with the associated user to Plugsurfing in order to finalize the payment method setup.

EU regulation: Co-badged cards compliance

Some payment cards support co-badging, meaning they can be processed through multiple networks (e.g., Visa, Cartes Bancaires).
To comply with EU regulations, your app must allow users to select their preferred network when creating a payment method.

Stripe documentation:

Note:
Plugsurfing platform doesn't allow updating their card network of an existing credit-card. If a user wants to use another network, they would need to create a new credit-card payment-option.

Publishable API key

The Stripe publishable API key is a client-side identifier provided by Stripe that is used to interact with Stripe's APIs securely from the frontend of your application.
In the case of libraries like the React Native Stripe library, the publishable key is essential for initializing the library and enabling your app to create and manage payment elements, such as payment forms.

Plugsurfing or Stripe may at any time roll the publishable API key.
Below are some important implementation recommendations to ensure seamless integration.

  • To avoid unnecessary downtime, when Stripe rejects a request which includes the publishable API key (with an HTTP 401 Unauthorized), the EMP app needs to refresh the key by invoking the relevant Drive API endpoint.
  • For optimal performance, we recommend caching the Stripe publishable API key. The publishable key is static and does not change frequently, so re-fetching it on every request can add unnecessary latency to your application.

Successful payments

When a payment is successful the session will be in this type of state:
sessionStatus will be COMPLETE balance_status will be PAID balanceAmountMinor will be 0

Failed payments

When a payment fails, the session balance status and amount will reflect if the session was paid or not.

Sometimes there can be a partially paid session.
Ex: The session price is €40. We reserve €30, we then capture the reserved $30, but we are unable to capture the outstanding €10.

Plugsurfing will automatically retry unpaid sessions up to 7 days.

EMP initiated retry

The EMP can retry a failed payment using the appropriate endpoint. However, in most cases, payment failures are not caused by technical errors but by issues such as insufficient funds, expired cards, or similar problems. Frequent retries are unlikely to resolve these issues. Instead, it is recommended to notify the end customer to ensure they have sufficient funds or to use a different payment method before attempting the payment again.

3DS Authentication

Even when the payment is labeled as an "off session" payment, the banks will sometimes trigger a 3DS authentication challenge before they accept the payment. This is also a cause of session payment failures since when the session payment takes place, there is no customer available to perform the authentication.

When this happens, the EMP needs to bring the customer back to the app, retry the payment, and if the bank again triggers a 3DS challenge, the EMP must have support for bringing the customer through a 3DS authentication flow.

Plugsurfing will return a Stripe client secret which the EMP must use when initiating the 3DS flow. Consult the Stripe documentation for more information.

Debt

What do we mean by the term debt? If one looks at for example the session balanceStatusthere is an attribute named DEBT. Debt means the customer have not paid the session in full and have a negative balance. The balance is extracted from the session attribute balanceAmountMinor.

What are the customer consequences of having debt?

The customer will be blocked from starting yet another session until the outstanding amount is fully paid.

Receipts

When the payment succeeds. There will be a session receipt available.

Refunds

Refunds will be handled manually between the EMP support and the Plugsurfing support. Plugsurfing are able to do as many (partial) refunds as may be needed. Refunds won't affect the balanceAmountMinor.
When a session is refunded, even if partially refunded, the balanceStatus will be in state REFUND. This is how the Plugsurfing platform currently handles this. Since refunds are a manual process, the details, remaining refundable amount, can be sorted out between humans.

Updated 30 days ago