API Endpoints

Sign-Up API

🚧

Notice

These APIs are under active development and are not subject to our breaking change policy.

Overview

MonetizeNow Self-Service APIs allow your customers to sign-up for service and establish a billing relationship with your company.

The Sign-Up API allows you to create a "shopping cart" session that can accommodate a multi-step sign-up process.

All sign-up sessions start with creating a new sign-up session by calling POST /api/selfService/signup to establish the session.

Once you have established a sign-up session which was not immediately finalized, you can perform any additional steps by calling PATCH /api/selfService/signup/cart_avkfeFeadLoj to update your session.

Quick Start

Here is an example of invoking the flow Sign-up with credit card and pay upfront which involves a multi-step flow to initialize the payment.

  1. Create a new sign-up session with the intent of collecting a payment method

    1. POST /api/selfService/signup

    2. {
  "action": "CREATE_WITH_PAYMENT_METHOD",
  "customer": {
    "accountName": "Acme Inc",
    "name": "John Doe",
    "email": "[email protected]",
    "billingAddress": {
      "line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94107",
      "country": "US"
    }
  },
  "billGroup": {
    "autoEmailInvoice": true,
    "collectInvoiceBalanceAutomatically": true
  },
  "quote": {
    "startDate": "2024-01-01",
    "offerings": [
      {
        "offeringId": "offr_EoqyNVChm1kwT",
        "rateId": "rate_aCTj2kwzyd0U5",
        "items": [{ "productId": "prod_a9sElJSR3TbyP", "quantity": 1 }]
      }
    ]
  }
}


      {
  "sessionId": "cart_zCrj2ABcd0U1",
  "customer": {
      "accountName": "Acme Inc",
      "name": "John Doe",
      "email": "[email protected]",
      "billingAddress": {
        "line1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94107",
        "country": "US"
      }
  },
  "billGroup": {
    "autoEmailInvoice": true,
    "collectInvoiceBalanceAutomatically": true
  },
  "paymentMethodInit": {
      "stripe": {
          "customerId": "cus_JKl2ABcd0U1",
          "setupIntentId": "seti_1P0qjFFlgb12q7bae7hXtrof",
          "clientSecret": "pk_test_51KnUJ0Flgb12q7babaqLUipiwMpUQLMvNy9hqpLkRsXzpvm8E7dSIrZ0cTnGHU8hoXNUsYSnj7C7PkkNk5t5ozW700JdvGcFy0"
      }
  },
  "quote": {
      "amountWithoutTax": 100,
      "amount": 100,
      "startDate": "2024-01-01",
      "offerings": [
          {
              "amountWithoutTax": 100,
              "amount": 100,
              "offeringId": "offr_EoqyNVChm1kwT",
              "rateId": "rate_aCTj2kwzyd0U5",
              "items": [
                  {
                      "productId": "prod_a9sElJSR3TbyP",
                      "quantity": 1,
                      "amountWithoutTax": 100,
                      "amount": 100
                  }
              ]
          }
      ]
  }
}

  2. Render the payment method form for your payment provider

    1. Use the paymentMethodInit returned from the sign-up response for all the data you need to continue the payment collection process. Make sure to configure this payment method so it is available for future offline use. Stripe reference

  3. Save the payment method to MonetizeNow

    1. PATCH /api/selfService/signup/cart_zCrj2ABcd0U1
    2. Tip: If this is your final update, set the action to FINALIZE to perform the update and finalization at the same time.
    3. {
  "action": "UPDATE",
  "paymentMethod": {
    "paymentMethodName": "visa",
    "paymentToken": "seti_1P0qjFFlgb12q7baCrgo9cfu",
  }
}

  4. Finalize the Session

    1. PATCH /api/selfService/signup/cart_zCrj2ABcd0U1
    2. {
  "action": "FINALIZE",
  "paymentMethod": {
    "paymentMethodName": "visa",
    "paymentToken": "seti_1P0qjFFlgb12q7baCrgo9cfu",
  }
}

The following has been completed

  1. Your customer exists and has an active subscription
  2. Your customer has an active payment method
  3. Depending on the rate and billGroup configuration, you will potentially have an invoice and a payment against the invoice
    1. Rates that bill in arrears will not generate an invoice until the end of the billing cycle

API Definition

The action parameter controls the behavior of the session.

ActionDescription
CREATE_AND_FINALIZESave and finalize the transaction.
Use this when you don't need to collect payment information.
CREATE_WITH_PAYMENT_METHODCreate a session and initialize everything needed for payment collection.
After you collect payment information via your Payment Gateway (such as Stripe), then you can finalize the transaction.
CREATE_IN_PENDINGSave the session and allow for additional configuration later.
Use this if you want to save and present pricing to your customer prior to finalization or if you have a verification process embedded into your sign-up flow.
INIT_PAYMENT_METHODUse this if you have a pending session but had not previously initialized the payment method collection process.
UPDATEUse this to make changes to any of the data provided on the session, such as change the products or add the newly created payment method.
FINALIZEUse this to finalize an existing session.
You can also provide any additional data points that you want to update at the same time as you finalize the transaction.
CANCELUse this to cancel an existing session.
ESTIMATEUse this if you want to show pricing without saving a session.

