Charge a Saved Card

Once a customer has saved their card and the payment method status is ACTIVE, you can charge it at any time by calling the charge endpoint. No customer interaction is required. The charge is processed entirely server-side.

Overview

Charging a saved card allows you to:

Bill customers for subscriptions, memberships, or recurring services
Charge after service delivery (on-demand services, freight, freelance work)
Process payments when orders ship or milestones are reached

Prerequisites

Before charging a saved card:

The payment method must have a status of ACTIVE
You must have the payment method id (returned when creating the payment method)
The card must not be expired or revoked

Creating a Charge

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.

Endpoint

POST /api/payment-method/{id}/payment

API reference: POST /payment-method/{id}/payment

Authentication

Include your API key in the request headers:

x-api-key: YOUR_API_KEY
Content-Type: application/json

Path Parameters

string

required

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

Request Body

{
  "amount": 500,
  "currency": "MXN",
  "description": "Monthly subscription - January 2025"
}

Field Descriptions

Field	Type	Required	Description
`amount`	number	Yes	Amount to charge in MXN. Must be at least 1 MXN.
`currency`	string	No	Currency code. Defaults to `"MXN"`.
`description`	string	No	Description of the charge.
`holdFunds`	boolean	No	When `true`, the funds are only held on the card and nothing is captured until you call the capture endpoint. Defaults to `false`, which charges the card immediately. See Hold Funds.
`externalId`	string	No	Your idempotency key for this charge, up to 255 characters, unique per organization. Repeating a request with the same value returns the original payment instead of charging the card again. See Idempotency.

Charging a card is unchanged. The contract you already use (amount, currency, description) is untouched, and holdFunds is optional and defaults to false, so a request that omits it charges the card immediately, exactly as it always has. Send holdFunds: true only when you want to hold funds instead of charging them.

holdFunds is the only name for this flag, and an unrecognized field is ignored rather than rejected. If you built against an earlier preview of the hold feature, check the name you send: there is no alias, so a request carrying any other spelling of this flag is treated as a request that set nothing, and the card is charged immediately instead of held. Confirm the response status is HELD before you treat a hold as placed.

Response

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

Field	Type	Description
`id`	string	Unique identifier of the payment.
`status`	string	Current status of the payment (`NOT_INITIALIZED`, `PENDING`, `CONFIRMED`, `CANCELLED`, `REFUNDED`). A payment sent with `holdFunds: true` returns `HELD` instead.
`amount`	number	The charged amount. On a captured hold this is the amount that was actually captured, which can be less than the amount that was held.
`heldAmount`	number \| null	The amount the bank authorized when a hold was placed. `null` on a regular charge, which never held anything. See Hold Funds.
`currency`	string	Currency code.
`externalId`	string \| null	The idempotency key you sent, echoed back so you can map our payment `id` to your own order reference. `null` when you sent none.

The response also carries the hold fields (heldAmount, heldAt, capturedAt, holdReleasedAt, holdExpiresAt, holdExpired, holdDaysRemaining). On a regular charge they are null, with holdExpired set to false. They are only populated on holds, and are documented in Hold Funds.

Code Examples

curl -X POST https://api-harmony.compago.com/api/payment-method/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/payment \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "currency": "MXN",
    "description": "Monthly subscription - January 2025"
  }'

const paymentMethodId = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee';

const response = await fetch(
  `https://api-harmony.compago.com/api/payment-method/${paymentMethodId}/payment`,
  {
    method: 'POST',
    headers: {
      'x-api-key': process.env.COMPAGO_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 500,
      currency: 'MXN',
      description: 'Monthly subscription - January 2025'
    })
  }
);

const payment = await response.json();
console.log('Payment ID:', payment.id);
console.log('Status:', payment.status);

import requests
import os

payment_method_id = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'

response = requests.post(
    f'https://api-harmony.compago.com/api/payment-method/{payment_method_id}/payment',
    headers={
        'x-api-key': os.environ['COMPAGO_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'amount': 500,
        'currency': 'MXN',
        'description': 'Monthly subscription - January 2025'
    }
)

payment = response.json()
print('Payment ID:', payment['id'])
print('Status:', payment['status'])

<?php
$paymentMethodId = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee';

$ch = curl_init("https://api-harmony.compago.com/api/payment-method/{$paymentMethodId}/payment");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'x-api-key: ' . getenv('COMPAGO_API_KEY'),
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'amount' => 500,
    'currency' => 'MXN',
    'description' => 'Monthly subscription - January 2025'
]));

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

echo 'Payment ID: ' . $payment['id'] . PHP_EOL;
echo 'Status: ' . $payment['status'] . PHP_EOL;
?>

require 'net/http'
require 'json'
require 'uri'

payment_method_id = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'
uri = URI("https://api-harmony.compago.com/api/payment-method/#{payment_method_id}/payment")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['x-api-key'] = ENV['COMPAGO_API_KEY']
request['Content-Type'] = 'application/json'
request.body = {
  amount: 500,
  currency: 'MXN',
  description: 'Monthly subscription - January 2025'
}.to_json

response = http.request(request)
payment = JSON.parse(response.body)

puts "Payment ID: #{payment['id']}"
puts "Status: #{payment['status']}"

