Personal payment source

Spotnana APIs allow you to create payment sources and map them to specific user profiles. This page will explain some important concepts related to personal payment sources.

What’s a personal payment source?

Any payment method that is mapped to a specific user profile on the Spotnana platform is referred to as a personal payment source. The behavior of these payment sources can be configured based on the user’s role. For example, an arranger may want the travelers he arranges travel for to use the credit card that is mapped to his profile.

Host URLs

Use the following host URLs to work with the payment APIs.

• vault.spotnana.com: for creating the personal payment source endpoint.
• api.spotnana.com: for all the other endpoints.

Core concepts

The following are some core concepts you’ll encounter when creating personal payment sources.

• Payment source type: The payment type associated with the payment method. For example, if you’re adding a credit card to a user profile, the paymentSourceInfo > paymentSource > type field in the create personal payment source endpoint will contain CARD as its value.

Note: Currently, the personal payment source APIs only support CARD (i.e., a credit card) as a source type.

• Payment source details: For a credit card, the payment source details include the card network name (e.g., VISA), a custom label, registered address, card number, CVV, and expiration details. The paymentSourceInfo > paymentSource > card object in the create personal payment source API request schema will contain the relevant card details.

Note: Spotnana never stores the card number and CVV information directly in our system. We use secure vault tokens to reference this information and map it to a user profile. As a result, the card number and CVV details cannot be edited after the payment source has been created. If you need to change the card number or CVV you must instead create a new payment source and then delete the older one.

• Travel type: Administrators can set a personal payment source to be available for use only for specific travel booking types (e.g., air, rail, etc.) or to be available for all travel types. When creating a personal payment source, the paymentSourceInfo > filter > travelTypes field in the request can be used to specify the supported travel types.
  
  

• Saving a card to a traveler profile: When creating a personal payment source for a user profile, we would need to save the card on a payment gateway (e.g., Stripe). During this process, the card issuing bank may invoke two-factor authentication (2FA) as part of their 3D secure (3DS) flow. If the 2FA is unsuccessful, the card will be maintained in an INCOMPLETE state on the Spotnana platform.
  
  

• Payment source status: Indicates if all the payment source details have been set for a user. If the paymentSource > status is INCOMPLETE then the payment source needs to be updated to include any missing information (e.g., the address wasn’t entered when creating the payment source). Once the status is ACTIVE, the source can be used for making payments. You can check the status of a created payment source using the get personal payment source for a user endpoint.

  A payment source status can also be INCOMPLETE due to the following reasons:

  • 3D secure (3DS) authentication required: If the underlying payment gateway mandates a 3DS authentication, the status will be marked as INCOMPLETE. In this scenario, when creating a personal payment source, a URL will be returned in the response. Partners can use this URL to complete the 3DS authentication for the card. Alternatively, the card can also be authenticated via the Online Booking Tool (OBT).
    
    
  • Card verification value (CVV) not provided: If the paymentSource > card > cvv field is not provided during the payment source creation, then the status will be set to INCOMPLETE. It is recommended to provide the CVV to enable authentication through the payment gateway, ensuring the card is readily usable.

Managed traveler access

Travel arrangers may sometimes want to use their personal payment source to book for the travelers they manage. This can be set up when you’re creating a payment source for the travel arranger’s user profile. In the request, use the paymentSourceInfo > filter > managedTravelerAccess object to configure it. Refer to the table below for typical scenarios:

  "managedTravelerAccess": {
    "enabled": true,
    "visibility": {
      "showToTravelers": true
    }
  }

  "managedTravelerAccess": {
    "enabled": true,
    "visibility": {
      "showToTravelers": false
    }
  }

Note: The managedTravelerAccess flag is only applicable for user profiles with roleType set to TRAVEL_ARRANGER or COMPANY_TRAVEL_ARRANGER. Use the get user roles endpoint to view a user’s role type. For all other user role types, the managedTravelerAccess > enabled must be set to false.

On the Spotnana platform, an arranger’s role can be one of the following two types:

• A travel arranger: Handles the bookings for travelers assigned to them.
• A company travel arranger: Handles the bookings for all travelers in the company.
  
  

Whether the payment source is visible to the travelers differs based on the arranger’s role type. The following table explains how the arranger role types can impact the visibility of their personal payment source to the managed travelers with whom it has been shared.

  "managedTravelerAccess": {
    "enabled": true,
    "visibility": {
      "showToTravelers": true
    }
  }

  "managedTravelerAccess": {
    "enabled": true,
    "visibility": {
      "showToTravelers": true
    }
  }

  "managedTravelerAccess": {
    "enabled": true,
    "visibility": {
      "showToTravelers": false
    }
  }

  "managedTravelerAccess": {
    "enabled": true,
    "visibility": {
      "showToTravelers": false
    }
  }

The card visibility will also be impacted if the arranger’s role is changed after the personal payment source is created. Here are some scenarios in which an arranger’s role change can impact the card visibility.