Merchant Subscription Payment API Guide

Overview

This guide explains how to integrate the Anyway MoR Platform's subscription payment system into your merchant application. The subscription flow allows you to set up recurring payments for your customers with automated billing.

Environment

Sandbox Environment: https://api.mor.dev.anyway.sh
Production Envrionment: TBD

Architecture

The subscription flow involves two main participants:

Your Merchant Application - Initiates subscription setup and receives webhooks

Anyway MoR Platform - Manages subscription lifecycle, payment processing, and automated billing

Making Payments

Once you have your Product ID and API Key, you can integrate payments into your application.

API Integration

Use the Subscription Setup API to process payments:

You'll need:

Your API Key (for authentication)

The Product ID (from your Products Catalog)

Integration Flow

Phase 1: Initial Setup (Customer Authorization)

This phase sets up a new subscription and authorizes the customer's payment method for recurring charges.

Step 1: Create Subscription Setup

Endpoint: POST /api/v1/subscriptions/setup

Authentication: Bearer token (your merchant API key)

Request Body:

{
  "productId": "your_product_id",
  "setupSuccessUrl": "https://yoursite.com/subscription/success",
  "setupCancelUrl": "https://yoursite.com/subscription/cancel",
  "webhookUrl": "https://yoursite.com/webhooks/subscription",
  "customerEmail": "customer@example.com",
  "customerFirstName": "John",
  "customerLastName": "Doe",
  "customerCountry": "USA",
  "productName": "Premium Membership",
  "description": "Monthly premium subscription",
  "firstPaymentAmount": 0.00
}

Request Parameters:

Parameter	Type	Required	Description
`productId`	string	Yes	Your product identifier. If it doesn't contain "ORG", your org ID will be prepended automatically
`setupSuccessUrl`	string	Yes	URL to redirect customer after successful payment setup
`setupCancelUrl`	string	Yes	URL to redirect customer if they cancel the setup
`webhookUrl`	string	Yes	URL to receive webhook notifications
`customerEmail`	string	Yes	Customer's email address
`customerFirstName`	string	Yes	Customer's first name
`customerLastName`	string	Yes	Customer's last name
`customerCountry`	string	Yes	3-letter ISO country code (e.g., "USA", "GBR")
`productName`	string	No	Display name for the product/service
`description`	string	No	Description of the subscription
`firstPaymentAmount`	decimal	No	Amount for first payment. Set to 0 for setup-only (no immediate charge), or specify amount for immediate charge

Note: The amount, currency, and interval are automatically fetched from the product pricing configuration in the database.

Response:

{
  "success": true,
  "message": "Subscription setup created successfully. Redirect customer to setup_url.",
  "data": {
    "paymentUrl": "https://payment.dev.anyway.sh/pay?token=eyJhbGc...",
    "orderId": "PI_538854c3f217645d3b30b7a2ce00d362",
    "subscriptionId": "sub_d749f000e08344e58b37230216e516c9",
    "status": "PAYMENT_PENDING",
    "expiresIn": 3600000
  }
}

Response Fields:

Field	Description
`paymentUrl`	Redirect URL for customer to complete payment setup
`orderId`	Unique order identifier for this subscription
`subscriptionId`	Unique subscription identifier
`status`	Current status (PAYMENT_PENDING)
`expiresIn`	JWT token expiration time in milliseconds (1 hour)

Step 2: Redirect Customer to Payment Setup

Redirect your customer to the paymentUrl returned in the response. The customer will:

Enter their payment details securely on the Anyway payment page

Authorize recurring payments for the subscription

Complete the setup process

Step 3: Customer Redirects Back to Your Site

After the customer completes or cancels the setup:

Success: Customer is redirected to your setupSuccessUrl

Cancel: Customer is redirected to your setupCancelUrl

Step 4: Receive Webhook Notification

Shortly after successful setup, you'll receive a webhook notification:

Webhook Event: subscription_setup_complete

Webhook Payload:

