Advanced Features

Recurring Payments

Implementing subscription and recurring billing models

Overview

Recurring payments allow merchants to offer subscription-based services and automate billing cycles. With PayOS, merchants can securely store customer payment tokens and initiate recurring charges without requiring customer re-entry of payment details.

Tokenization for Recurring Payments

  • Tokenization: PayOS converts sensitive payment details into secure tokens. These tokens represent payment instruments such as cards or bank accounts.
  • Reusable Tokens: Stored tokens enable merchants to charge customers repeatedly without needing to collect payment data again.

Example of Tokenized Payment Response:

1{
2  "id": "recurring_token_12345",
3  "type": "card",
4  "last_used": "2024-10-17T12:05:00Z",
5  "card_details": {
6    "brand": "Visa",
7    "last4": "4242",
8    "expiry_month": "12",
9    "expiry_year": "2026"
10  }
11}

How It Works

  1. Create Initial Payment:

    • Collect payment details from the customer during the first transaction.
    • PayOS returns a payment token upon successful authorization.

  2. Store Token:

    • Store the token securely within your merchant system for future transactions.

  3. Initiate Recurring Charges:

    • Use the stored token to initiate future charges.
    • Optional: Allow customers to manage their payment methods via your portal.

Example Recurring Payment Request:

$curl --request POST 'https://api.payos.money/api/v1/recurring' --header 'Authorization: Bearer YOUR_API_KEY' --header 'Content-Type: application/json' --data-raw '{
>  "token_id": "recurring_token_12345",
>  "amount": 1000,
>  "currency": "USD",
>  "description": "Monthly subscription for Premium Plan"
>}'

Best Practices

  • Subscription Management: Merchants should handle subscription status changes (e.g., cancellations or reactivations) within their own systems.
  • Expiry Handling: Monitor token expiry dates and notify customers in advance if updates are needed.
  • Secure Storage: Store tokens in compliance with PCI standards to minimize risk.

Error Handling and Retries

PayOS will automatically retry failed recurring payments based on configured rules. Merchants are notified via webhooks in case of repeated failures.