> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywithatoa.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Payment Method

> Update payment method via the Atoa Payment Methods API, request parameters, response schema and code samples in cURL, Python, JavaScript, PHP, Go and Java.

Update a saved payment method. Today this updates the card's metadata — supply only the metadata you want to change.

### Authorization

Bearer `<accessSecret>`

**Path Parameters**

<ParamField path="customerId" type="string" required>
  The customer UUID who owns the card.
</ParamField>

<ParamField path="cardId" type="string" required>
  The card identifier to update.
</ParamField>

**Request Body Schema**

<ParamField body="metadata" type="object">
  Set of key-value pairs to attach to the saved card. Supplied keys are merged into the card's existing metadata: a key is added or overwritten, and setting a key to an empty string (`""`) removes it. Keys you don't include are left unchanged.

  * Up to **50** key-value pairs.
  * Each key must be **1–40** characters and must not contain `[` or `]`.
  * Each value must be a **string** of at most **500** characters.
</ParamField>

**Response**

Returns the updated saved card object.

<ResponseField name="id" type="string">
  Card identifier.
</ResponseField>

<ResponseField name="name" type="string">
  Cardholder name.
</ResponseField>

<ResponseField name="type" type="string">
  Card type (e.g., `credit`, `debit`).
</ResponseField>

<ResponseField name="lastFourDigits" type="string">
  Last 4 digits of the card number.
</ResponseField>

<ResponseField name="category" type="string">
  Card category.
</ResponseField>

<ResponseField name="cardType" type="string">
  Card type (e.g., `DEBIT`, `CREDIT`, `PREPAID`).
</ResponseField>

<ResponseField name="brand" type="string">
  Card network brand (e.g., `VISA`, `MASTERCARD`).
</ResponseField>

<ResponseField name="country" type="string">
  Card issuing country code.
</ResponseField>

<ResponseField name="expiryDate" type="string">
  Card expiry date in `MM/YYYY` format.
</ResponseField>

<ResponseField name="metadata" type="object">
  The key/value string pairs attached to the card after the update.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of when the card was saved.
</ResponseField>

<RequestExample>
  ```bash curl theme={null}
  curl --request PUT \
    --url https://api.atoa.me/api/customers/{customerId}/cards/{cardId} \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
    "metadata": { "internalId": "42", "legacyRef": "" }
  }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.atoa.me/api/customers/{customerId}/cards/{cardId}"
  payload = {
      "metadata": {"internalId": "42", "legacyRef": ""}
  }
  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
  }

  response = requests.put(url, json=payload, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.atoa.me/api/customers/{customerId}/cards/{cardId}",
    {
      method: "PUT",
      headers: {
        Authorization: "Bearer <token>",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        metadata: { internalId: "42", legacyRef: "" },
      }),
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```php PHP theme={null}
  <?php

  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.atoa.me/api/customers/{customerId}/cards/{cardId}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_POSTFIELDS => json_encode([
      "metadata" => ["internalId" => "42", "legacyRef" => ""]
    ]),
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer <token>",
      "Content-Type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  curl_close($curl);
  echo $response;
  ```

  ```go Go theme={null}
  package main

  import (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
  )

  func main() {
    url := "https://api.atoa.me/api/customers/{customerId}/cards/{cardId}"
    payload := strings.NewReader(`{
      "metadata": { "internalId": "42", "legacyRef": "" }
    }`)

    req, _ := http.NewRequest("PUT", url, payload)
    req.Header.Add("Authorization", "Bearer <token>")
    req.Header.Add("Content-Type", "application/json")

    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)
    fmt.Println(string(body))
  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.put("https://api.atoa.me/api/customers/{customerId}/cards/{cardId}")
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .body("{\"metadata\":{\"internalId\":\"42\",\"legacyRef\":\"\"}}")
    .asString();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "card_abc123def456",
    "name": "John Doe",
    "type": "credit",
    "lastFourDigits": "4242",
    "category": "consumer",
    "cardType": "DEBIT",
    "brand": "VISA",
    "country": "GB",
    "expiryDate": "12/2027",
    "metadata": { "internalId": "42" },
    "createdAt": "2025-06-15T10:30:00.000Z"
  }
  ```

  ```json 400 theme={null}
  {
    "name": "BAD_REQUEST",
    "message": "metadata keys must be 40 characters or less.",
    "status": 400,
    "errors": []
  }
  ```

  ```json 404 theme={null}
  {
    "name": "NOT_FOUND",
    "message": "Card not found",
    "status": 404,
    "errors": []
  }
  ```
</ResponseExample>