{
  "event": "subscription_setup_complete",
  "subscriptionId": "sub_d749f000e08344e58b37230216e516c9",
  "orderId": "PI_538854c3f217645d3b30b7a2ce00d362",
  "status": "ACTIVE",
  "activatedAt": "2025-10-14T10:30:00Z",
  "nextBillingDate": "2025-11-14T10:30:00Z",
  "amount": 29.99,
  "currency": "USD",
  "interval": "monthly"
}

Important: Your webhook endpoint should:

Return HTTP 200 status for successful receipt

Verify the subscription status in your database

Activate the customer's subscription features

Phase 2: Recurring Billing (Automated)

The MoR Platform automatically handles recurring billing through a scheduled job.

Automated Billing Process

Daily/Hourly Cron Job runs to check for subscriptions due for billing

For each due subscription, the platform:

Processes the recurring payment automatically using the stored payment method

Updates subscription billing dates

Sends webhook notifications on success or failure

Success Scenario

Webhook Event: subscription_payment_succeeded

Webhook Payload:

{
  "event": "subscription_payment_succeeded",
  "subscriptionId": "sub_d749f000e08344e58b37230216e516c9",
  "orderId": "PI_new_order_id",
  "amount": 29.99,
  "currency": "USD",
  "lastBilledAt": "2025-11-14T10:30:00Z",
  "nextBillingDate": "2025-12-14T10:30:00Z",
  "paymentStatus": "paid"
}

Failure Scenarios

First Failure (Soft Failure):

Webhook Event: subscription_payment_failed

{
  "event": "subscription_payment_failed",
  "subscriptionId": "sub_d749f000e08344e58b37230216e516c9",
  "failureReason": "card_declined",
  "retryCount": 1,
  "nextRetryDate": "2025-11-17T10:30:00Z",
  "paymentStatus": "failed"
}

The platform will automatically retry in 3 days.

Multiple Failures (Hard Failure):

After 3+ failed attempts:

Webhook Event: subscription_payment_failed

{
  "event": "subscription_payment_failed",
  "subscriptionId": "sub_d749f000e08344e58b37230216e516c9",
  "failureReason": "multiple_failures",
  "retryCount": 3,
  "status": "past_due",
  "paymentStatus": "failed"
}

The subscription is marked as past_due or cancelled, and the customer receives an email to update their payment method.

Phase 3: Customer Management

Get Subscription Status

Endpoint: GET /api/v1/subscriptions/{subscriptionId}

Authentication: Bearer token (your merchant API key)

Response:

{
  "success": true,
  "data": {
    "subscriptionId": "sub_d749f000e08344e58b37230216e516c9",
    "amount": 29.99,
    "currency": "USD",
    "interval": "monthly",
    "status": "ACTIVE",
    "description": "Monthly premium subscription",
    "productName": "Premium Membership",
    "customerEmail": "customer@example.com",
    "customerName": "John Doe",
    "customerId": "cust_123",
    "paymentMethodId": "pm_xyz789",
    "createdAt": "2025-10-14T10:30:00Z",
    "activatedAt": "2025-10-14T10:35:00Z",
    "nextBillingDate": "2025-11-14T10:30:00Z",
    "firstPaymentAmount": 0.00
  }
}

Cancel Subscription

Endpoint: POST /api/v1/subscriptions/{subscriptionId}/cancel

Authentication: Bearer token (your merchant API key)

Response:

{
  "success": true,
  "message": "Subscription cancelled successfully"
}

Webhook Event: subscription_cancelled

{
  "event": "subscription_cancelled",
  "subscriptionId": "sub_d749f000e08344e58b37230216e516c9",
  "canceledAt": "2025-10-14T15:00:00Z",
  "cancelAtPeriodEnd": true
}

Update Payment Method

Note: This endpoint is planned for future implementation.

When a customer needs to update their payment method (e.g., expired card):

Endpoint: POST /api/v1/subscriptions/{subscriptionId}/update_payment_method

The customer will be redirected to a secure form to enter new payment details, similar to the initial setup flow.

Webhook Implementation Guide

Webhook Security

HTTPS Only: Your webhook endpoint must use HTTPS

Verify Source: Validate that webhook requests come from Anyway's servers