Checking Payment Status

After creating a charge, you can check its status at any time:

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

API reference: GET /payment-method/{id}/payment/{paymentId}

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 status:', payment.status);

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('Payment status:', payment['status'])

<?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 status: ' . $payment['status'] . 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 status: #{payment['status']}"

Idempotency (`externalId`)

POST /api/payment-method/{id}/payment accepts an optional externalId: your own key for this operation, up to 255 characters, unique across all payments in your organization. It is the supported way to make this endpoint safe to retry, and we recommend sending one on every charge. Without it, a retry after a timeout charges the card a second time. A network error tells you nothing about whether the bank approved the first attempt, so a blind retry of a

500 MXN charge can take

1,000 MXN. With an externalId, the retry returns the payment you already made.

{
  "amount": 500,
  "currency": "MXN",
  "description": "Monthly subscription - January 2025",
  "externalId": "invoice-2025-01-8842"
}

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

The payment method externalId, sent to POST /api/payment-method and documented in Manage Payment Methods, is your reference for the saved card or customer.
The payment externalId, sent to POST /api/payment-method/{id}/payment and documented here, 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.

Replay Behaviour

Situation	What happens
You reuse an `externalId` with the same payment method, amount and currency	The original payment is returned. The card is not charged again and the bank is not contacted. The HTTP status is the one the original attempt produced.
You reuse an `externalId` whose original was declined	The decline is returned again, forever. The key is spent.
You reuse an `externalId` with a different payment method, amount or currency	409 `EXTERNAL_ID_MISMATCH`. The message names the payment the key already identifies.
The original request is still in flight	409 `EXTERNAL_ID_CONFLICT`. Retry in a moment: the first request had not finished writing yet.
You send no `externalId`, or an empty string	No idempotency. Every request creates a new payment.

A declined attempt spends the externalId. This surprises people, so it is worth stating plainly: if the bank declines the charge, replaying the same externalId returns that decline again, it does not try the card a second time. To retry a declined charge you must send a new externalId, for example invoice-2025-01-8842-2.This is deliberate. An idempotency key names one attempt, not one intention. The endpoint cannot tell “my HTTP client retried” from “my operator pressed the button again”, and freeing the key on a decline would let a duplicate retry fire a second authorization at the issuer, which feeds their fraud heuristics and can produce a genuine double charge when the bank actually approved a request we recorded as declined.

Charges and holds share one externalId namespace, because both are created by this same endpoint. order-1 cannot exist as a charge and also as a hold. Replaying a key with a different holdFunds value than the original returns the original payment rather than an error, so keep the flag stable across your retries.

The key is echoed back as externalId on every payment response for a saved card (the charge itself, capture, release, refund, list and detail), so you can reconcile our payment id against your own order reference without keeping a mapping table.

Important Business Rules

Payment method must be ACTIVE. You can only charge payment methods with an ACTIVE status. Attempting to charge a PENDING, EXPIRED, or REVOKED payment method will result in a 400 error.

Card expiration. If the customer’s card has expired since it was saved, the charge will fail. In this case, you’ll need to create a new payment method and have the customer save an updated card.

Currency restriction. Only MXN (Mexican Peso) is currently supported. Charges in other currencies will be rejected.

Error Handling

Status Code	Error	Solution
400	Payment method not ACTIVE	Verify the payment method status is `ACTIVE` before charging.
400	Invalid amount	Ensure the amount is at least 1 MXN.
400	Currency not supported	Use `"MXN"` as the currency.
400	`externalId` too long	Keep the payment `externalId` to 255 characters or fewer.
401	Unauthorized	Check your API key is valid and included in headers.
404	Payment method not found	Verify the payment method ID is correct.
409	`EXTERNAL_ID_MISMATCH`	The `externalId` you sent already identifies a payment with a different payment method, amount, or currency. Use a different `externalId` for a different operation.
409	`EXTERNAL_ID_CONFLICT`	The `externalId` is in use by another request that has not finished yet. Retry in a moment: nothing was sent to the bank.

Next Steps

Hold Funds

Hold funds on a card with holdFunds, then capture them (in full or in part) or release them within 7 natural days.

Process Refunds

Issue full refunds for charges made against saved cards.

Manage Payment Methods

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

Get Started

Core Concepts

Developer API

Accept Payments

Integrations

Charge a Saved Card

Overview

Prerequisites

Creating a Charge

Endpoint

Authentication

Path Parameters

Request Body

Field Descriptions

Response

Code Examples

Checking Payment Status

Idempotency (`externalId`)

Replay Behaviour

Important Business Rules

Error Handling

Next Steps

Hold Funds

Process Refunds

Manage Payment Methods

​Overview

​Prerequisites

​Creating a Charge

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Field Descriptions

​Response

​Code Examples

​Checking Payment Status

​Idempotency (externalId)

​Replay Behaviour

​Important Business Rules

​Error Handling

​Next Steps

Hold Funds

Process Refunds

Manage Payment Methods

Overview

Prerequisites

Creating a Charge

Endpoint

Authentication

Path Parameters

Request Body

Field Descriptions

Response

Code Examples

Checking Payment Status

Idempotency (`externalId`)

Replay Behaviour

Important Business Rules

Error Handling

Next Steps