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

# Manage Payment Methods

> List, retrieve, and revoke saved payment methods and view payment history.

Compago provides a full set of endpoints for managing your saved payment methods and their associated payments. You can list all payment methods, retrieve details for a specific one, revoke cards you no longer need, and view the payment history for any saved card.

## List Payment Methods

Retrieve a paginated list of all payment methods in your organization.

### Endpoint

```
GET /api/payment-method
```

**API reference:** [`GET /payment-method`](/api-reference/payment-method/list)

### Query Parameters

<ParamField query="status" type="string">
  Filter by payment method status: `PENDING`, `ACTIVE`, `EXPIRED`, or `REVOKED`.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for pagination.
</ParamField>

<ParamField query="pageSize" type="integer" default="100">
  Number of items per page (max 500).
</ParamField>

### Response

```json theme={null}
{
  "count": 25,
  "page": 1,
  "pageSize": 100,
  "items": [
    {
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "status": "ACTIVE",
      "externalId": "customer_12345",
      "card": {
        "lastFourDigits": "4242",
        "networkType": "VISA"
      },
      "createdAt": "2025-01-15T10:30:00Z"
    },
    {
      "id": "ffffffff-gggg-hhhh-iiii-jjjjjjjjjjjj",
      "status": "REVOKED",
      "externalId": "customer_67890",
      "card": {
        "lastFourDigits": "1234",
        "networkType": "MASTERCARD"
      },
      "createdAt": "2025-01-10T08:15:00Z"
    }
  ]
}
```

### Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  # List all active payment methods
  curl "https://api.harmony.compago.com/api/payment-method?status=ACTIVE&page=1&pageSize=50" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.harmony.compago.com/api/payment-method?status=ACTIVE&page=1&pageSize=50',
    {
      headers: { 'x-api-key': process.env.COMPAGO_API_KEY }
    }
  );

  const { count, items } = await response.json();
  console.log(`Found ${count} active payment methods`);
  items.forEach(pm => {
    console.log(`${pm.id} - ${pm.card?.networkType} ****${pm.card?.lastFourDigits}`);
  });
  ```

  ```python Python theme={null}
  response = requests.get(
      'https://api.harmony.compago.com/api/payment-method',
      params={'status': 'ACTIVE', 'page': 1, 'pageSize': 50},
      headers={'x-api-key': os.environ['COMPAGO_API_KEY']}
  )

  data = response.json()
  print(f"Found {data['count']} active payment methods")
  for pm in data['items']:
      card = pm.get('card', {})
      print(f"{pm['id']} - {card.get('networkType')} ****{card.get('lastFourDigits')}")
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://api.harmony.compago.com/api/payment-method?status=ACTIVE&page=1&pageSize=50');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'x-api-key: ' . getenv('COMPAGO_API_KEY')
  ]);

  $response = curl_exec($ch);
  $data = json_decode($response, true);
  curl_close($ch);

  echo "Found {$data['count']} active payment methods" . PHP_EOL;
  foreach ($data['items'] as $pm) {
      $card = $pm['card'] ?? [];
      echo "{$pm['id']} - {$card['networkType']} ****{$card['lastFourDigits']}" . PHP_EOL;
  }
  ?>
  ```

  ```ruby Ruby theme={null}
  uri = URI('https://api.harmony.compago.com/api/payment-method?status=ACTIVE&page=1&pageSize=50')
  request = Net::HTTP::Get.new(uri)
  request['x-api-key'] = ENV['COMPAGO_API_KEY']

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
  data = JSON.parse(response.body)

  puts "Found #{data['count']} active payment methods"
  data['items'].each do |pm|
    card = pm['card'] || {}
    puts "#{pm['id']} - #{card['networkType']} ****#{card['lastFourDigits']}"
  end
  ```
</CodeGroup>

## Get Payment Method Details

Retrieve the full details of a specific payment method.

### Endpoint

```
GET /api/payment-method/{id}
```

**API reference:** [`GET /payment-method/{id}`](/api-reference/payment-method/get)

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the payment method (UUID).
</ParamField>

### Response

```json theme={null}
{
  "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "status": "ACTIVE",
  "externalId": "customer_12345",
  "card": {
    "lastFourDigits": "4242",
    "networkType": "VISA"
  },
  "createdAt": "2025-01-15T10:30:00Z"
}
```

### Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.harmony.compago.com/api/payment-method/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    `https://api.harmony.compago.com/api/payment-method/${paymentMethodId}`,
    {
      headers: { 'x-api-key': process.env.COMPAGO_API_KEY }
    }
  );

  const paymentMethod = await response.json();
  console.log('Status:', paymentMethod.status);
  console.log('Card:', paymentMethod.card?.networkType, '****' + paymentMethod.card?.lastFourDigits);
  ```

  ```python Python theme={null}
  response = requests.get(
      f'https://api.harmony.compago.com/api/payment-method/{payment_method_id}',
      headers={'x-api-key': os.environ['COMPAGO_API_KEY']}
  )

  pm = response.json()
  print(f"Status: {pm['status']}")
  card = pm.get('card', {})
  print(f"Card: {card.get('networkType')} ****{card.get('lastFourDigits')}")
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.harmony.compago.com/api/payment-method/{$paymentMethodId}");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'x-api-key: ' . getenv('COMPAGO_API_KEY')
  ]);

  $response = curl_exec($ch);
  $pm = json_decode($response, true);
  curl_close($ch);

  echo "Status: {$pm['status']}" . PHP_EOL;
  echo "Card: {$pm['card']['networkType']} ****{$pm['card']['lastFourDigits']}" . PHP_EOL;
  ?>
  ```

  ```ruby Ruby theme={null}
  uri = URI("https://api.harmony.compago.com/api/payment-method/#{payment_method_id}")
  request = Net::HTTP::Get.new(uri)
  request['x-api-key'] = ENV['COMPAGO_API_KEY']

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
  pm = JSON.parse(response.body)

  puts "Status: #{pm['status']}"
  card = pm['card'] || {}
  puts "Card: #{card['networkType']} ****#{card['lastFourDigits']}"
  ```
</CodeGroup>

## Revoke a Payment Method

Permanently revoke a saved payment method. Once revoked, the card can no longer be charged.

### Endpoint

```
DELETE /api/payment-method/{id}
```

**API reference:** [`DELETE /payment-method/{id}`](/api-reference/payment-method/revoke)

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the payment method to revoke (UUID).
</ParamField>

<Warning>
  **This action is permanent.** Once a payment method is revoked, it cannot be reactivated. You will need to create a new payment method and have the customer save their card again.
</Warning>

### Response

```json theme={null}
{
  "success": true
}
```

### Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api.harmony.compago.com/api/payment-method/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    `https://api.harmony.compago.com/api/payment-method/${paymentMethodId}`,
    {
      method: 'DELETE',
      headers: { 'x-api-key': process.env.COMPAGO_API_KEY }
    }
  );

  const result = await response.json();
  console.log('Revoked:', result.success);
  ```

  ```python Python theme={null}
  response = requests.delete(
      f'https://api.harmony.compago.com/api/payment-method/{payment_method_id}',
      headers={'x-api-key': os.environ['COMPAGO_API_KEY']}
  )

  result = response.json()
  print('Revoked:', result['success'])
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.harmony.compago.com/api/payment-method/{$paymentMethodId}");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'x-api-key: ' . getenv('COMPAGO_API_KEY')
  ]);

  $response = curl_exec($ch);
  $result = json_decode($response, true);
  curl_close($ch);

  echo 'Revoked: ' . ($result['success'] ? 'true' : 'false') . PHP_EOL;
  ?>
  ```

  ```ruby Ruby theme={null}
  uri = URI("https://api.harmony.compago.com/api/payment-method/#{payment_method_id}")
  request = Net::HTTP::Delete.new(uri)
  request['x-api-key'] = ENV['COMPAGO_API_KEY']

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
  result = JSON.parse(response.body)

  puts "Revoked: #{result['success']}"
  ```
</CodeGroup>

## List Payments for a Payment Method

Retrieve a paginated list of all payments (charges) made against a specific payment method.

### Endpoint

```
GET /api/payment-method/{id}/payment
```

**API reference:** [`GET /payment-method/{id}/payment`](/api-reference/payment-method/list-payments)

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the payment method (UUID).
</ParamField>

### Query Parameters

<ParamField query="status" type="string">
  Filter by payment status: `NOT_INITIALIZED`, `PENDING`, `CONFIRMED`, `CANCELLED`, or `REFUNDED`.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for pagination.
</ParamField>

<ParamField query="pageSize" type="integer" default="100">
  Number of items per page (max 500).
</ParamField>

### Response

```json theme={null}
{
  "count": 10,
  "page": 1,
  "pageSize": 100,
  "items": [
    {
      "id": "11111111-2222-3333-4444-555555555555",
      "status": "CONFIRMED",
      "amount": 500,
      "currency": "MXN",
      "createdAt": "2025-02-01T12:00:00Z"
    },
    {
      "id": "66666666-7777-8888-9999-000000000000",
      "status": "REFUNDED",
      "amount": 250,
      "currency": "MXN",
      "createdAt": "2025-01-15T09:30:00Z"
    }
  ]
}
```

### Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.harmony.compago.com/api/payment-method/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/payment?status=CONFIRMED&page=1" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    `https://api.harmony.compago.com/api/payment-method/${paymentMethodId}/payment?status=CONFIRMED&page=1`,
    {
      headers: { 'x-api-key': process.env.COMPAGO_API_KEY }
    }
  );

  const { count, items } = await response.json();
  console.log(`Found ${count} confirmed payments`);
  items.forEach(p => {
    console.log(`${p.id} - $${p.amount} ${p.currency} - ${p.status}`);
  });
  ```

  ```python Python theme={null}
  response = requests.get(
      f'https://api.harmony.compago.com/api/payment-method/{payment_method_id}/payment',
      params={'status': 'CONFIRMED', 'page': 1},
      headers={'x-api-key': os.environ['COMPAGO_API_KEY']}
  )

  data = response.json()
  print(f"Found {data['count']} confirmed payments")
  for p in data['items']:
      print(f"{p['id']} - ${p['amount']} {p['currency']} - {p['status']}")
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.harmony.compago.com/api/payment-method/{$paymentMethodId}/payment?status=CONFIRMED&page=1");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'x-api-key: ' . getenv('COMPAGO_API_KEY')
  ]);

  $response = curl_exec($ch);
  $data = json_decode($response, true);
  curl_close($ch);

  echo "Found {$data['count']} confirmed payments" . PHP_EOL;
  foreach ($data['items'] as $p) {
      echo "{$p['id']} - \${$p['amount']} {$p['currency']} - {$p['status']}" . PHP_EOL;
  }
  ?>
  ```

  ```ruby Ruby theme={null}
  uri = URI("https://api.harmony.compago.com/api/payment-method/#{payment_method_id}/payment?status=CONFIRMED&page=1")
  request = Net::HTTP::Get.new(uri)
  request['x-api-key'] = ENV['COMPAGO_API_KEY']

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
  data = JSON.parse(response.body)

  puts "Found #{data['count']} confirmed payments"
  data['items'].each do |p|
    puts "#{p['id']} - $#{p['amount']} #{p['currency']} - #{p['status']}"
  end
  ```
</CodeGroup>

## Get Payment Details

Retrieve the details of a specific payment made against a payment method.

### Endpoint

```
GET /api/payment-method/{id}/payment/{paymentId}
```

**API reference:** [`GET /payment-method/{id}/payment/{paymentId}`](/api-reference/payment-method/get-payment)

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the payment method (UUID).
</ParamField>

<ParamField path="paymentId" type="string" required>
  The unique identifier of the payment (UUID).
</ParamField>

### Response

```json theme={null}
{
  "id": "11111111-2222-3333-4444-555555555555",
  "status": "CONFIRMED",
  "amount": 500,
  "currency": "MXN"
}
```

### Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.harmony.compago.com/api/payment-method/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/payment/11111111-2222-3333-4444-555555555555 \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    `https://api.harmony.compago.com/api/payment-method/${paymentMethodId}/payment/${paymentId}`,
    {
      headers: { 'x-api-key': process.env.COMPAGO_API_KEY }
    }
  );

  const payment = await response.json();
  console.log(`Payment ${payment.id}: ${payment.status} - $${payment.amount} ${payment.currency}`);
  ```

  ```python Python theme={null}
  response = requests.get(
      f'https://api.harmony.compago.com/api/payment-method/{payment_method_id}/payment/{payment_id}',
      headers={'x-api-key': os.environ['COMPAGO_API_KEY']}
  )

  payment = response.json()
  print(f"Payment {payment['id']}: {payment['status']} - ${payment['amount']} {payment['currency']}")
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.harmony.compago.com/api/payment-method/{$paymentMethodId}/payment/{$paymentId}");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'x-api-key: ' . getenv('COMPAGO_API_KEY')
  ]);

  $response = curl_exec($ch);
  $payment = json_decode($response, true);
  curl_close($ch);

  echo "Payment {$payment['id']}: {$payment['status']} - \${$payment['amount']} {$payment['currency']}" . PHP_EOL;
  ?>
  ```

  ```ruby Ruby theme={null}
  uri = URI("https://api.harmony.compago.com/api/payment-method/#{payment_method_id}/payment/#{payment_id}")
  request = Net::HTTP::Get.new(uri)
  request['x-api-key'] = ENV['COMPAGO_API_KEY']

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
  payment = JSON.parse(response.body)

  puts "Payment #{payment['id']}: #{payment['status']} - $#{payment['amount']} #{payment['currency']}"
  ```
</CodeGroup>

## Error Responses

| Status Code | Error                                     | Solution                                             |
| ----------- | ----------------------------------------- | ---------------------------------------------------- |
| 400         | Cannot revoke payment method (not ACTIVE) | Only `ACTIVE` payment methods can be revoked.        |
| 401         | Unauthorized                              | Check your API key is valid and included in headers. |
| 404         | Payment method not found                  | Verify the payment method ID is correct.             |
| 404         | Payment not found                         | Verify the payment ID is correct.                    |

## Next Steps

<CardGroup cols={2}>
  <Card title="Charge a Saved Card" icon="money-bill" href="/payment-method/charge">
    Charge a customer's saved card on demand.
  </Card>

  <Card title="Process Refunds" icon="rotate-left" href="/payment-method/refund">
    Issue full refunds for charges.
  </Card>
</CardGroup>