# 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.
For example, a credit card (personal or corporate) added to a user's profile is considered 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](/spotnana/personal_payment_creation).

- **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](/openapi/paymentsapi#operation/createpersonalpaymentsource) endpoint
will contain `CARD` as its value.


> **Note:** Currently, the [personal payment source](/openapi/paymentsapi#operation/personal-payment-sources) 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](/openapi/paymentsapi#operation/createpersonalpaymentsource) 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](/spotnana/personal_payment_creation) and
then [delete](/spotnana/personal_payment_deletion) 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](/spotnana/personal_payment_creation) 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](/spotnana/personal_payment_updation) 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](/openapi/paymentsapi#operation/getpersonalpaymentsource) 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](/spotnana/personal_payment_creation),
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](/spotnana/personal_payment_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](/spotnana/personal_payment_creation) 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:

| Scenario  | How to configure it? |
|  --- | --- |
| An arranger wants to display their personal payment source to all their managed travelers.
When travelers are creating a booking they will be able to see and use the arranger’s payment source. | 
```
  "managedTravelerAccess": {
    "enabled": true,
    "visibility": {
      "showToTravelers": true
    }
  }
```
 |
| An arranger wants to use their personal payment source to create bookings
on behalf of their managed travelers. However, they don’t
want managed travelers to be able to use their payment source or view its details. | 
```json
  "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](/openapi/usersapi#operation/getuserroles) 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.

| Role  | Configuration  | Shared card visibility  |
|  --- | --- | --- |
| `TRAVEL_ARRANGER` | 
```json
  "managedTravelerAccess": {
    "enabled": true,
    "visibility": {
      "showToTravelers": true
    }
  }
```
 | The travelers managed by the arranger can use the shared card during checkout. |
| `COMPANY_TRAVEL_ARRANGER` | 
```json
  "managedTravelerAccess": {
    "enabled": true,
    "visibility": {
      "showToTravelers": true
    }
  }
```
 | All travelers in the company can use the arranger’s shared card during checkout. |
| `TRAVEL_ARRANGER` | 
```json
  "managedTravelerAccess": {
    "enabled": true,
    "visibility": {
      "showToTravelers": false
    }
  }
```
 | The travel arranger can use their card to create bookings on behalf of their managed travelers. |
| `COMPANY_TRAVEL_ARRANGER` | 
```json
  "managedTravelerAccess": {
    "enabled": true,
    "visibility": {
      "showToTravelers": false
    }
  }
```
 | The travel arranger can use their card to create bookings on behalf of all the travelers in the company. |


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.

| Role change  | Shared card’s visibility after the role change  |
|  --- | --- |
| From `TRAVEL_ARRANGER` to `COMPANY_TRAVEL_ARRANGER` | The arranger’s card is now shared with all travelers in the company. |
| From `COMPANY_TRAVEL_ARRANGER` to `TRAVEL_ARRANGER` | The arranger’s card is now shared with only the travelers managed by the arranger. |
| From `TRAVEL_ARRANGER` or `COMPANY_TRAVEL_ARRANGER` to a non-arranger role | If a user is no longer a travel arranger, their personal card can only be accessed and used by them. |