Create Subscription Message Sequences
Diagrams and steps for creating and managing a recurring payment for a service.
Prerequisites
A subscription requires one or more plans. See Create Plan.
Each plan requires a product of type service. See Create Product.
Note
Subscriptions automatically create draft invoices during each billing cycle. Invoice payments are processed immediately when simultaneous invoice is set to true. When simultaneous invoice is set to false or not defined, invoice payments are processed 1 hour after invoices are created.
Create a Subscription
Subscription with Automatic Capture of Card Payment
This diagram shows the sequence of events when a subscription is created from a card. In this example, installment payments are made in advance, and authorization and capture occur simultaneously. The fraud check illustrated here is part of all card payment requests.
The client sends a Create Subscription request to Rapyd.
Rapyd sends a response with details of the subscription to the client. The status of the subscription is set to active.
Rapyd sends Webhook - Subscription Created to the client.
Rapyd sends Webhook - New Cycle Started to the client.
Rapyd sends Webhook - Invoice Created to the client. The status of the invoice is set to draft.
Rapyd sends Webhook - Invoice Finalized to the client. The status of the invoice is set to open.
Rapyd requests a fraud check and payment from the card network.
The card network approves the card and transfers the funds to Rapyd.
Rapyd credits the client wallet and sends Webhook - Payment Completed to the client. The status of the payment is set to CLO (closed).
Rapyd sends Webhook - Payment Succeeded to the client.
Rapyd sends Webhook - Invoice Payment Created to the client.
Rapyd sends Webhook - Invoice Payment Succeeded to the client. The status of the invoice is set to paid.
Subscription with Card 3DS Authentication
This diagram shows the sequence of events when a subscription is created from a card that requires 3DS authentication. After the customer passes 3DS authentication, the individual recurring payments are automatically processed without additional authentication.
The client sends a Create Subscription request to Rapyd.
Rapyd sends a response with details of the subscription to the client. The status of the subscription is set to active.
Rapyd sends Webhook - Subscription Created to the client.
Rapyd sends Webhook - New Cycle Started to the client.
Rapyd sends Webhook - Invoice Created to the client. The status of the invoice is set to draft.
Rapyd sends Webhook - Invoice Finalized to the client. The status of the invoice is set to open.
Rapyd sends Webhook - Payment Succeeded containing the URL of the 3DS authenticator to the client. The status of the payment is set to ACT (active).
The client sends the URL of the 3DS authentication site to the customer.
The customer successfully completes the authentication requirements.
The 3DS authentication site notifies Rapyd that the customer is authenticated.
Rapyd requests payment from the card network.
The card network approves and transfers the funds to Rapyd.
Rapyd credits the client wallet and sends Webhook - Payment Completed to the client. The status of the payment is set to CLO (closed).
Rapyd sends Webhook - Invoice Payment Created to the client.
Rapyd sends Webhook - Invoice Payment Succeeded to the client. The status of the invoice is set to paid.
Subscription with a Trial Period
These diagrams show the sequence of events when a subscription is created with a trial period. You can define a trial period in a plan object attached to the subscription, or by setting trial_period_days in the Create Subscription request.
During Subscription Creation and Trial Period
The client sends a Create Subscription request to Rapyd.
Rapyd sends a response with details of the subscription to the client. The status of the subscription is set to trialing.
Rapyd sends Webhook - Subscription Created to the client.
Rapyd sends Webhook - New Cycle Started to the client.
Rapyd sends Webhook - Invoice Created to the client. The status of the invoice is set to draft.
Rapyd sends Webhook - Invoice Payment Succeeded to the client. The status of the invoice is set to paid, and the amount is set to zero.
Three days before the end of the trial period, Rapyd sends Webhook - Trial Nearing End to the client.
When Trial Period Ends
At the end of the trial period, Rapyd sends Webhook - New Cycle Started to the client. The status of the subscription is set to active.
Rapyd sends Webhook - Invoice Created to the client. The status of the invoice is set to draft.
Rapyd sends Webhook - Invoice Finalized to the client. The status of the invoice is set to open.
Rapyd requests a fraud check and payment from the card network.
The card network approves the card and transfers the funds to Rapyd.
Rapyd credits the client wallet and sends Webhook - Payment Completed to the client. The status of the payment is set to CLO (closed).
Rapyd sends Webhook - Payment Succeeded to the client.
Rapyd sends Invoice Payment Created Webhook to the client.
Rapyd sends Webhook - Invoice Payment Succeeded to the client. The status of the invoice is set to paid.
During Subscription Creation and Trial Period - Payment Failed
This diagram shows the sequence of events when the first installment payment for a new subscription fails. A payment can fail for many reasons, for example, the card has been blocked or does not have sufficient funds.
The client sends a Create Subscription request to Rapyd.
Rapyd sends a response with details of the subscription to the client. The status of the subscription is set as follows:
active - If no trial period is defined.
trialing - If a trial period is defined.
Rapyd sends Webhook - Subscription Created to the client.
Rapyd sends Webhook - New Cycle Started to the client.
Rapyd sends Webhook - Invoice Created to the client. The status of the invoice is set to draft.
Rapyd sends Webhook - Invoice Finalized to the client. The status of the invoice is set to open.
Rapyd requests a fraud check and payment from the card network.
The card network declines the payment.
Rapyd sends Webhook - Invoice Payment Failed to the client. The status of the payment is set to ACT (active).
Rapyd sends Webhook - Payment Failed to the client. The status of the payment is set to ERR (error).
Rapyd sends Webhook - Subscription Unpaid to the client. The status of the subscription is set to unpaid.