Payment Methods API

MikroCloud never stores any payment information on its servers. Instead, we use Stripe to securely store your payment information. The APIs below are mostly wrappers that allow the integration of the Stripe.js workflow.

In general, the following steps are required to create a payment method:

Create a Setup Intent
Consume the Setup Intent client-side using Stripe.js
Save the payment method

You may use the id of an existing payment method and send it to the Save a Payment Method endpoint to set it as the default payment method.

All the endpoints in this section require the user to have a billing account. If the user does not have a billing account, a no account error will be returned.

The Setup Intent Object

Name
id
Type
string
Description
Unique identifier for the setup intent object.
Name
publishable_key
Type
string
Description
This is a publishable secret that can be safely used with Stripe.js to complete payment setup from the frontend.
Name
client_secret
Type
enum
Description
The client secret of this Setup Intent. Used for client-side retrieval using a publishable key.
The client secret can be used to complete payment setup from your frontend. It should not be stored, logged, or exposed to anyone other than the user. Make sure that you have TLS enabled on any page that includes the client secret.
Name
status
Type
enum
Description
Status, one of requires_payment_method, requires_confirmation, requires_action, processing, canceled, or succeeded.
Name
created_at
Type
datetime
Description
Time at which the object was created. Returns a datetime string in the format YYYY-MM-DD HH:MM:SS using the timezone claim of the JWT access token. Defaults to UTC.

The Tax ID Object

{
    "id": "seti_1NqmXCCVnXOZCtu9R88qcSTk",
    "publishable_key": "pk_test_4eC39HqLyjWDarjtzd...",
    "client_secret": "seti_1NqmXCCVnXOZCtu9R88qcST...",
    "status": "requires_payment_method",
    "created_at": "2023-09-16 00:38:54"
}

POSTv1/account/setup-intent

Create a Setup Intent

Requires the account:write scope.

Parameters

No parameters are required for this endpoint.

Example request

curl -X POST https://api.mikrocloud.com/v1/account/setup-intent \
-H "Authorization: Bearer {token}"

Example response

{
    "id": "seti_1NqmXCCVnXOZCtu9R88qcSTk",
    "publishable_key": "pk_test_4eC39HqLyjWDarjtzd...",
    "client_secret": "seti_1NqmXCCVnXOZCtu9R88qcST...",
    "status": "requires_payment_method",
    "created_at": "2023-09-16 00:38:54"
}

Consume a Setup Intent

Below is a very basic example of how to consume a setup intent using Stripe.js. Once the card has been verified, the payment method can be saved using the Save a Payment Method.

In the example below {{publishable_key}} and {{client_secret}} should be replaced with the values returned from the Setup Intent endpoint.

Never log, store, or expose the client_secret to anyone other than the user. Only ever use the client_secret on a page that has TLS enabled.

index.html

<div id="card-element"></div>

<button id="card-button" data-secret="{{client_secret}}">
    Add Payment Method
</button>

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

<script>
    const stripe = Stripe('{{publishable_key}}');

    const elements = stripe.elements();
    const cardElement = elements.create('card');

    cardElement.mount('#card-element');

    const cardButton = document.getElementById('card-button');
    const clientSecret = cardButton.dataset.secret;

    cardButton.addEventListener('click', async (e) => {
        const {setupIntent, error} = await stripe.confirmCardSetup(
            clientSecret, {
                payment_method: {
                    card: cardElement,
                }
            }
        );

        if (error) {
            // Display "error.message" to the user...
        } else {
            // The card has been verified successfully...
            // Call the save payment method endpoint here...
        }
    });
</script>

The Payment Method Object

Name
id
Type
string
Description
Unique identifier for the payment method object.
Name
brand
Type
enum
Description
Card brand. Can be amex, diners, discover, eftpos_au, jcb, mastercard, unionpay, visa, or unknown.
Name
last4
Type
string
Description
The last four digits of the card.
Name
exp_month
Type
int
Description
Two-digit number representing the card's expiration month.
Name
exp_year
Type
int
Description
Four-digit number representing the card's expiration year.
Name
created_at
Type
datetime
Description
Time at which the object was created. Returns a datetime string in the format YYYY-MM-DD HH:MM:SS using the timezone claim of the JWT access token. Defaults to UTC.

The Tax ID Object

{
    "id": "card_1Nqn8bCVnXOZCtu949NkeQ97",
    "brand": "visa",
    "last4": "4242",
    "exp_month": 4,
    "exp_year": 2024,
    "created_at": "2023-09-16 01:17:33"
}

POSTv1/account/payment-methods

Save a Payment Method

Requires the account:write scope.

Parameters

Name
id
Type
string
Required
Required
Description
Unique identifier for the payment method object.

You may use the id of an existing payment method to set it as the default payment method.

Example request

curl -X POST https://api.mikrocloud.com/v1/account/tax \
-H "Authorization: Bearer {token}" \
-d '{"id": "card_1Nqn8bCVnXOZCtu949NkeQ97"}'

Example response

{
    "id": "card_1Nqn8bCVnXOZCtu949NkeQ97",
    "brand": "visa",
    "last4": "4242",
    "exp_month": 4,
    "exp_year": 2024,
    "created_at": "2023-09-16 01:17:33"
}

GETv1/account/payment-methods

Retrieve Payment Methods

Requires the account:read scope.

Parameters

No parameters are required for this endpoint.

Example request

curl -G https://api.mikrocloud.com/v1/account/payment-methods \
-H "Authorization: Bearer {token}"

Example response

[
    {
        "id": "card_1Nqn8bCVnXOZCtu949NkeQ97",
        "brand": "visa",
        "last4": "4242",
        "exp_month": 4,
        "exp_year": 2024,
        "created_at": "2023-09-16 01:17:33"
    }
]

DELETEv1/account/payment-methods/{id}

Delete a Payment Method

Requires the account:write scope.

Parameters

Name
id
Type
string
Description
Unique identifier for the payment method object.

It is not possible to delete the default / only payment method. If you wish to delete the a payment method, you must first set another payment method as the default.

Example request

curl -X DELETE https://api.mikrocloud.com/v1/account/payment-methods/{id} \
-H "Authorization: Bearer {token}"