# Add a Card
source: https://developer.mastercard.com/donations/documentation/use-cases/manage-cards/add-a-card/index.md

## Overview {#overview}

The **Add Card** endpoint adds a new payment card to a donor profile registered in Mastercard Donate. Adding a card-on-file allows you to associate the card details securely with a donor for future transactions.

To add a card, provide the unique `donorId` as the endpoint path parameter. A successful request returns the `HTTP 200 Created` status and a JSON response body that includes the unique `card_id` and the **last four digits** of the Primary Account Number (PAN).

A card is only added once. For subsequent requests, the initial `card_id` is returned.
Tip: **Design Guidelines**   

<br />


To ensure a secure, intuitive, and user-friendly experience when cardholders select their payment card, follow these key design principles:

* Show a masked version of the Payment Account Number (PAN) to help donors identify their card while maintaining privacy and security.
* Prevent cardholders from proceeding until they have explicitly accepted your Terms and Conditions and Privacy Policy.
* Set a payment card as default. If the cardholder enrolls only one payment card, then this card should automatically be the default card.
* Use clear visual indicators to show which card is currently the default card.
* Enable donors to change the default card if they enroll more than one card.

## Sequence Diagram {#sequence-diagram}

The following outlines the sequence of events:
Diagram add-a-card

## Execution Steps {#execution-steps}

The following details the steps in the above sequence diagram:

1. The donor chooses to register a card and requests the partner user interface to display the add card screen.
2. The partner user interface displays the add card screen to the donor.
3. The donor enters the card details in the form displayed by the partner user interface.
4. The partner user interface forwards the card data to the partner server to further process it.
5. The partner server invokes the `POST /donors/{donor_id}/cards` endpoint and provides the card data in the endpoint request to the Mastercard Donate service.
6. The Mastercard Donate service verifies the donor identifier.
7. The Mastercard Donate service verifies the card primary account number (PAN) for uniqueness if it finds the donor.
8. The Mastercard Donate service processes the data, stores it, and generates a unique `card_id` if it does not find a duplicate PAN.
9. The Mastercard Donate service returns the `card_id` to the partner server.
10. The partner server stores the `card_id`.
11. The partner server sends the registered card details and its unique `card_id` to the partner user interface.
12. The partner server also sends a confirmation to the donor that the card registration was successful.
13. The Mastercard Donate service sends an error message to the partner server if it finds a duplicate PAN.
14. The partner server forwards the error message to the partner user interface.
15. The partner user interface displays the error message to the donor.
16. The Mastercard Donate service sends an error message to the partner server if it does not find the donor.
17. The partner server forwards the error message to the partner user interface.
18. The partner user interface displays the error message to the donor.

## Endpoint {#endpoint}


API Reference: `POST /donors/{donor_id}/cards`

## Endpoint Parameter {#endpoint-parameter}

For more details on the endpoint parameters, refer to the [Parameters to Add a Card](https://developer.mastercard.com/donations/documentation/parameters/manage-cards-param/add-card-param/index.md) section.

## Sample Request and Response {#sample-request-and-response}

For more details, refer to the [Add a Card](https://developer.mastercard.com/donations/tutorial/donation-api-details/cardsapinew/index.md) tutorial.