Frequently Asked Questions (FAQ)

Quick answers to common questions about Paysera Recurring Billing API.

Quick Navigation

Use the tabs below to find answers by category. Click any question to expand the answer.

🔰 General

General Questions

What is recurring billing?

Recurring billing allows you to charge customers automatically on a regular schedule (monthly, yearly, etc.) without requiring them to manually authorize each payment.

Key Features:

• Automatic subscription payments
• Token-based authorization
• Variable billing amounts
• Flexible billing schedules
• Secure card tokenization

How it works:

1. Customer makes initial payment with user interaction
2. System obtains a recurring billing token
3. Future charges use the token (no customer interaction needed)

How does recurring billing work?

The recurring billing flow:

1. Initial Payment (with user interaction)

   • Create payment request with token_strategy: "required"
   • Customer completes payment on Paysera page
   • Receive notification with issued_token

2. Store Token

   • Save the token securely in your database
   • Link token to customer/subscription

3. Future Charges (automatic)

   • Create payment request with stored token
   • Authorize payment via API
   • No customer interaction needed

📖 Complete flow documentation →

Is recurring billing available for all payment methods?

No. Recurring billing supports cards only:

• ✅ Credit/debit cards (Visa, Mastercard), entered in the card form

Not supported:

• ❌ Bank payments and bank accounts
• ❌ Apple Pay and Google Pay
• ❌ Other payment methods

Note: The first payment must be made by card for a token to be issued.

Do I need a special account to use recurring billing?

Your project must be approved by Paysera before recurring billing is enabled.

Recurring billing is not available by default on a new account. To use it you need:

• ✅ A registered Paysera account
• ✅ A Checkout project
• ✅ Approval from Paysera support to enable recurring billing
• ✅ MAC credentials issued to you after approval

The approval step exists because Paysera needs to review how you intend to use recurring billing before enabling it for your project.

📖 How to obtain credentials and request access →

What are the typical use cases?

Common scenarios:

• 🔄 Subscriptions - Monthly/yearly software subscriptions
• 📦 Membership Fees - Gym memberships, clubs
• 📰 Content Access - News sites, streaming services
• 🏢 SaaS Products - Cloud services, web applications
• 💼 Professional Services - Retainer agreements
• 🎓 Education - Course subscriptions, online learning

🔧 Integration

Integration Questions

How do I enable recurring billing?

To enable recurring billing:

1. Include token_strategy: "required" in initial payment request
2. Process the notification callback
3. Extract and store the issued_token from notification data

Example payment request:

{
  "business_id": "your_business_id",
  "order_id": "SUB_12345",
  "price": { "amount": "9.99", "currency": "EUR" },
  "description": "Monthly subscription",
  "payer": { "email": "customer@example.com" },
  "token_strategy": "required",
  "accept_url": "https://yoursite.com/success",
  "cancel_url": "https://yoursite.com/cancel",
  "callback_url": "https://yoursite.com/callback"
}

After successful payment, the notification will include issued_token field.

📖 Integration guide →

How long does integration take?

Typical timeline:

Experience Level	Estimated Time
Experienced developer	4-8 hours
Intermediate developer	1-2 days
Learning as you go	2-4 days

Time includes:

• API authentication setup
• Initial payment implementation
• Callback handling
• Token storage
• Recurring charge implementation
• Testing

Do I need HTTPS/SSL certificate?

Yes, HTTPS is required!

Reasons:

• 🔒 Security for payment data
• ✅ Required for callback URL
• 🛡️ PCI DSS compliance
• 🌐 Browser requirements

Note: Most hosting providers offer free SSL certificates via Let's Encrypt.

What programming languages are supported?

Any language that can make HTTP requests!

Official libraries:

• PHP (Recurring Billing API client)
• PHP (Notification Event API client)

Custom integration (any other language):

• Call the REST API directly
• Implement MAC authentication yourself
• See the Examples page for sample implementations in JavaScript, Python, and PHP

📖 View libraries →

Can I use Recurring Billing API with mobile apps?

Yes! Two approaches:

1. WebView (Recommended)

   • Open payment page in app's browser
   • Handles 3D Secure automatically
   • Simplest integration

2. Backend API

   • Process through your server
   • App communicates with your backend
   • Your backend handles Paysera API

Best practice: Never store MAC credentials in mobile apps - always use backend API.

💻 Technical

Technical Questions

What is a callback URL and why is it needed?

Callback URL is where Paysera sends payment status notifications.

Why it's critical:

