Add a credit/debit card for a guest

Overview

This API helps you to add a credit card or debit card for a guest, allowing them to save payment methods for future transactions.

Endpoint: POST /api/v1/guests/{guest_id}/accounts

🔐 Prerequisites

Valid API authentication
Guest must exist in the system
User must have appropriate permissions (Add or Edit on Guests object)

Key Information

Card Storage: This API enables guests to securely save their payment methods for future use
Hosted Collection: The system will always return a hosted payment URI to collect card details securely
Redirect URI: Always include redirect_uri for proper redirection flow after card addition
Source Tracking: The source parameter helps track where the card is being added from:
- 1 for WebStore (default)
- 5 for Mobile
Billing Information: Required for card storage when AVS (Address Verification Service) is enabled
Validation: The API validates guest existence, user permissions, and payment processor configuration before processing

Request Structure

{
  "center_id": "ad3feb5f-40e2-4075-8f8f-5f40ef1ed697",
  "redirect_uri": "https://example.com/card-added-success",
  "billing_info": null,
  "source": 1
}

Billing Info Structure

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "country_code": "US",
  "address": "123 Main St",
  "state": "CA",
  "zipcode": "90210",
  "city": "Beverly Hills",
  "phone": "+1-555-123-4567"
}

Response Structure

Success Response

{
  "success": true,
  "error": null,
  "hosted_payment_uri": "https://secure-payment.zenoti.com/add-card?token=550e8400-e29b-41d4-a716-446655440124&redirect=https%3A%2F%2Fexample.com%2Fcard-added-success",
  "token_id": "550e8400-e29b-41d4-a716-446655440124"
}

Error Response

{
  "success": false,
  "error": {
    "code": 400,
    "message": "Guest not found"
  }
}

Use Cases

💳 Use Case : Add Payment Method for Guest

Scenario: A guest wants to save a new credit card to their profile for future payments.

Request Body:

{
  "center_id": "ad3feb5f-40e2-4075-8f8f-5f40ef1ed697",
  "redirect_uri": "https://example.com/card-added-success",
  "source": 1
}

Response:

{
  "success": true,
  "error": null,
  "hosted_payment_uri": "https://secure-payment.zenoti.com/add-card?token=550e8400-e29b-41d4-a716-446655440124&redirect=https%3A%2F%2Fexample.com%2Fcard-added-success",
  "token_id": "550e8400-e29b-41d4-a716-446655440124"
}

Response Details:

When adding new payment methods, the API always returns:

hosted_payment_uri: This field contains a URL to a secure hosted payment page where the guest can safely enter their card details. You must redirect the guest to this URL to complete the card addition process.
token_id: A unique session token that maintains the card addition session state during the hosted payment flow.

Implementation Flow:

Initial Request: Send card addition request with center_id and redirect_uri
Hosted Payment Response: API returns hosted_payment_uri for secure card collection
Guest Redirect: Redirect guest's browser to the hosted_payment_uri
Card Collection: Guest enters their card details on the secure hosted page
Card Storage: System securely stores the payment method for the guest
Return: After successful card addition, guest is redirected back to your redirect_uri
Completion: The card is now available for future payments

Important Notes:

The hosted_payment_uri is always provided for secure card collection
No payment account ID is returned in the initial response as the card hasn't been stored yet
Always redirect guests to the hosted_payment_uri to collect card details securely
The redirect_uri parameter is mandatory for all transactions
Card details are stored securely after successful collection
The saved card will be available for future payment transactions

Common Error Responses

AVS Verification Failed

{
  "success": false,
  "error": {
    "code": 400,
    "message": "Transaction failed due to an incorrect billing address. Please update the postal code and try again."
  }
}

Guest Not Found

{
  "success": false,
  "error": {
    "code": 404,
    "message": "Guest not found"
  }
}

Invalid Center ID

{
  "success": false,
  "error": {
    "code": 400,
    "message": "Invalid center id"
  }
}

Missing Redirect URI

{
  "success": false,
  "error": {
    "code": 400,
    "message": "redirect_uri is required"
  }
}

Payment Configuration Not Found

{
  "success": false,
  "error": {
    "code": 400,
    "message": "Payment configuration not done"
  }
}

User Not Authorized

{
  "success": false,
  "error": {
    "code": 403,
    "message": "User not authorized"
  }
}

Duplicate Card

{
  "success": false,
  "error": {
    "code": 400,
    "message": "Payment method already exists"
  }
}

💡 Implementation Notes

Card Storage: This API is designed specifically for adding and storing payment methods to a guest's profile
Mandatory Redirect URI: Always include redirect_uri as it's required for the hosted payment flow
Hosted Payment Flow: The system will redirect guests to a secure hosted payment page to enter their card details
No Immediate Account ID: The response does not include a payment account ID because card storage occurs after collection
Billing Information: Include billing details when AVS verification is required by the payment processor
Future Use: Saved cards can be used in payment APIs by referencing the generated account ID
Asynchronous Processing: Card storage is processed after details are collected on the hosted page
Security: All card data is handled securely through PCI-compliant hosted payment pages
Multi-Platform Support: Cards saved from any platform can be used across web and mobile applications

This API provides a secure and user-friendly way for guests to save their payment methods for convenient future transactions.