Adding a First Billing Amount Before Subscription is Activated
An advance collection is when a payment is collected outside of the application, before the subscription is activated.
The scenario below allows an integrator to add a first payment amount the first debit scheduled by the subscription.
- Customer agreed to a first billing amount while the subscription is set as pending.
- Integrator merchant application will display the subscription details to allow the merchant to approve/start the subscription.
NOTE:
If there is a need to update the first billing amount before activating the subscription, the old subscription will need to be cancelled and a new subscription will need to be created.
Step 1: Create A Subscription
[POST] https://api-{{Environment}}.ezypay.com/v2/billing/subscriptions
API Endpoint Documentation: https://developer.ezypay.com/reference#create-a-subscription
NOTE:
If there is a need to add a billing start amount of X amount into the subscription, this can be action via the "Create Subscription API".
Ezypay will collect the first Payment as soon as the Subscription is Activated (Step 3).
{
"name": "Test8 Payment Plan",
"customerId": "d7744fad-c7cd-49d2-83bd-3740c6eb415b",
"planId": "e8ab0c2f-5e8e-4676-930b-f6f211040d9f",
"autoPayment": "true",
"customerEmailNotification": "true",
"markAsPending": "true",
"startDate": "2019-06-01",
"billingStart": "day_of_month",
"billingStartValue": "1",
"intervalUnit": "MONTH",
"interval": 1,
"accountingCode": "ABC123_NSW",
"firstBillingAmount": {
"currency": "AUD",
"value": "1000"
}
}
{
"id": "842ed3f1-80ac-40e6-84c8-de3d902036b8",
"customerId": "d7744fad-c7cd-49d2-83bd-3740c6eb415b",
"planId": "e8ab0c2f-5e8e-4676-930b-f6f211040d9f",
"name": "Test8 Payment Plan",
"status": "PENDING",
"startDate": null,
"endDate": null,
"paymentMethodToken": "7f63be7a-0c25-4d17-aebd-3ddc1665cf2b",
"accountingCode": "ABC123_NSW",
"amount": {
"currency": "AUD",
"value": 100,
"type": null
},
"tax": {
"rate": 10
},
"nextBillingDate": null,
"nextFutureInvoice": null,
"interval": 1,
"intervalUnit": "MONTH",
"totalPaid": {
"currency": "AUD",
"value": 0,
"type": null
},
"totalBillingCycles": 0,
"remainingToPay": {
"currency": "AUD",
"value": 5000,
"type": null
},
"remainingBillingCycles": null,
"endTargetAmount": {
"currency": "AUD",
"value": 5000,
"type": null
},
"endTargetBillingCycles": null,
"cancelledDate": null,
"failedPaymentHandling": null,
"failedAttemptsCount": 0,
"totalPastDue": {
"currency": "AUD",
"value": 0,
"type": null
},
"totalDiscounted": {
"currency": "AUD",
"value": 0,
"type": null
},
"metadata": null,
"createdOn": "2019-05-27T06:40:08.516",
"autoPayment": true,
"setupPayments": null
}
Step 2: Retrieve Subscription Details
[GET] https://api-{{Environment}}.ezypay.com/v2/billing/subscriptions/{{SubscriptionId}}
API Endpoint Documentation: https://developer.ezypay.com/reference#retrieve-a-subscription
NOTE:
If the "Mark as Pending" status is set to true, there will not be any future Invoice being generated. The Virtual Invoice will start to appear as soon as the subscription is activated (Step 3).
{
"id": "842ed3f1-80ac-40e6-84c8-de3d902036b8",
"customerId": "d7744fad-c7cd-49d2-83bd-3740c6eb415b",
"planId": "e8ab0c2f-5e8e-4676-930b-f6f211040d9f",
"name": "Test8 Payment Plan",
"status": "PENDING",
"startDate": null,
"endDate": null,
"paymentMethodToken": "7f63be7a-0c25-4d17-aebd-3ddc1665cf2b",
"accountingCode": "ABC123_NSW",
"amount": {
"currency": "AUD",
"value": 100,
"type": null
},
"tax": {
"rate": 10
},
"nextBillingDate": null,
"nextFutureInvoice": null,
"interval": 1,
"intervalUnit": "MONTH",
"totalPaid": {
"currency": "AUD",
"value": 0,
"type": null
},
"totalBillingCycles": 0,
"remainingToPay": {
"currency": "AUD",
"value": 5000,
"type": null
},
"remainingBillingCycles": null,
"endTargetAmount": {
"currency": "AUD",
"value": 5000,
"type": null
},
"endTargetBillingCycles": null,
"cancelledDate": null,
"failedPaymentHandling": null,
"failedAttemptsCount": 0,
"totalPastDue": {
"currency": "AUD",
"value": 0,
"type": null
},
"totalDiscounted": {
"currency": "AUD",
"value": 0,
"type": null
},
"metadata": null,
"createdOn": "2019-05-27T06:40:08.516",
"autoPayment": true,
"setupPayments": null
}
Step 3: Activate a Pending Subscription
[PUT] https://api-{{env}}/v2/billing/subscriptions/{{SubscriptionId}}/activate
If the start date is today, just pass in the date in the format of yyyy-mm-dd in the API Request Body.
{
//"paymentMethodToken" : ""
"startDate": "2019-05-27"
}
{
"id": "842ed3f1-80ac-40e6-84c8-de3d902036b8",
"customerId": "d7744fad-c7cd-49d2-83bd-3740c6eb415b",
"planId": "e8ab0c2f-5e8e-4676-930b-f6f211040d9f",
"name": "Test8 Payment Plan",
"status": "ACTIVE",
"startDate": "2019-05-27",
"endDate": "2021-05-01",
"paymentMethodToken": "7f63be7a-0c25-4d17-aebd-3ddc1665cf2b",
"accountingCode": "ABC123_NSW",
"amount": {
"currency": "AUD",
"value": 100,
"type": null
},
"tax": {
"rate": 10
},
"nextBillingDate": "2019-07-01",
"nextFutureInvoice": {
"subscriptionId": "842ed3f1-80ac-40e6-84c8-de3d902036b8",
"date": "2019-07-01",
"cycleStartDate": "2019-07-01",
"cycleEndDate": "2019-07-31",
"items": [
{
"description": "Test8 Payment Plan",
"amount": {
"currency": "AUD",
"value": 100,
"type": null
},
"tax": {
"rate": 10
},
"type": "subscription_payment",
"accountingCode": "ABC123_NSW"
},
{
"description": "Transaction Fee",
"amount": {
"currency": "AUD",
"value": 1.49,
"type": null
},
"tax": {
"rate": 10
},
"type": "transaction_fee",
"accountingCode": null
}
],
"amount": {
"currency": "AUD",
"value": 101.49,
"type": null
},
"totalTax": {
"currency": "AUD",
"value": 9.23,
"type": null
}
},
"interval": 1,
"intervalUnit": "MONTH",
"totalPaid": {
"currency": "AUD",
"value": 1000,
"type": null
},
"totalBillingCycles": 1,
"remainingToPay": {
"currency": "AUD",
"value": 4000,
"type": null
},
"remainingBillingCycles": null,
"endTargetAmount": {
"currency": "AUD",
"value": 5000,
"type": null
},
"endTargetBillingCycles": null,
"cancelledDate": null,
"failedPaymentHandling": null,
"failedAttemptsCount": 0,
"totalPastDue": {
"currency": "AUD",
"value": 0,
"type": null
},
"totalDiscounted": {
"currency": "AUD",
"value": 0,
"type": null
},
"metadata": null,
"createdOn": "2019-05-27T06:41:20.211",
"autoPayment": true,
"setupPayments": null
}
API Endpoint Documentation: https://developer.ezypay.com/reference#activate-a-subscription
Step 4: Get Invoice List From Subscription
[GET] https://api-{{env}}/v2/billing/invoices?customerId={{CustomerId}}&subscriptionId={{SubscriptionId}}
NOTE:
Using the [GET] Invoice List with the Subscription ID selected will display all physical invoices which are available on Ezypay.
Invoices retrieved here are invoices that have been transacted by Ezypay.
For Future Invoice (Virtual Invoices) the integrator would need to call the [GET] Future Invoice API (Step 5).
{
"data": [
{
"id": "6971fe03-d292-4189-8d69-105633eec66b",
"documentNumber": "IN0000000000000187",
"date": "2019-05-27",
"dueDate": "2019-05-27",
"scheduledPaymentDate": null,
"status": "PAID",
"memo": null,
"items": [
{
"description": "Transaction Fee",
"amount": {
"currency": "AUD",
"value": 14.9,
"type": null
},
"tax": {
"rate": 10
},
"id": "438e777b-5963-4fdc-8498-daa6ab0f0727",
"type": "transaction_fee",
"discounted": {
"currency": "AUD",
"value": 0,
"type": null
},
"accountingCode": null
},
{
"description": "Test8 Payment Plan",
"amount": {
"currency": "AUD",
"value": 1000,
"type": null
},
"tax": {
"rate": 10
},
"id": "8458fcaf-2427-4e61-b60e-5deafb3ba706",
"type": "subscription_payment",
"discounted": {
"currency": "AUD",
"value": 0,
"type": null
},
"accountingCode": "ABC123_NSW"
}
],
"amount": {
"currency": "AUD",
"value": 1014.9,
"type": null
},
"amountWithoutDiscount": {
"currency": "AUD",
"value": 1014.9,
"type": null
},
"totalDiscounted": {
"currency": "AUD",
"value": 0,
"type": null
},
"totalRefunded": {
"currency": "AUD",
"value": 0,
"type": null
},
"totalTax": {
"currency": "AUD",
"value": 92.26,
"type": null
},
"customerId": "d7744fad-c7cd-49d2-83bd-3740c6eb415b",
"subscriptionId": "842ed3f1-80ac-40e6-84c8-de3d902036b8",
"subscriptionName": "Test8 Payment Plan",
"paymentMethodToken": "7f63be7a-0c25-4d17-aebd-3ddc1665cf2b",
"autoPayment": true,
"createdOn": "2019-05-27T06:41:20.238"
}
],
"paging": {
"nextUrl": null,
"nextCursor": 0,
"limit": 0,
"totalCount": 1
}
}
Step 5: Get Future Invoice Based On Subscription
[GET] https://api-{{Environment}}.ezypay.com/v2/futureinvoices?subscriptionId={{SubscriptionId}}&customerId={{CustomerId}}&limit=1
NOTE
The up and coming Billing will return to charge the customer 100 every month again.
{
"data": [
{
"subscriptionId": "842ed3f1-80ac-40e6-84c8-de3d902036b8",
"date": "2019-07-01",
"cycleStartDate": "2019-07-01",
"cycleEndDate": "2019-07-31",
"items": [
{
"description": "Test8 Payment Plan",
"amount": {
"currency": "AUD",
"value": 100,
"type": null
},
"tax": {
"rate": 10
},
"type": "subscription_payment",
"accountingCode": "ABC123_NSW"
},
{
"description": "Transaction Fee",
"amount": {
"currency": "AUD",
"value": 1.49,
"type": null
},
"tax": {
"rate": 10
},
"type": "transaction_fee",
"accountingCode": null
}
],
"amount": {
"currency": "AUD",
"value": 101.49,
"type": null
},
"totalTax": {
"currency": "AUD",
"value": 9.23,
"type": null
}
}
],
"paging": {
"nextUrl": null,
"nextCursor": 0,
"limit": 0,
"totalCount": 23
}
}
Step 6: Get Subscription Details (To Check the Next Billing Date)
[GET] https://api-{{Environment}}.ezypay.com/v2/billing/subscriptions/{{SubscriptionId}}
Similar to Step 3, the difference the Next Billing Date will now be available.
NOTE:
The response will now look slightly different to the one retrieve in Step 3.
The "startDate" will now be populated, the "status" will now show as "Active" and the next billing date will be populated as well.Question: Reason why the next billing date is on July 2019 instead of June 2019?
Answer:Due to the initial setup for the start date was configured to the 1st June 2019, So when a start date is moved ahead (2019-05-27) the first collection will include the first Month as well.
{
"id": "842ed3f1-80ac-40e6-84c8-de3d902036b8",
"customerId": "d7744fad-c7cd-49d2-83bd-3740c6eb415b",
"planId": "e8ab0c2f-5e8e-4676-930b-f6f211040d9f",
"name": "Test8 Payment Plan",
"status": "ACTIVE",
"startDate": "2019-05-27",
"endDate": "2021-05-01",
"paymentMethodToken": "7f63be7a-0c25-4d17-aebd-3ddc1665cf2b",
"accountingCode": "ABC123_NSW",
"amount": {
"currency": "AUD",
"value": 100,
"type": null
},
"tax": {
"rate": 10
},
"nextBillingDate": "2019-07-01",
"nextFutureInvoice": {
"subscriptionId": "842ed3f1-80ac-40e6-84c8-de3d902036b8",
"date": "2019-07-01",
"cycleStartDate": "2019-07-01",
"cycleEndDate": "2019-07-31",
"items": [
{
"description": "Test8 Payment Plan",
"amount": {
"currency": "AUD",
"value": 100,
"type": null
},
"tax": {
"rate": 10
},
"type": "subscription_payment",
"accountingCode": "ABC123_NSW"
},
{
"description": "Transaction Fee",
"amount": {
"currency": "AUD",
"value": 1.49,
"type": null
},
"tax": {
"rate": 10
},
"type": "transaction_fee",
"accountingCode": null
}
],
"amount": {
"currency": "AUD",
"value": 101.49,
"type": null
},
"totalTax": {
"currency": "AUD",
"value": 9.23,
"type": null
}
},
"interval": 1,
"intervalUnit": "MONTH",
"totalPaid": {
"currency": "AUD",
"value": 1000,
"type": null
},
"totalBillingCycles": 1,
"remainingToPay": {
"currency": "AUD",
"value": 4000,
"type": null
},
"remainingBillingCycles": null,
"endTargetAmount": {
"currency": "AUD",
"value": 5000,
"type": null
},
"endTargetBillingCycles": null,
"cancelledDate": null,
"failedPaymentHandling": null,
"failedAttemptsCount": 0,
"totalPastDue": {
"currency": "AUD",
"value": 0,
"type": null
},
"totalDiscounted": {
"currency": "AUD",
"value": 0,
"type": null
},
"metadata": null,
"createdOn": "2019-05-27T06:41:20.211",
"autoPayment": true,
"setupPayments": null
}
Updated almost 2 years ago