• 🔔 Real-time payment status updates
• 🔐 Secure confirmation (cannot be faked by user)
• 🎯 Delivers the recurring billing token
• ⚡ Triggers order fulfillment

Requirements:

• Must be publicly accessible (not localhost)
• Must use HTTPS
• Should respond quickly (< 10 seconds)
• Must return "OK" for successful processing

📖 Callback handling guide →

How do I authenticate API requests?

MAC Authentication is used for all API requests.

Authentication header format:

Authorization: MAC id="your_mac_id",
                   ts="1234567890",
                   nonce="random_string",
                   mac="calculated_hash"

Parameters:

• id - Your MAC ID
• ts - Unix timestamp
• nonce - Random unique string
• mac - HMAC-SHA256 signature

📖 Authentication guide →

How long is a billing token valid?

A token has no expiry date. It can be used until a charge with it is refused, for example because the card expired or was replaced.

• No event is sent when a token stops working; it shows up only as a failed charge
• A token works only with the credentials that created it

Best practices:

• Handle refused charges gracefully
• Prompt customer to update payment method after a refused charge

Can I charge different amounts each time?

Yes! Variable amounts are supported.

Use cases:

• 📊 Usage-based billing (charge by usage)
• 💰 Tiered subscriptions (different plans)
• 📈 Annual price increases
• 🎁 Promotional discounts
• ⚖️ Proration for upgrades/downgrades

Each recurring charge can specify a different amount and currency.

How do I cancel a subscription?

Simply stop charging the token.

No API call needed to "cancel" a token. Just:

1. Update subscription status in your database
2. Stop sending recurring payment requests
3. (Optional) Notify customer via email

Customer-initiated cancellation:

• Provide cancellation UI in your app
• Mark subscription as cancelled
• Stop processing charges

What happens if a recurring charge fails?

No notification is sent for a failed or declined charge. Only payment_request.captured and payment_request.checkout_token_issued events exist.

The charge request answers immediately: on failure it returns an error with the reason in error_description, and the payment request stays new.

Possible error_description values:

• 💰 Insufficient funds
• 🏦 Failed to authorize payment
• 💳 Invalid card number
• 📅 Expired card
• 🚫 Restricted card

Other declines, for example a replaced card or a deactivated token, can come back as Unexpected issue occurred, please try again later. That answer and Service is unavailable. can also be technical errors: repeat the request for the same payment request instead of creating a new one, as a repeat checks the earlier attempt first. See Repeating a request.

Best practices:

• Retry a declined charge (for example Insufficient funds) later; after a technical error or a timeout, repeat the request for the same payment request
• Notify customer immediately
• Provide payment update option
• Suspend service after retries exhausted

📖 Error handling →

🔐 Security

Security Questions

Is Recurring Billing API secure?

Yes! Multiple security layers:

• 🔒 HTTPS encryption for all communications
• ✅ MAC authentication for request signing
• 🏦 PCI DSS Level 1 compliant
• 🔐 3D Secure for card payments
• 📝 Transaction logging and monitoring
• 🛡️ Fraud detection systems

Your responsibilities:

• Keep MAC credentials secret
• Validate callback signatures
• Use HTTPS on your site
• Secure token storage

How do I secure the billing token?

Token security best practices:

DO:

• ✅ Store in encrypted database columns
• ✅ Restrict access to authorized personnel
• ✅ Use secure connections (HTTPS/TLS)
• ✅ Implement access controls
• ✅ Log token usage

DON'T:

• ❌ Expose in client-side code
• ❌ Include in URLs or logs
• ❌ Send via email or chat
• ❌ Store in plain text
• ❌ Share across systems unnecessarily

How do I verify callback authenticity?

Always validate the MAC signature!

Callbacks must be validated to prevent fraud. The notification includes authentication in the request headers.

Security measures:

1. Verify MAC signature
2. Check timestamp to prevent replay attacks
3. Validate notification ID is unique
4. Use HTTPS for callback URL

Never trust callback data without verification!

📖 Callback validation →

Where should I store MAC credentials?

Security best practices:

DO:

• ✅ Store in environment variables
• ✅ Use secure config files (outside web root)
• ✅ Use secrets management services
• ✅ Encrypt at rest
• ✅ Limit access to authorized personnel

DON'T:

• ❌ Hardcode in source code
• ❌ Commit to version control (Git)
• ❌ Store in public repositories
• ❌ Send via email or chat
• ❌ Include in client-side code

What if my MAC credentials are compromised?

Immediate actions:

