# 1. New Card

## Store New Card

<mark style="color:green;">`POST`</mark> `{{Base Adres}}/paywall/card`

{% hint style="info" %}
**Important**: Card transactions are high-security operations. Therefore, you need to send the '**apikeyprivate**' and '**apiclientprivate**' parameters in the 'Header' field.\
\
[<mark style="color:green;">**CardWallAPI Address**</mark>](/payment-orchestration-integration-document/environment.md)
{% endhint %}

**The parameters (HEADERS) that need to be sent to the service are as follows:**

<table><thead><tr><th width="162">Parameter</th><th width="86">Type</th><th width="144">Compulsory </th><th width="403">Description</th></tr></thead><tbody><tr><td>apikeyprivate</td><td>string</td><td>Yes</td><td>The Private Key obtained from the merchant panel.</td></tr><tr><td>apiclientprivate</td><td>string</td><td>Yes</td><td>The Private Client obtained from the merchant panel.</td></tr></tbody></table>

**The parameters (BODY) that need to be sent to the service are as follows:**

<table><thead><tr><th width="217">Parameter</th><th width="95">Type</th><th width="141">Compulsory </th><th width="336">Description</th></tr></thead><tbody><tr><td>RelationalId1</td><td>string</td><td>Yes</td><td>The unique information that the card is to be associated with.</td></tr><tr><td>RelationalId2</td><td>string</td><td>No</td><td>The second unique information that the card is to be associated with (all information should be sent during listing).</td></tr><tr><td>RelationalId3</td><td>string</td><td>No</td><td>The third unique information that the card is to be associated with (all information should be sent during listing).</td></tr><tr><td>Nickname</td><td>string</td><td>Yes</td><td>The nickname of the card (Example: My High Limit Card :))</td></tr><tr><td>HolderName</td><td>string</td><td>Yes</td><td>The name of the cardholder on the card.</td></tr><tr><td>Number</td><td>string</td><td>Yes</td><td>The card number</td></tr><tr><td>Month</td><td>int</td><td>Yes</td><td>The expiration date of the card (month)</td></tr><tr><td>Year</td><td>int</td><td>Yes</td><td>The expiration date of the card (year) - The parameter should be 4 characters.</td></tr><tr><td>IncludeDetails</td><td>boolean</td><td>No</td><td>To get the details of card like Bin, Bank, Type, Brand etc set that parameters as <code>TRUE</code></td></tr></tbody></table>

**An example JSON file to be sent to the service is as follows:**

{% tabs %}
{% tab title="JSON" %}
{% code lineNumbers="true" %}

```json5
{
    "PartnerBased": false,
    "PartnerIdentity": "",
    "RelationalId1": "1000923",
    "RelationalId2": "",
    "RelationalId3": "",
    "Card": {
        "Nickname": "İş bankası kartım",
        "HolderName": "Emir Selim Tütüncü",
        "Number": "4546711234567894",
        "Month": 12,
        "Year": 2026
    },
    "IncludeDetails": true
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

**The parameters returned from the service are as follows:**

<table><thead><tr><th width="189">Parameter</th><th width="129.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>ErrorCode</td><td>int</td><td>Error code. If the transaction is successful, it returns a value of '0'.</td></tr><tr><td>Result</td><td>bool</td><td>It returns either true or false. If the transaction is successful, it returns 'true'.</td></tr><tr><td>Message</td><td>string</td><td>If the transaction is unsuccessful, this is the message specified for the error, providing language support based on the 'locale' parameter.</td></tr><tr><td>Body</td><td>object</td><td>If the transaction is unsuccessful, this is the detail object for the error.</td></tr></tbody></table>

{% tabs %}
{% tab title="JSON" %}
{% code lineNumbers="true" %}

```json
{
    "ErrorCode": 0,
    "Result": true,
    "Message": "",
    "Body": {
        "Name": "İş bankası kartım",
        "CardBin": "444676",
        "CardLastFour": "3623",
        "CardHolderName": "E*i* S*l*m T*t*n*ü",
        "CardNumber": "454671******7894",
        "CardTypeId": 0,
        "CardType": "Visa",
        "Month": 12,
        "Year": 2026,
        "UniqueCode": "hNNqz1Yy2sb59BSKdF1S0pgrwBWvUuNxG8WiVq4T1AgK56FQljAlKQ==",
        "Details": {
            "CardBankId": 53,
            "CardBank": "T.C.ZİRAAT BANKASI A.Ş.",
            "CardBrandId": 2,
            "CardBrand": "Visa",
            "CardFamilyId": 7,
            "CardFamily": "Combo",
            "CardKindId": 1,
            "CardKind": "Bireysel Kart",
            "CardTypeId": 1,
            "CardType": "Credit"
        }
    }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.paywall.one/payment-orchestration-integration-document/card-storage-service/card-saving/1.-new-card.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.