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

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

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, or REFUNDED.

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

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,
  "currency": "MXN"
}

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

One-time payment

Payment Methods

Payment Links

Payment Intents

Odoo Integration

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