Overview
We provide services to allow your business to integrate recurring payments for your product packages/products that need to be charged according to specific cycles.
When your business integrates Merchant hosted model, you can allow your customer to input payment information in your page and then make payment this transaction easily. This document provides details on how you can integrate Subscription Payments.
Integration model
| Step | PIC | Description |
|---|---|---|
| 1 | End user | On the merchant's page, input personal information |
| 2 | End user | Choose the expected plan with the service the merchant is providing |
| 3 | End user | Choose the payment method (currently AppotaPay offers one method, Credit card, to make payment) |
| 4 | End user | Input payment information (card information, billing information,...) |
| 5 | End user | Submit information and confirm payment |
| Create customer | ||
| 6 | Merchant | Record information sent by merchant: Customer information (only create individual customers) → Send request to create Customer before creating payment method (customer can also be created in request of ‘Create payment method’ API) |
| 7 | AppotaPay | Receive customer creation request, the system processes to create customer and responds |
| 8 | Merchant | Record customer ID information |
| Create payment method | ||
| 9 | Merchant | Save information, Send request to create a Payment method with the customer ID received in Step 8 (attach the merchant's return_url to receive payment linking results) including the information: - Customer information (or Customer ID) - Payment method - Billing information - Card information |
| 10 | AppotaPay | Check the existence of Customer ID in the request - If it does not exist → Go to step 11 - If it already exists → Go to step 13 |
| 11 | AppotaPay | Respond error code to merchant |
| 12 | Merchant | Receive information and display errors to the user |
| 13 | AppotaPay | Create a payment method and return the results to the Merchant |
| 14 | Merchant | Receive response of payment method |
| 15 | Merchant | Check the status of the payment method REQUIRES_ACTION → go to step 16 ACTIVE → go to step 25 PENDING → go to step 22 |
| If Payment method's status is REQUIRES_ACTION | ||
| 16 | Merchant | Redirect user to action.url to perform the necessary actions |
| 17 | End user | User performs action according to the displayed url → The AppotaPay system processes and navigates to the return url corresponding to each result: step 18 → At the same time, AppotaPay also triggers related events and callbacks to Merchant: step 22 |
| 18 | AppotaPay | Check information which the user inputs , process the system → redirect the user to the return url corresponding to the status of the payment method (which the Merchant provided previously) - If payment method is failed → redirect to failureReturnUrl - If payment method is activated → redirect to successReturnUrl |
| 19 | Merchant | Merchant checks the payment method status - Failure → go to step 20 - Success → go to step 21 |
| 20 | Merchant | Receive payment method results, update status Show error to user → perform another transaction again |
| 21 | Merchant | Receive payment method status, update status Display the loading page and wait for the next steps to complete recurring payments → go to step 25 → chuyển bước 25 |
If Payment method's status is PENDING Merchant waits for response from AppotaPay about the specific status via callback | ||
| 22 | AppotaPay | Trigger event related to payment method and call back for Merchant - Payment method activated - event: payment_method.activated - status:ACTIVE - Payment method failed - event: payment_method.failed - status: FAILED |
| 23 | Merchant | Check event and status in event - If status = FAILED → Step 24 - If status = ACTIVATED → Step 25 |
| 24 | Merchant | Show error to user and end transaction, initiate another transaction |
If Payment method's status is ACTIVE → Go to step 25 | ||
| Create plan | ||
| 25 | Merchant | Start creating Plan, send request with information - Customer ID - Payement method ID - Schedule info (interval, retry, failed cycle action,...) |
| 26 | AppotaPay | Check the existence of Customer ID and Payment method ID - If it does not exist → go to step 24 - If it exists → go to step 27 |
| 27 | AppotaPay | Check the status of payment method ID - If the status isn’t ACTIVE → go to step 24 - If the status is ACTIVE → go to step 28 |
| 28 | AppotaPay | Initialize the plan and respond to the plan information and plan status At the same time, the AppotaPay system also proactively checks information and status, starts callback activation plan event for Merchant (perform like step 33) |
| 29 | Merchant | Check plan status - REQUIRES_ACTION → go to step 30 - PENDING → go to 32 - ACTIVE → go to 36 |
| 30 | Merchant | Redirect the user to actions.url (returned in the response) for the user to perform additional necessary actions |
| 31 | User | User performs action according to the displayed url → The AppotaPay system processes and then triggers events related to the activation plan: step 33 |
| 32 | Merchant | Wait for webhook activation from AppotaPay (At the same time, the AppotaPay system also proactively checks information and status, call back activation plan for Merchant (perform like step 33)) |
| 33 | AppotaPay | After processing the plan information, AppotaPay will call back the activation plan to the Merchant At the same time, check if the plan is required immediate charging (step 38) |
| 34 | Merchant | Check event and plan status - If event is subscription.plan.activated and status is ACTIVE → go to step 36 - If event is subscription.plan.inactivated and status is INACTIVE → go to step 35 |
| 35 | Merchant | Display error code to end user |
| 36 | Merchant | Wait for the webhook event related to the cycle to be initiated or paid for the plan |
| 37 | Merchant | Receive cycle event information |
| 38 | AppotaPay | Check if the plan is required immediate charging or not - If No → go to step 39 - If Yes → go to step 40 |
| 39 | AppotaPay | AppotaPay calls back event for the first cycle (successfully initialized) - event subscription.cycle.created and status is SCHEDULED Lưu ý: Recurring time will depend on the anchor_date information sent |
| 40 | AppotaPay | AppotaPay calls back event for the first cycle (successful paid) - event subscription.cycle.succeeded and status is SUCCEEDED |
| 41 | AppotaPay | After sending subscription.cycle.succeeded event AppotaPay calls back event for the next cycle (successfully initialized) - event: subscription.cycle.created and status is SCHEDULED |
| 42 | Merchant | Display plan/ cycle result |