Manage Payment Methods

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

These examples call the production host. While you build, replace https://api-harmony.compago.com with https://demo-api-harmony.compago.com and use a key from the Demo dashboard. See Environments.

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

Endpoint

GET /api/payment-method

API reference: GET /payment-method

Query Parameters

string

Filter by payment method status: PENDING, ACTIVE, EXPIRED, or REVOKED.

integer

default:"1"

Page number for pagination.

integer

default:"100"

Number of items per page (max 500).

Response

{
  "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"
    }
  ]
}

This is not the payment externalId. They are two different fields, one screen apart in these docs:

The payment method externalId, sent to POST /api/payment-method and documented here, is your reference for the saved card or customer.
The payment externalId, sent to POST /api/payment-method/{id}/payment and documented in Charge a Saved Card and Hold Funds, is your idempotency key for one charge or hold.

They live in separate namespaces, so the same string may safely be used for both. They are never compared with each other.

Code Examples

# 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"

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}`);
});

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
$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;
}
?>

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

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}

Path Parameters

string

required

The unique identifier of the payment method (UUID).

Response

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

Code Examples

curl https://api-harmony.compago.com/api/payment-method/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee \
  -H "x-api-key: YOUR_API_KEY"

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);

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
$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;
?>

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']}"

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}

Path Parameters

string

required

The unique identifier of the payment method to revoke (UUID).

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.

Response

{
  "success": true
}

Code Examples

curl -X DELETE https://api-harmony.compago.com/api/payment-method/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee \
  -H "x-api-key: YOUR_API_KEY"

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);

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
$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;
?>

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']}"

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

Path Parameters

string

required

The unique identifier of the payment method (UUID).

Query Parameters

string

Filter by payment status: NOT_INITIALIZED, PENDING, CONFIRMED, CANCELLED, REFUNDED, HELD, HOLD_RELEASED, or HOLD_EXPIRED. Filtering by HELD is the quickest way to list the holds that are still live on a card.

integer

default:"1"

Page number for pagination.

integer

default:"100"

Number of items per page (max 500).

Response

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

Every payment in the list carries the idempotency key you sent as externalId (null when you sent none), and the hold fields: heldAmount, heldAt, capturedAt, holdReleasedAt, holdExpiresAt, holdExpired, and holdDaysRemaining. They are null on regular charges (holdExpired is false) and populated on holds:

{
  "id": "11111111-2222-3333-4444-555555555555",
  "status": "HELD",
  "amount": 3500,
  "heldAmount": 3500,
  "currency": "MXN",
  "createdAt": "2025-03-04T16:20:11.482Z",
  "externalId": "deposit-R-4821",
  "heldAt": "2025-03-04T16:20:12.907Z",
  "capturedAt": null,
  "holdReleasedAt": null,
  "holdExpiresAt": "2025-03-11T05:00:00.000Z",
  "holdExpired": false,
  "holdDaysRemaining": 7
}

On a hold that was captured for only part of its amount, amount is the amount that was captured and heldAmount stays at the amount that was originally held, so a payment showing "amount": 200 with "heldAmount": 1200 was a

1,200 MXN hold captured for

200 MXN. See Capturing a Hold. The heldAt above is 2025-03-04 10:20 in Mexico City, so the placement day is Tuesday 4 March. Six calendar days later is Monday 10 March, and the window closes at 23:00 that day, which is 2025-03-11T05:00:00.000Z in UTC. holdExpiresAt is always 23:00 America/Mexico_City, never the clock time at which you placed the hold. holdDaysRemaining is 7 here because the hold was placed before 23:00 on its own placement day, so that day still counts. See Hold Funds for what each field means and how to tell whether a hold is still capturable.

Code Examples

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"

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}`);
});

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
$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;
}
?>

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

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}

Path Parameters

string

required

The unique identifier of the payment method (UUID).

string

required

The unique identifier of the payment (UUID).

Response

{
  "id": "11111111-2222-3333-4444-555555555555",
  "status": "CONFIRMED",
  "amount": 500,
  "heldAmount": null,
  "currency": "MXN",
  "externalId": "invoice-2025-01-8842"
}

This response carries the same externalId and hold fields as the list endpoint (heldAmount, heldAt, capturedAt, holdReleasedAt, holdExpiresAt, holdExpired, holdDaysRemaining), so it is the endpoint to poll when you need to know whether a hold is still live, and the one to read to see how much of a hold was actually captured.

Code Examples

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"

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}`);

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
$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;
?>

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']}"

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.

Get Started

Core Concepts

Developer API

Accept Payments

Integrations

Manage Payment Methods

List Payment Methods

Endpoint

Query Parameters

Response

Code Examples

Get Payment Method Details

Endpoint

Path Parameters

Response

Code Examples

Revoke a Payment Method

Endpoint

Path Parameters

Response

Code Examples

List Payments for a Payment Method

Endpoint

Path Parameters

Query Parameters

Response

Code Examples

Get Payment Details

Endpoint

Path Parameters

Response

Code Examples

Error Responses

Next Steps

Charge a Saved Card

Process Refunds

​List Payment Methods

​Endpoint

​Query Parameters

​Response

​Code Examples

​Get Payment Method Details

​Endpoint

​Path Parameters

​Response

​Code Examples

​Revoke a Payment Method

​Endpoint

​Path Parameters

​Response

​Code Examples

​List Payments for a Payment Method

​Endpoint

​Path Parameters

​Query Parameters

​Response

​Code Examples

​Get Payment Details

​Endpoint

​Path Parameters

​Response

​Code Examples

​Error Responses

​Next Steps

Charge a Saved Card

Process Refunds

List Payment Methods

Endpoint

Query Parameters

Response

Code Examples

Get Payment Method Details

Endpoint

Path Parameters

Response

Code Examples

Revoke a Payment Method

Endpoint

Path Parameters

Response

Code Examples

List Payments for a Payment Method

Endpoint

Path Parameters

Query Parameters

Response

Code Examples

Get Payment Details

Endpoint

Path Parameters

Response

Code Examples

Error Responses

Next Steps