It's now time to finish the checkout process by finalizing the order with a payment. You can close the order by choosing one of the payment methods described below:

  1. Stripe gateway with their Elements form, which process credit cards data and eventually updates the order status based on the result of the payment process.
  2. No-Payment flow, which always marks the order as confirmed without actually requiring any synchronous payment to be processed. Keep in mind this is valid only if you have a Merchant Partner agreement with Musement.

To know more about your current API plan or apply for a Merchant Partner agreement with Musement, you can contact [email protected]

Stripe

Once the order created, you can connect with our Stripe account to host the payment on your platform (Musement remaining merchant of records).

1. Implement your stripe payment on the "client side”

To support 3DS2 we updated the Stripe script to version 3.
We suggest you to use Stripe Elements to collect credit card information because other solutions are going to be deprecated by Stripe in the near future.

For more information see Stripe doc: https://stripe.com/docs/payments/accept-a-payment-synchronously#build-the-payment-form

Step A: Load Stripe script

<script src="https://js.stripe.com/v3/"></script>

Step B: Create and mount the form

in your HTML code:

// optional
<input id="cardholder-name" type="text">

<!-- placeholder for Elements -->
<div id="card-element"></div>

// optional
<div id="card-errors" role="alert"></div>

// optional
<button id="card-button">Submit Payment</button>

in your JS code:

var stripe = window.Stripe(public_stripe_api_key);
var elements = stripe.elements({locale: locale});

var cardElement = elements.create('card');
cardElement.mount('#card-element');

as public_stripe_api_key you can use Musement public Stripe API key for testing: pk_test_tulgJ5FZniT3DGCgwzxA3uKo.

For production environment, you can use: pk_live_ksevD0pPgdOMpQROpAhWHdYE

the params locale is optional but we recommend to use it.
locale must be a two characters long string in lower case (ex. 'en')

2. Get paymentMethod id on subimt form

Instead of get a Stripe token, now we need the Stripe PaymentMethod id to proceed in the flow.

var cardholderName = document.getElementById('cardholder-name');
var cardButton = document.getElementById('card-button');

cardButton.addEventListener('click', function(ev) {
  stripe.createPaymentMethod('card', cardElement, {
    billing_details: {name: cardholderName.value}
  }).then(function(result) {
    if (result.error) {
      // Show error in payment form
    } else {
        // Call Musement payments API
      // sending result.paymentMethod.id
    }
  });
});

Using cardButton is optional if you are using your own CTA.

When user submits credit card data javascript should proceed to this line - now you have the paymentMethod id (result.paymentMethod.id)

3. Call Musement Payments API

Here more information about the payment endpoint:
https://api-docs.musement.com/reference#split

POST with following payload:

curl -X POST \
  https://api.musement.com/api/v3/payments/split/payment \
  -H 'Accept: application/json, application/xml' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "order_uuid": "valid-order-uuid-here",
    "stripe_token": "stripe_payment_method_id_here"
}
'

Response status 200:

3DS NOT required:

Order is paid and the flow is finished!

3DS required:

in the response you receive an object called 3d_secure with the following structure:

{
    "3d_secure": {
    "type": "USE_STRIPE_SDK",
    "payment_intent_client_secret": "stripe_payment_intent_client"
  }
}

In order to complete the flow you need to handle the last step with the payment_intent_client you have just received calling our complete_3d_secure endpoint

stripe.handleCardAction('stripe_payment_intent_client')
    .then(handleResult)

function handleResult(result) {
    if (result.error) {
    // handle error
    
  } else {
    // Call Musement complete_3d_secure API
    // sending result.paymentIntent.id
    
  }
}
curl -X POST \
 https://api.musement.com/api/v3/payments/split/complete_3d_secure \
  -H 'Accept: application/json, application/xml' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "order_uuid": "valid-order-uuid-here",
    "payment_intent_id": "stripe_payment_intent_id_here"
}

if response status is 200, order is paid and the flow is finished.

Other responses:
please refer to response error codes in our API swagger for any details.

Apple Pay

Our integration with Apple Pay is done via Stripe. There is no big difference from the normal payment flow.

🚧

Domain verification

To use Apple Pay on a website you have to verify the domain, also test domain must be verified one. Please get in touch with you account to proceed with the domain verification.

First you have to check if the device of the customer supports Apple Pay.

To do this you must call

Stripe.applePay.checkAvailability(stripeResponseHandler);

In stripeResponseHandler callback you can insert your business logic and perform all needed actions.

Usually in this method the “Pay with Apple Pay” button is shown or hidden depending on the device support for Apple Pay.

function stripeResponseHandler(available) {
  // If Apple Pay is available, display the button on your checkout page
  if (available) {
    document.getElementById('apple-pay-button').style.display = 'block';
  }
}

More details here: https://stripe.com/docs/stripe-js/v2#applepay-checkavailability

If the device supports Apple Pay you must then call window.Stripe.applePay.buildSession() method to get the token needed by Musement’s APIs.

The minimum payload is

Stripe.applePay.buildSession({
  countryCode: 'US',
  currencyCode: 'USD',
  total: {
    label: 'The fantastic travel website',
    amount: '19.99'
  }
}, onSuccessHandler, onErrorHandler);
  • currencyCode use the same value you passed in X-Musement-Currency when you created the order using POST /orders

  • amount is the total_price.value of the Order model returned by POST /orders

For more fields and details please refer to the official doc https://stripe.com/docs/stripe-js/v2#applepay-buildsession

Pay the order using the standard payment endpoint the only thing you have to remember is to set is_apple_pay to true.

curl -X POST \
  https://api-origin.musement.com/api/v3/orders \
  -H 'Content-Type: application/json' \
  -d '{
  "order_uuid" : "order.uuid in the response of POST /orders",
  "stripe_token" : "stripe_token_generated_at_step_2",
  "is_apple_pay" : true
}'

REFERENCES

No-Payment

The No-payment flow allows you to close an order without making a payment.
You need a special API grant to use this flow.

curl -X POST \
  https://api.musement.com/api/v3/payments/no/payment \
  -H 'Authorization: Bearer hereAValidBearer' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "uuid" : "efbc64fa-ab9f-40aa-84db-590beed8350d"
}'

📘

Getting access to no-payment

Please contact your account manager to have your account granted the proper rights to use no-payment.