Documentation
LoginSandbox
Start typing to search…

B2C Subscriptions

This guide outlines the steps to integrate a B2C subscription work flow.

To attain a full B2C subscription workflow within Solvimon's platform, it's as simple as following five essential steps:

  1. Create customer
  2. Initialize subscription and schedule
  3. Integrate invoice webhook
  4. Integrate payment webhook
  5. Update subscription

Step-by-step Workflow

1. Create Customer

Endpoint URL

POST https://api.solvimon.com/v1/customers

Request Body

{
  "reference": "cust_1",
  "type": "INDIVIDUAL",
  "individual": {
    "name": {
      "first_name": "John",
      "last_name": "Doe"
    },
    "residential_address": {
      "country": "NL"
    }
  },
  "email": "[email protected]",
  "custom_fields": [
    {
      "reference": "PAYMENT_GATEWAY:ADYEN:SHOPPER_REFERENCE",
      "value": "cust_1"
    }
  ]
}
Request Body Explanation
  • reference: The reference of the customer.
  • custom_fields.referenceand custom_fields.value: The key-value pair to indicate the customer reference in the payment service provider's (PSP) system.
    • reference: The key for the desired PSP integration.
      • PAYMENT_GATEWAY:ADYEN:SHOPPER_REFERENCE: Use this for the Adyen integration.
      • PAYMENT_GATEWAY:STRIPE:CUSTOMER_ID: Use this for Stripe integration.
    • value: The customer reference in the PSP system.
📘

Customers API

Please see the customers API reference for more information.

2. Initialize Subscription and Schedule

Endpoint URL

POST https://api.solvimon.com/v1/pricing-plan-subscriptions/init

Request Body

{
  "pricing_plan_subscription": {
    "reference": "cust_1_monthly_eur_20240915",
    "customer_reference": "cust_1",
    "billing_entity_reference": "entity_nl",
    "billing_time": "EXACT",
    "billing_currency": "EUR"
  },
  "pricing_plan_schedules": [
    {
      "pricing_plan_version_selector": {
        "pricing_plan_reference": "monthly_eur"
      },
      "start_at": "2024-09-15T00:00:00Z",
      "end_at": "2025-09-15T00:00:00Z"
    }
  ],
  "first_payment": {
    "payment_acceptor_reference": "adyen_b2c_subscriptions",
    "external_reference": "N9KKLBTLMJS8F6V5",
    "amount": {
      "quantity": "9.99",
      "currency": "EUR"
    },
    "result": "AUTHORIZED"
  },
  "payment_method": {
    "type": "CARD",
    "card": {
      "brand": "VISA",
      "last_four_digits": "1111"
    },
    "integration_reference": "adyen",
    "integration_details": {
      "payment_gateway_variant": "ADYEN",
      "adyen": {
        "recurring_detail_reference": "DB4FCTVZ45F2MV65"
      }
    }
  }
}
Request Body Explanation
  • pricing_plan_subscription:
    • reference: The reference of the subscription.
    • customer_reference: The reference of the customer to create this subscription for.
    • billing_entity_reference: The reference of the billing entity to create this subscription for.
    • billing_time: The billing time of the subscription. For B2C, it's highly recommended to use the EXACT variant, so that the billing will occur exactly one billing_period (e.g. the 15th of every month) after the start date.
    • billing_currency: The billing currency of the subscription. The currency is used for the invoices generated by this subscription.
👍

Default Subscription Billing Terms

Alternatively, instead of setting the subscription's billing terms manually for every subscription, you could also set default subscription terms. These terms will then be used by default if no billing terms are provided when creating a subscription.

  • pricing_plan_schedules:
    • pricing_plan_version_selector: Set the reference of the pricing plan that must be used for the schedule. By default the latest ACTIVE version will be taken of the pricing plan.
    • start_at: Set this date to the date when your customer has paid for the activation of the subscription.
  • first_payment: For B2C, when the first payment is done outside the Solvimon platform (like when the payment of the subscription was part of an other payment), the details of the first payment that the customer made can be supplied. This will result in the first invoice automatically being moved to "FINAL" and "paid".
    • external_reference: This is the reference of the payment attempt made at the PSP.
  • payment_method: For B2C, the payment method used for the invoices generated by this subscription.
    • integration_reference: The reference to the Payment Service Providers integration in Solvimon.
    • integration_details: This is where you can provide the reference of the payment method in the PSP. This will be used to make a payment attempt for subsequent invoices.
📘

Init Subscription API

Please see the Initialize Subscription and Schedule API reference for more information.

3. Integrate Invoice Webhook

You can configure a webhook to receive the callback once an invoice is FINAL or updated to paid.

4. Integrate Payment Webhook

You can configure a webhook to receive the callback once a payment has been created and what its result is. You could also use a single webhook to achieve 3 and 4.

📘

Configuring Webhooks

For more information on how to configure a webhook in the Solvimon platform, please read the Webhook guide.

5. Update Subscription

You will be able to update the subscription after it has been created. A typical use case for a B2C workflow would be to set or update the end date (end_at) of a schedule, and a second schedule for a new / other pricing plan, or update the payment method for the subscription. The payment method is what will be used to make a payment at the PSP for the invoices of the subscription.

Test Out Setting Up a B2C Subscription

We've created a recipe for you to test out the workflow as described above.

Updated 9 months ago

What’s Next