Skip to main content
Version: Lastest

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

Ảnh Mô hình kết nối Merchant Hosted Subscription

NoPICMain stepDescription
1End userCreate transactionOn the merchant's page, input personal information
2End userChoose the expected plan with the service the merchant is providing
3End userChoose the payment method (currently AppotaPay offers one method, Credit card, to make payment)
4End userInput payment information (card information, billing information,...)
5End userSubmit information and confirm payment
Create customer
6MerchantCreate customer

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)

7AppotaPayReceive customer creation request, the system processes to create customer and responds
8MerchantRecord customer ID information
Create payment method
9MerchantCreate payment method

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

10AppotaPay

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

11AppotaPayRespond error code to merchant
12MerchantReceive information and display errors to the user
13AppotaPayCreate a payment method and return the results to the Merchant
14MerchantReceive response of payment method
15Merchant

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
16MerchantAuthenticate payment methodRedirect user to action.url to perform the necessary actions
17End 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

18AppotaPay

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

19Merchant

Merchant checks the payment method status

- Failure → go to step 20

- Success → go to step 21

20Merchant

Receive payment method results, update status

Show error to user → perform another transaction again

21Merchant

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

22AppotaPayWait payment method result

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

23Merchant

Check event and status in event

- If status = FAILED → Step 24

- If status = ACTIVATED → Step 25

24MerchantShow error to user and end transaction, initiate another transaction

If Payment method's status is ACTIVE

→ Go to step 25

Create plan
25MerchantCreate plan

Start creating Plan, send request with information

- Customer ID

- Payement method ID

- Schedule info (interval, retry, failed cycle action,...)

26AppotaPay

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

27AppotaPay

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

28AppotaPay

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)

29Merchant

Check plan status

- REQUIRES_ACTION → go to step 30

- PENDING → go to 32

- ACTIVE → go to 36

30MerchantRedirect the user to actions.url (returned in the response) for the user to perform additional necessary actions
31User

User performs action according to the displayed url

→ The AppotaPay system processes and then triggers events related to the activation plan: step 33

32Merchant

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))

33AppotaPayReceive webhook events

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)

34Merchant

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

35MerchantDisplay error code to end user
36MerchantWait for the webhook event related to the cycle to be initiated or paid for the plan
37MerchantReceive cycle event information
38AppotaPay

Check if the plan is required immediate charging or not

- If No → go to step 39

- If Yes → go to step 40

39AppotaPay

AppotaPay calls back event for the first cycle (successfully initialized) - event subscription.cycle.created and status is SCHEDULED

Note: Recurring time will dependon the anchor_date information sent

40AppotaPayAppotaPay calls back event for the first cycle (successful paid) - event subscription.cycle.succeeded and status is SUCCEEDED
41AppotaPay

After sending subscription.cycle.succeeded event

AppotaPay calls back event for the next cycle (successfully initialized) - event: subscription.cycle.created and status is SCHEDULED

42MerchantDisplay plan/ cycle result