Retrieve the saved credit/debit cards of a guest

Overview

This API enables you to retrieve the saved credit or debit cards of a guest. Supply guest_id and center_id to this API and it fetches the active payment accounts of the guest.

Endpoint: GET /api/v1/guests/{guest_id}/accounts?center_id={center_id}

🔐 Prerequisites

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

Key Information

• Guest Identification: The guest_id must be a valid 32-character GUID of an existing guest.

• Center Context: The center_id determines which center's payment accounts to retrieve for the guest.

• Active Accounts Only: The API returns only active payment accounts that can be used for transactions.

• Card Security: For security reasons, only partial card information (last four digits, brand, expiry) is returned.

• Account Selection: The returned account_id values can be used in payment APIs to charge specific saved cards.

• Cross-Center Access: Guests may have different saved cards at different centers within the same organization.

Request Structure

No request body is required. All parameters are provided in the URL path and query string.

Response Structure

Success Response

[
  {
    "account_id": "11ADA4D4-5FC9-46D4-8CB6-B1C532DB4CC4",
    "card_logo": "visa",
    "last_four": "1234",
    "expiry_on": "12/25"
  },
  {
    "account_id": "22BDB5E5-6FD0-57E5-9DC7-C2D643EC5DD5",
    "card_logo": "mastercard", 
    "last_four": "5678",
    "expiry_on": "08/26"
  }
]

Error Response

{
  "error": {
    "code": 502,
    "message": "Guest Id not found."
  }
}

Response Details

Use Cases

🔍 Use Case : Get Saved Cards for Payment Selection

Scenario: A guest wants to see their saved payment methods before making an invoice payment.

Endpoint: GET /api/v1/guests/550e8400-e29b-41d4-a716-446655440000/accounts?center_id=ad3feb5f-40e2-4075-8f8f-5f40ef1ed697

Response:

[
  {
    "account_id": "11ADA4D4-5FC9-46D4-8CB6-B1C532DB4CC4",
    "card_logo": "visa",
    "last_four": "1234", 
    "expiry_on": "12/25"
  },
  {
    "account_id": "22BDB5E5-6FD0-57E5-9DC7-C2D643EC5DD5",
    "card_logo": "mastercard",
    "last_four": "5678",
    "expiry_on": "08/26"
  }
]

Common Error Responses

Guest Not Found

{
  "error": {
    "code": 502,
    "message": "Guest Id not found."
  }
}

Center Not Found

{
  "error": {
    "code": 502,
    "message": "Center Id not found."
  }
}

Access Denied

{
  "error": {
    "code": 438,
    "message": "cannot access."
  }
}

User Not Authorized

{
  "error": {
    "code": 438,
    "message": "UserNotAuthorized, The request does not have authenticated user."
  }
}

💡 Implementation Notes

• Security: Only masked card information is returned for PCI compliance.

• Account Selection: Use the returned account_id in payment APIs to charge specific saved cards.

• Center Context: Payment accounts may vary between different centers for the same guest.

• Empty Results: If no saved cards exist, an empty array [] is returned.

• Expired Cards: The API typically returns only active, non-expired payment methods.

• Performance: This is a lightweight API suitable for real-time card selection interfaces.

• Integration: Commonly used before invoice payment APIs to display available payment options.