interface SignUpRequest {
  /**
   * Action to be performed
   */
  action:
    | "CREATE_AND_FINALIZE"
    | "CREATE_WITH_PAYMENT_METHOD"
    | "CREATE_IN_PENDING"
    | "INIT_PAYMENT_METHOD"
    | "UPDATE"
    | "FINALIZE"
    | "CANCEL"
    | "ESTIMATE";
  /**
   * Customer information - required for steps that create a quote
   */
  customer?: {
    /** Company name */
    accountName: string;
    /** Optional custom identifier */
    customId?: string | null;
    /** Individual name */
    name: string;
    /** Individual email */
    email: string;
    billingAddress?: {
      line1?: string;
      line2?: string;
      city?: string;
      state?: string;
      postalCode?: string;
      country?: string;
    };
  };
  /**
   * Optional settings to control billing options
   * If omitted, these will be populated based on your global tenant settings
   */
  billGroup?: {
    autoEmailInvoice?: boolean;
    collectInvoiceBalanceAutomatically?: boolean;
  };
  /**
   * Product information that the customer is purchasing
   * If provided on more than one request, subsequent requests will supersede prior requests
   */
  quote?: {
    /** Date to start service */
    startDate?: string;
    /** Optional custom identifier */
    customId?: string | null;
    /** Offerings (AKA bundles) being sold */
    offerings: {
      /** Id of offering */
      offeringId: string;
      /** Id of rate to use */
      rateId: string;
      /**
       * Quantity of each product
       * if not specified, defaults to the minimum quantity defined in the product catalog
       */
      items: {
        /** Id of product */
        productId: string;
        /** Quantity of product */
        quantity: number;
      }[];
    }[];
  };
  /**
   * Payment method to save to MonetizeNow
   */
  paymentMethod?: {
    /** Name of payment method, wil default if not provided */
    paymentMethodName?: string;
    /** Payment token from the payment provider */
    paymentToken: string;
  };
}


interface SignUpResponse {
  /** Session id that can be used for subsequent requests */
  sessionId: string;
  error: false;
  /** Action that was performed **/
  action:
    | "CREATE_AND_FINALIZE" /** Create and save everything, does not allow providing a payment method */
    | "CREATE_WITH_PAYMENT_METHOD" /** Create a quote and initialize payment method creation, returning data to complete payment method collection */
    | "CREATE_IN_PENDING" /** Create everything in a pending state that can be finalized */
    | "ADD_PAYMENT_METHOD" /** Save payment method returned from the Payment Gateway **/
    | "FINALIZE" /** Finalize any prior process that was not yet finalized */
    | "ESTIMATE" /** Provide quote pricing without saving anything, */;
  customer?: {
    accountId: string;
    accountName: string;
    contactId: string;
    contactName: string;
    contactEmail: string;
  };
  quote?: {
    id: string;
    amount: number;
    startDate: string;
    status: "DRAFT" | "PROCESSED";
    offerings: {
      offeringId: string;
      rateId: string;
      amount: number;
      items: {
        productId: string;
        quantity: number;
        amount: number;
      }[];
    }[];
    // ...some fields omitted for brevity...
  };
  invoice?: {
    id: string;
    amountWithoutTax: number;
    amount: number;
    items: {
      id: string;
    }[];
    // ...some fields omitted for brevity...
  },
  /**
   * Optionally returned after finalization if a payment was made
   */
  payment?: { id: string; amount: number; },
  /**
   * Bill group that was created
   */
  billGroup?: { id: string; },
  /**
   * Contract that was created
   */
  contract?: { id: string; },
  /**
   * Payment method initialization data returned from MonetizeNow to initialize the payment method
   */
	paymentMethodInit?: {
    stripe?: {
      customerId: string;
      setupIntentId: string;
      clientSecret: string;
      publicKey: string;
    };
  };
}

interface SignUpRequestError {
  /** Session id, if one was saved */
  sessionId: string;
  error: true;
  message: string;
}

Payment Method Collection

📘

Information

MonetizeNow currently supports Stripe, with additional payment gateways coming in the future.

Always use the payment providers hosted PCI compliant forms to ensure that customer credit card or bank information never pass through your server.

Once you establish a session and have initialized a payment method, MonetizeNow will create the customer in the Payment Gateway and will return everything required to embed a payment method form in your website.

You are in charge of embedding the payment gateway form in your website, and once the collection process is complete you will update the payment method on the session which will save it to MonetizeNow.

Payment method initialization response

Some parts of the response have been omitted from this example

{
  "sessionId": "cart_zCrj2ABcd0U1",
  "paymentMethodInit": {
      "stripe": {
          "customerId": "cus_JKl2ABcd0U1",
          "setupIntentId": "seti_1P0qjFFlgb12q7bae7hXtrof",
          "clientSecret": "pk_test_51KnUJ0Flgb12q7babaqLUipiwMpUQLMvNy9hqpLkRsXzpvm8E7dSIrZ0cTnGHU8hoXNUsYSnj7C7PkkNk5t5ozW700JdvGcFy0"
      }
  },
}

Collect payment information from your customer

Use the paymentMethodInit returned from the sign-up response for all the data you need to continue the payment collection process. Make sure to configure this payment method so it is available for future offline use. Stripe reference

Save the payment method to MonetizeNow

Save the payment token back to MonetizeNow

PATCH /api/selfService/signup/cart_zCrj2ABcd0U1

{
  "action": "UPDATE",
  "paymentMethod": {
    "paymentMethodName": "visa",
    "paymentToken": "seti_1P0qjFFlgb12q7baCrgo9cfu",
  }
}

Sign-Up - Pricing Calculations

📘

Information

If you have a tax engine configured, prices will not include tax calculations until you finalize the sign-up session.

It is a best-practice to allow MonetizeNow to own the pricing calculations that your present to your customers during the sign-up process.

You can obtain product pricing calculations by creating a sign-up session, and you can use the ESTIMATE action if you don't yet want to save the actual session.

TIP If you have simple pricing presented on your website, then you can calculate this in your browser without needing to make an API request to MonetizeNow until you are ready to save your session.

Trials

📘

Coming Soon

We are working on our trial documentation.