Payment Intents

Create, retrieve, list and cancel payment intents through the API. Confirming a payment intent through the API is not available yet; take card payments with hosted checkout or a payment link.

A payment intent tracks one attempt to collect one amount from one customer, from creation through to success or cancellation.

Confirming through the API is not available yet. There is no way to send a card token or a saved card to POST /v2/payment-intents/{id}/confirm, so it returns 422 payment_method_unusable and leaves the intent unchanged. To take a card payment, send the customer to hosted checkout or a checkout link. The API never accepts raw card numbers.

Through the API you can create, retrieve, list and cancel payment intents, and capture a manual-capture intent that has already been charged.

Before you start

  • A secret API key with the payment_intents:read and payment_intents:write scopes. See Authentication.
  • A customer ID. See Customers.
  • Use staging (https://staging-api.revkeen.com/v2) and an rk_sandbox_* key until the flow works end to end. See Environments.

Lifecycle

requires_payment_method ─► requires_confirmation ─► processing ─► succeeded
          ▲                                           │   ▲
          └──────────── declined ◄────────────────────┤   │
                                                      ▼   │
                                              requires_action (3D Secure)

Any status except succeeded ─► canceled

An intent created with a payment_method starts in requires_confirmation; without one it starts in requires_payment_method.

StatusMeaningWhat you do next
requires_payment_methodNo payment method yet, or the last attempt was declinedCancel; confirming through the API is not available yet
requires_confirmationReady to chargeCancel; confirming through the API is not available yet
requires_actionThe customer must authenticate (3D Secure)Send the customer to next_action.redirect_to_url.url
processingBeing charged, or authorised and waiting for capture (capture_method: manual)Capture, or wait
succeededPaid. TerminalFulfil the order
canceledCancelled. TerminalNothing; create a new intent to try again

succeeded and canceled are final: an intent in either status cannot be confirmed, captured, cancelled or changed.

Amounts and currency

Amounts are integers in the minor unit of the currency: 2500 in gbp is £25.00. If you leave currency out, RevKeen uses your account's default currency. Currency codes are returned in lower case.

Create

Create the intent with the amount and the customer. The TypeScript examples use @revkeen/sdk.

import { RevKeen } from "@revkeen/sdk";

const client = new RevKeen({
  apiKey: process.env.REVKEEN_API_KEY!,
  baseUrl: "https://staging-api.revkeen.com/v2",
});

const intent = await client.paymentIntents.create({
  amount: 2500, // £25.00
  currency: "GBP",
  customer: "3f0c5b2e-8a41-4d6f-9c1e-2b7a9d4e6f10",
  description: "Sports massage, 60 minutes",
  metadata: { order_id: "order_1042" },
});
curl https://staging-api.revkeen.com/v2/payment-intents \
  -H "x-api-key: $REVKEEN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500,
    "currency": "GBP",
    "customer": "3f0c5b2e-8a41-4d6f-9c1e-2b7a9d4e6f10",
    "description": "Sports massage, 60 minutes"
  }'

The response is the payment intent object. Its id starts with pi_.

Capture

capture applies to an intent created with capture_method: manual that is in processing. The card was already charged when the intent was confirmed (the gateway takes a sale, not an authorisation), so capture does not call the gateway again: it marks the intent succeeded and records the sale. You cannot capture more than amount_capturable, or capture an intent created with capture_method: automatic.

Cancel

Cancel an intent you no longer intend to charge. Any status except succeeded and canceled can be cancelled, with one exception: an intent in processing that has already been charged at the gateway is refused with 409 payment_intent_charged, because cancelling it would not return the money.

await client.paymentIntents.cancel("pi_...", {
  cancellation_reason: "requested_by_customer",
});

cancellation_reason is one of duplicate, fraudulent, requested_by_customer, abandoned or failed_invoice. To return money from a payment that has already succeeded, use a refund, not a cancel.

Retrieve and list

const current = await client.paymentIntents.get("pi_...");

const recent = await client.paymentIntents.list({
  customer: "3f0c5b2e-8a41-4d6f-9c1e-2b7a9d4e6f10",
  status: "succeeded",
  limit: 20,
});

Retrieve the intent whenever you need its current status, for example after a timeout.

Lists are newest first. When has_more is true, pass the id of the last intent on the page as starting_after to get the next page, or the first one as ending_before to go back. A cursor that names no intent of your account is refused with 400.

Once an intent has succeeded, its transaction field holds the sale transaction it recorded. Pass that value as payment_id, or pass the intent's own id as payment_intent, to create a refund.

Idempotency

Send an Idempotency-Key header on every create, capture and cancel, and reuse the same key when you retry the same operation. A retried request with the same key returns the stored result instead of charging again. Keys are kept for 24 hours. See Idempotency.

With the TypeScript SDK, set the header on a client you use for that one operation:

import { randomUUID } from "node:crypto";

// Store this key with your order so a retry reuses it.
const idempotencyKey = randomUUID();

const scoped = new RevKeen({
  apiKey: process.env.REVKEEN_API_KEY!,
  baseUrl: "https://staging-api.revkeen.com/v2",
  headers: { "Idempotency-Key": idempotencyKey },
});

const intent = await scoped.paymentIntents.create({
  amount: 2500,
  currency: "GBP",
  customer: "3f0c5b2e-8a41-4d6f-9c1e-2b7a9d4e6f10",
});

If a create request times out, retry it with the same key, or list the customer's intents before creating another. Creating a second intent without the key risks charging twice.

Errors

Errors use the standard RevKeen shape: error.type, error.code and error.message. The SDK throws RevKeenAPIError, which carries the HTTP status and the response body.

Statuserror.codeMeaningWhat to do
400payment_intent_unexpected_stateThe action is not allowed in the intent's current status, for example capturing an automatic-capture intentRetrieve the intent and act on its current status
400variesThe request body failed validationFix the request
401authentication_failed, invalid_api_key, api_key_revoked and similarMissing, invalid or revoked keyCheck the key and its scopes
404resource_missingNo such intent for this accountCheck the ID and the environment
409payment_intent_chargedCancel on an intent that has already been chargedRefund the payment instead of cancelling
422payment_method_unusableConfirm is not available through the API yetUse hosted checkout or a payment link
429rate_limit_exceededToo many requestsWait for the Retry-After seconds, then retry with the same idempotency key
5xxinternal_errorThe outcome is unknownRetrieve the intent before doing anything else

Webhooks

There are no payment_intent.* webhook events. The capture and cancel responses, and retrieving the intent, are the source of truth for an intent you create through the API.

Owner: david · Reviewed 10 Oct 2026 · Next review 30 Oct 2026

On this page