Idempotency: Handle duplicate webhook deliveries gracefully using the orderId or subscriptionId

Webhook Response Requirements

Return HTTP 200 status for successful receipt

Respond within 5 seconds

If your endpoint fails, the platform will retry with exponential backoff

Sample Webhook Handler (Node.js)

Subscription Status Reference

Status	Description
`PENDING`	Subscription created, awaiting customer payment setup
`ACTIVE`	Subscription is active and billing normally
`PAST_DUE`	Payment failed multiple times, awaiting resolution
`CANCELED`	Subscription has been cancelled
`PAUSED`	Subscription is paused (billing cycles skipped)

Billing Interval Reference

Interval	Description
`WEEKLY`	Billed every 7 days
`MONTHLY`	Billed once per month
`YEARLY`	Billed once per year

Testing Guide

Test Product Setup

Create a test product in the database with pricing configuration:

Product ID: test_premium_monthly

Amount: 9.99 USD

Interval: MONTHLY

Test Flow

Call POST /api/v1/subscriptions/setup with test customer data

Use the returned paymentUrl to complete test payment setup

Verify webhook is received at your webhookUrl

Check subscription status via GET /api/v1/subscriptions/{subscriptionId}

Test Cards

Use the following test cards for different scenarios:

Success: 4242 4242 4242 4242

Decline: 4000 0000 0000 0002

Insufficient Funds: 4000 0000 0000 9995

Error Handling

Common Error Responses

Invalid Request (400):

{
  "success": false,
  "message": "Invalid request parameters",
  "errors": [
    "customerEmail must be a valid email address"
  ]
}

Unauthorized (401):

{
  "success": false,
  "message": "Invalid or missing authentication token"
}

Not Found (404):

{
  "success": false,
  "message": "Subscription not found"
}

Internal Server Error (500):

{
  "success": false,
  "message": "Unable to process subscription setup",
  "error": "Payment processing failed"
}

Support and Questions

For technical support or integration questions:

Email: support@anyway.sh

Documentation: https://docs.anyway.sh

API Status: https://status.anyway.sh

Changelog

v1.0 (2025-10-14): Initial subscription API release

Subscription setup with secure payment processing

Automated recurring billing

Webhook notifications

Subscription management endpoints

Setup

Merchant Subscription Payment API Guide#

Overview#

Environment#

Architecture#

Making Payments#

API Integration#

Integration Flow#

Phase 1: Initial Setup (Customer Authorization)#

Step 1: Create Subscription Setup#

Step 2: Redirect Customer to Payment Setup#

Step 3: Customer Redirects Back to Your Site#

Step 4: Receive Webhook Notification#

Phase 2: Recurring Billing (Automated)#

Automated Billing Process#

Success Scenario#

Failure Scenarios#

Phase 3: Customer Management#

Get Subscription Status#

Cancel Subscription#

Update Payment Method#

Webhook Implementation Guide#

Webhook Security#

Webhook Response Requirements#

Sample Webhook Handler (Node.js)#

Subscription Status Reference#

Billing Interval Reference#

Testing Guide#

Test Product Setup#

Test Flow#

Test Cards#

Error Handling#

Common Error Responses#

Support and Questions#

Changelog#

Merchant Subscription Payment API Guide

Overview

Environment

Architecture

Making Payments

API Integration

Integration Flow

Phase 1: Initial Setup (Customer Authorization)

Step 1: Create Subscription Setup

Step 2: Redirect Customer to Payment Setup

Step 3: Customer Redirects Back to Your Site

Step 4: Receive Webhook Notification

Phase 2: Recurring Billing (Automated)

Automated Billing Process

Success Scenario

Failure Scenarios

Phase 3: Customer Management

Get Subscription Status

Cancel Subscription

Update Payment Method

Webhook Implementation Guide

Webhook Security

Webhook Response Requirements

Sample Webhook Handler (Node.js)

Subscription Status Reference

Billing Interval Reference

Testing Guide

Test Product Setup

Test Flow

Test Cards

Error Handling

Common Error Responses

Support and Questions

Changelog