Payment

Initialize payment¶

There are 2 supported payment procedures: - Checkout, where stripe provides the UI - "payment intent", the client must use stripe libraries to create its own UI.

You can call init payment endpoint only if the order is in status Placed or Payment. If the order is in status Payment you already have initialized a payment session. You will get the same response again, but you can't change the process - thus provided InitpaymentData is not taken into account. The URL of the payment endpoint:

PUT https://api.discover.swiss/test/market/v1/orders/{orderNumber}/payment

Web checkout¶

Using the checkout process of Stripe takes only two steps:

We create a session object on the backend and send it to Stripe. The session already contains all the required information for the payment.
checkout: the client uses the session Id to redirect the customer to the payment page. otherwise: Client creates its own form and sends the payment to stripe

You must send callbacks URL as part of the payment initialization in the body of the request. Stripe will redirect to those URL after payment done:

{
    "createCheckoutSession" : true,
    "successUrl": "https://my.server/payment_ok",
    "errorUrl": "https://my.server/payment_failed"
}

Payment endpoint returns session id required to redirect to Stripe:

{
  "initPaymentData":
  {
    "sessionId": "cs_test_Px7s8kZKHpYwRfrlETarNX1MQNwEBnixCmpaTzVfPl7stpBOfIaLGm6B",
    "clientSecret": "pi_5MDVV8EJdYTfvwwn0aqpMMMM_secret_5MDVVQLhbHPmtjty6x7sfSSSS",
    "paymentApiKey": "pk_test_BFvwJBVHlQbtxmftXMbF3gs00052KLsbTk",
    "result": true
  },
  "validationMessages": []
}

You can use Stripe's API to redirect the customer. Here is a sample for JavaScript: where the api-key which is part of the response above must be used (in the sample: pk_test_BFvwJBVHlQbtxmftXMbF3gs00052KLsbTk)

var stripe = window['Stripe']('pk_test_BFvwJBVHlQbtxmftXMbF3gs00052KLsbTk');
      stripe.redirectToCheckout({
        // Make the id field from the Checkout Session creation API response
        // available to this file, so you can provide it as parameter here
        // instead of the {{ CHECKOUT_SESSION_ID }} placeholder.
          sessionId: response.initPaymentData.sessionId
      }).then(function (result) {
         // do something
      }, function (result) {
        // using `result.error.message`.
        this.errorText = result.error.message;
      });

More information:

Checkout sample: https://stripe.com/docs/checkout/quickstart

Payment intents¶

This is the default.

{
    "createCheckoutSession" : false
}

Payment endpoint returns the client secret which is required to call the confirm CardPayment at Stripe:

{
    "initPaymentData": {
        "clientSecret": "pi_5MDVV8EJdYTfvwwn0aqpMMMM_secret_5MDVVQLhbHPmtjty6x7sfSSSS",
        "paymentApiKey": "pk_test_BFvwJBVHlQbtxmftXMbF3gs00052KLsbTk",
        "result": true
    },
    "validationMessages": []
}

Info

Stripe offers libraries that fit different ways of implementation depending on the client's preferences

In the sample app we used JavaScript and the Angular elements-wrapper https://github.com/AckerApple/stripe-angular

More information:

Payment methods¶

During the payment user might have 2 options to pay:

with new card information
with saved payment method

Payment methods are attached to the account and can be saved during the payment and deleted any time.

Save payment method¶

To save the payment method for future usage it is necessary to update the payment intent using the following endpoint:

PUT https://api.discover.swiss/test/market/v1/orders/{orderNumber}/paymentforfutureusage

In case decision changed and it is not necessary to save payment method anymore than call this endpoint:

DELETE https://api.discover.swiss/test/market/v1/orders/{orderNumber}/paymentforfutureusage

List payment method¶

It's possible to receive a list of saved payment methods in the account by calling the following endpoint:

GET https://api.discover.swiss/test/market/v1/paymentmethod

Remove payment method¶

Any of the payment method which is attached to the account can be removed from the list. That means that it won't be used for future payment.

To remove payment method use next endpoint:

DELETE https://api.discover.swiss/test/market/v1/paymentmethod/{id}

Use payment method¶

There are several approaches to confirm payment method:

Confirm on client side
Create payment method and confirm in one click

Confirm on client side¶

After regular payment initialization it is necessary to select saved payment method and then use Confirm payment intent by payment method approach using stripe api directly.

Create and confirm in one click¶

To use this approach it is necesssary to display the list of payment methods to the user to give a chance to chose desired payment method.

When the payment method was selected as one which will be used for future payment then it's necessary to create new payment intent with paymentMethodId

PUT https://api.discover.swiss/test/market/v1/orders/{orderNumber}/payment

{
    "CreateCheckoutSession": false,
    "PaymentMethodId": "pm_1MlxciEJdYTfvwwn1FNiGOhe" 
}

After this, the system will try to confirm the payment automatically. Response will contain Result property with the value true in case payment were succesfully confirmed, or false if the user interaction is necessary.

When the Result property is false - it is recommended to use client side approach to confirm payment with saved payment method or confirm payment with new payment method by providing card details.

Free orders¶

If an order has a total amount of 0, there is no payment needed and the fulfillment process starts immediately.
This is the case if you do not get any information about how to do the payment (no clientSecret)

Response

{
    "initPaymentData": {
        "result": true
    },
    "validationMessages": []
}

Pay¶

Once the payment successfully proceed payment the following things happen:

the client gets redirected to the success page which must be implemented by the client → the client-side ordering process has finished
stripe calls our server to confirm the payment → the fulfillment process gets started

Warning

We only reserve money of the customer's card. The charging of the cards occurs only if fulfillment has completed. On a partial fulfillment only the successfully processsed items are charged.

Stripe sends a checkout.session.completed event to the webhook we registered. This webhook is an endpoint by discover.swiss API which is not accessible to the public and is the same for all partners.

When the webhook is called, it does the following:

Validate the message and signature from Stripe
Save the payment id into the order and change the status to Paid. If this phase fails the webhook will return an error to Stripe. This will cause Stripe to repeat the webhook call.
Start the fulfillment and delivery processes. If something fails in this process the webhook still returns an OK response to Stripe.

Last update: December 5, 2023 07:22:51