1. 🚨 Contact Paysera support immediately
2. 🔑 Regenerate MAC credentials
3. 🔄 Update all integration code
4. 📊 Review recent transactions
5. 🔍 Investigate security breach
6. 📝 Document incident

Prevention:

• Regular security audits
• Access logging
• Principle of least privilege
• Secure credential storage

⚠️ Troubleshooting

Troubleshooting

Why am I not receiving the billing token?

Common reasons:

1. Missing token_strategy parameter

   • ✓ Ensure token_strategy: "required" is included

2. Wrong payment method

   • ✓ Customer used non-tokenizable method (bank transfer)
   • ✓ Only cards support recurring billing

3. Callback not processed

   • ✓ Check callback URL is accessible
   • ✓ Verify HTTPS certificate
   • ✓ Look for issued_token in notification data (not in payment request response)

4. Account issues

   • ✓ Recurring billing may need to be enabled
   • ✓ Contact Paysera support

Why are recurring charges being declined?

Check for:

• 💳 Card expired - Notify customer to update
• 💰 Insufficient funds - Retry in a few days
• 🚫 Card limit reached - Customer needs to contact bank
• ⛔ Token revoked - Customer cancelled authorization
• ❌ Invalid token - Token was created with other credentials
• 🏦 Bank decline - Various bank-side issues

The API returns only the reason texts listed in "What happens if a recurring charge fails?", so a revoked token or another bank-side refusal comes back as a generic decline.

Solution:

• Implement error handling
• Notify customer with the reason from error_description
• Provide payment update mechanism
• Retry later; after a technical error or a timeout, repeat the request for the same payment request

Authentication errors (401 Unauthorized)

Possible causes:

1. Invalid MAC credentials

   • ✓ Verify MAC ID and Secret
   • ✓ Check for typos or extra spaces

2. Incorrect signature

   • ✓ Check timestamp is current
   • ✓ Verify nonce is unique
   • ✓ Ensure correct HMAC-SHA256 calculation

3. Expired credentials

   • ✓ Regenerate if old
   • ✓ Check project status

4. Wrong host

   • ✓ There is no test environment; send requests to checkout-eu-a.paysera.com

📖 Authentication guide →

How do I handle duplicate callbacks?

Paysera may retry callbacks to ensure delivery.

Implement idempotency:

1. Check if notification_id was already processed
2. If yes, return success without processing again
3. If no, process and mark as handled

Example logic:

// Check if notification already processed
if (await isNotificationProcessed(notification_id)) {
  return { status: 'already_processed' };
}

// Process payment
await processPayment(payment_data);

// Mark as processed
await markNotificationProcessed(notification_id);

This prevents duplicate charges or order fulfillment.

📋 Compliance

Compliance & Legal

Is recurring billing PCI compliant?

Yes! PCI DSS Level 1 compliant.

How it works:

• 🔐 Sensitive card data never touches your servers
• 🏦 Paysera is PCI DSS Level 1 certified
• 🎫 You only store the billing token (not card details)
• ✅ Significantly reduces your PCI compliance scope

Your responsibilities:

• Use HTTPS for all communications
• Secure token storage
• Don't log sensitive data
• Follow security best practices

Do I need customer consent?

Yes! Customer consent is required.

You must:

1. ✅ Clearly disclose it's a recurring subscription
2. ✅ Show billing amount and frequency
3. ✅ Get explicit customer consent before charging
4. ✅ Provide easy cancellation options
5. ✅ Send confirmation emails

Best practices:

• Display terms before checkout
• Require checkbox acceptance
• Send welcome email with details
• Provide self-service cancellation

What about GDPR compliance?

GDPR requirements for recurring billing:

You must:

• 📋 Include recurring billing in privacy policy
• 🗑️ Allow customers to request data deletion
• 📅 Implement data retention policies
• 🔒 Secure all customer data
• 📝 Maintain consent records

Data processing:

• Customer payment details held by Paysera
• You store only non-sensitive tokens
• Customers can revoke consent anytime

Are there geographical restrictions?

Available in most countries where Paysera operates.

Factors affecting availability:

• 🌍 Customer's country
• 💳 Payment method
• ⚖️ Local regulations
• 🏦 Banking infrastructure

Coverage:

• Strong coverage in EU
• Limited in some regions
• Check with Paysera support for specific countries

✨ Best Practices

Support

Need help with complex integrations?

Contact: tech_support@paysera.com

Still have questions?

Can't find an answer to your question?

• 📧 Contact support via your merchant dashboard
• 📖 Browse documentation: Recurring Billing API
• 💬 Check Help Center: Paysera Help