Using Your Own Linking UI

You should use this flow if your business does not need a web page for linking, or if you prefer to use your own web page for your customers to link their payment method. Using your own web page has several tradeoffs:

You have a higher level of customization on your linking site
Your Linking UI must integrate with our create payment method API
Your integration must cover the different authentication flows of the different payment methods.
To accept Credit or Debit Cards, you will need to :
- Have PCI DCSS Certification
- Otherwise, you need to use Xendit.js to collect your customer's card information (Reference)

High level flow

Creating a Customer

Before creating a subscription plan, you must create a Customer Object using the Create Customer API.

The mobile number in the customer object is mandatory for eWallet payments. Please ensure that the inputted mobile number is registered with the eWallet account.

POST https://api.xendit.co/customers

{
     "reference_id": "demo_1475801962607",
     "type": "INDIVIDUAL",
     "individual_detail": {
       "given_names": "John",
       "surname": "Doe"
     },
     "email": "customer@website.com",
     "mobile_number": "+628121234567890"
}

Creating a Payment Method

After creating a customer, you will need to create a Payment Method Object using the Create Payment Method API endpoint.

Example of Create Payment Method Request:

POST https://api.xendit.co/v2/payment_methods

{
  "type": "EWALLET",
  "reusability": "MULTIPLE_USE",
  "ewallet": {
    "channel_code": "OVO",
    "channel_properties": {
      "success_return_url": "https://your-redirect-website.com/success",
      "failure_return_url": "https://your-redirect-website.com/failure"
    }
  },
  "customer_id": "fc4c060b-3c41-4707-b7b2-df9c3376edde",
  "metadata": {
    "sku": "ABCDEFGH"
  }
}

When the API returns a successful response, this means that the account linking process has started. You will need to pass the payment_method_id to the Plan Creation API in the next step.

If you receive a response with a REQUIRES_ACTION status, this means that your customer is required to perform additional steps for the linking to be successful. The most common actions are:

Redirecting the end user to a web page for authentication
Send a one-time code for authorization validated via an API

Note: Expect a Payment Method Activated Webhook to be sent to your specified callback URL once the payment method has been successfully authorized for payments.

Creating a Plan

Once you have created your Customer and your customer has successfully authorized the payment method, you are now ready to use the Create Plan endpoint. Enter the customer_id and the payment_method_id retrieved from the previous to the request of Plan Creation API. You may also input more than 1 payment_method_id in one plan and rank them by preference.

Note: The status of the Payment Method must be ACTIVE in order for the plan to be successfully activated.

During this step, you are able to configure a wide range of settings for your end users. See our API reference for more information.

Example of Create Subscription Plan Request:

POST https://api.xendit.co/recurring/plans

{
  "reference_id": "test_reference_id",
  "customer_id": "cust-239c16f4-866d-43e8-9341-7badafbc019f",
  "recurring_action": "PAYMENT",
  "currency": "IDR",
  "amount": 13579,
  "payment_methods": [{
    "payment_method_id": "pm-asdaso213897821hdas",
    "rank": 1
  }],
  "schedule": {
    "reference_id": "test_reference_id",
    "interval": "MONTH",
    "interval_count": 1,
    "total_recurrence": 12,
    "anchor_date": "2022-02-15T16:23:52Z",
    "retry_interval": "DAY",
    "retry_interval_count": 3,
    "total_retry": 2,
    "failed_attempt_notifications": [1,2]
  },
  "immediate_action_type": "FULL_AMOUNT",
  "notification_config": {
    "recurring_created": ["WHATSAPP","EMAIL"],
    "recurring_succeeded": ["WHATSAPP","EMAIL"],
    "recurring_failed": ["WHATSAPP","EMAIL"],
    "locale": "en"},
  "failed_cycle_action": "STOP",
  "payment_link_for_failed_attempt" : true,
  "metadata": null,
  "description": "Video Game Subscription",
  "items": [
        {
            "type": "DIGITAL_PRODUCT",
            "name": "Cine Mraft",
            "net_unit_amount": 13579,
            "quantity": 1,
            "url": "https://www.xendit.co/",
            "category": "Gaming",
            "subcategory": "Open World"
      }
   ]
}

Last Updated on 2025-01-10

Creating a Customer
Creating a Payment Method
Creating a Plan