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

# Payment Methods API — list and manage saved cards

> List, retrieve, detach, and set a default payment method for a customer — supporting cards, Apple Pay, Google Pay, and bank invoices.

A payment method represents a saved payment instrument attached to a customer. Payment methods are created when a customer completes checkout with `save_payment_method: true`. Use these endpoints to list, retrieve, detach, or set a default method on the customer.

**Supported types**

| Type           | Description                |
| -------------- | -------------------------- |
| `card`         | Credit or debit card.      |
| `apple_pay`    | Apple Pay wallet.          |
| `google_pay`   | Google Pay wallet.         |
| `bank_invoice` | Bank invoice (gíróseðill). |

***

## List payment methods

`GET /v1/payment_methods`

Returns a paginated list of payment methods for a customer.

### Query parameters

<ParamField query="customer" type="string">
  Filter by customer ID. Recommended — without this filter the endpoint returns methods across all customers on your merchant account.
</ParamField>

<ParamField query="starting_after" type="string">
  Cursor for pagination. Pass the `id` of the last payment method from the previous page to retrieve the next page.
</ParamField>

<ParamField query="limit" type="number">
  Maximum number of payment methods to return per page.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.borga.is/v1/payment_methods?customer=cus_abc123&limit=20" \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx"
  ```
</RequestExample>

### Response fields

<ResponseField name="data" type="object[]" required>
  Array of payment method objects.

  <Expandable title="payment method fields">
    <ResponseField name="id" type="string" required>
      Unique payment method identifier.
    </ResponseField>

    <ResponseField name="customer" type="string" required>
      ID of the customer this method belongs to.
    </ResponseField>

    <ResponseField name="type" type="string" required>
      Payment method type. One of `card`, `apple_pay`, `google_pay`, `bank_invoice`.
    </ResponseField>

    <ResponseField name="card" type="object">
      Card details. Present when `type` is `card`, `apple_pay`, or `google_pay`.

      <Expandable title="card fields">
        <ResponseField name="brand" type="string" required>
          Card network (e.g. `visa`, `mastercard`, `amex`).
        </ResponseField>

        <ResponseField name="last4" type="string" required>
          Last four digits of the card number.
        </ResponseField>

        <ResponseField name="exp_month" type="number" required>
          Two-digit expiry month (1–12).
        </ResponseField>

        <ResponseField name="exp_year" type="number" required>
          Four-digit expiry year.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      ISO 8601 creation timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="has_more" type="boolean" required>
  Whether more payment methods exist beyond this page.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "pm_01hxa8w2qkfr5nt9vcj3dl7mbe",
        "customer": "cus_abc123",
        "type": "card",
        "card": {
          "brand": "visa",
          "last4": "4242",
          "exp_month": 12,
          "exp_year": 2028
        },
        "created_at": "2026-04-29T09:00:00Z"
      }
    ],
    "has_more": false
  }
  ```
</ResponseExample>

***

## Retrieve a payment method

`GET /v1/payment_methods/{id}`

Retrieves the details of a single payment method.

### Path parameters

<ParamField path="id" type="string" required>
  The ID of the payment method to retrieve.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.borga.is/v1/payment_methods/pm_01hxa8w2qkfr5nt9vcj3dl7mbe \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx"
  ```
</RequestExample>

### Response fields

<ResponseField name="id" type="string" required>
  Unique payment method identifier.
</ResponseField>

<ResponseField name="customer" type="string" required>
  ID of the customer this method belongs to.
</ResponseField>

<ResponseField name="type" type="string" required>
  Payment method type. One of `card`, `apple_pay`, `google_pay`, `bank_invoice`.
</ResponseField>

<ResponseField name="card" type="object">
  Card details. Present when `type` is `card`, `apple_pay`, or `google_pay`.

  <Expandable title="card fields">
    <ResponseField name="brand" type="string" required>
      Card network (e.g. `visa`, `mastercard`, `amex`).
    </ResponseField>

    <ResponseField name="last4" type="string" required>
      Last four digits of the card number.
    </ResponseField>

    <ResponseField name="exp_month" type="number" required>
      Two-digit expiry month (1–12).
    </ResponseField>

    <ResponseField name="exp_year" type="number" required>
      Four-digit expiry year.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp of when the payment method was saved.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "pm_01hxa8w2qkfr5nt9vcj3dl7mbe",
    "customer": "cus_abc123",
    "type": "card",
    "card": {
      "brand": "visa",
      "last4": "4242",
      "exp_month": 12,
      "exp_year": 2028
    },
    "created_at": "2026-04-29T09:00:00Z"
  }
  ```
</ResponseExample>

***

## Detach a payment method

`DELETE /v1/payment_methods/{id}`

Detaches a payment method from its customer. Once detached, the method can no longer be used for future payments. This action is irreversible.

### Path parameters

<ParamField path="id" type="string" required>
  The ID of the payment method to detach.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url https://api.borga.is/v1/payment_methods/pm_01hxa8w2qkfr5nt9vcj3dl7mbe \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx"
  ```
</RequestExample>

### Response fields

<ResponseField name="id" type="string" required>
  ID of the detached payment method.
</ResponseField>

<ResponseField name="deleted" type="boolean" required>
  Always `true` on a successful detach response.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "pm_01hxa8w2qkfr5nt9vcj3dl7mbe",
    "deleted": true
  }
  ```
</ResponseExample>

***

## Set default payment method

`POST /v1/payment_methods/{id}/set_default`

Sets a payment method as the default for the associated customer. The default method is used automatically for recurring charges and subscription renewals.

### Path parameters

<ParamField path="id" type="string" required>
  The ID of the payment method to set as default.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.borga.is/v1/payment_methods/pm_01hxa8w2qkfr5nt9vcj3dl7mbe/set_default \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx"
  ```
</RequestExample>

### Response fields

<ResponseField name="id" type="string" required>
  Unique payment method identifier.
</ResponseField>

<ResponseField name="customer" type="string" required>
  ID of the customer this method belongs to.
</ResponseField>

<ResponseField name="type" type="string" required>
  Payment method type. One of `card`, `apple_pay`, `google_pay`, `bank_invoice`.
</ResponseField>

<ResponseField name="card" type="object">
  Card details. Present when `type` is `card`, `apple_pay`, or `google_pay`.

  <Expandable title="card fields">
    <ResponseField name="brand" type="string" required>
      Card network (e.g. `visa`, `mastercard`, `amex`).
    </ResponseField>

    <ResponseField name="last4" type="string" required>
      Last four digits of the card number.
    </ResponseField>

    <ResponseField name="exp_month" type="number" required>
      Two-digit expiry month (1–12).
    </ResponseField>

    <ResponseField name="exp_year" type="number" required>
      Four-digit expiry year.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp of when the payment method was saved.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "pm_01hxa8w2qkfr5nt9vcj3dl7mbe",
    "customer": "cus_abc123",
    "type": "card",
    "card": {
      "brand": "visa",
      "last4": "4242",
      "exp_month": 12,
      "exp_year": 2028
    },
    "created_at": "2026-04-29T09:00:00Z"
  }
  ```
</ResponseExample>