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 returns422 payment_method_unusableand 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:readandpayment_intents:writescopes. See Authentication. - A customer ID. See Customers.
- Use staging (
https://staging-api.revkeen.com/v2) and anrk_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 ─► canceledAn intent created with a payment_method starts in requires_confirmation; without one it starts in requires_payment_method.
| Status | Meaning | What you do next |
|---|---|---|
requires_payment_method | No payment method yet, or the last attempt was declined | Cancel; confirming through the API is not available yet |
requires_confirmation | Ready to charge | Cancel; confirming through the API is not available yet |
requires_action | The customer must authenticate (3D Secure) | Send the customer to next_action.redirect_to_url.url |
processing | Being charged, or authorised and waiting for capture (capture_method: manual) | Capture, or wait |
succeeded | Paid. Terminal | Fulfil the order |
canceled | Cancelled. Terminal | Nothing; 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.
| Status | error.code | Meaning | What to do |
|---|---|---|---|
400 | payment_intent_unexpected_state | The action is not allowed in the intent's current status, for example capturing an automatic-capture intent | Retrieve the intent and act on its current status |
400 | varies | The request body failed validation | Fix the request |
401 | authentication_failed, invalid_api_key, api_key_revoked and similar | Missing, invalid or revoked key | Check the key and its scopes |
404 | resource_missing | No such intent for this account | Check the ID and the environment |
409 | payment_intent_charged | Cancel on an intent that has already been charged | Refund the payment instead of cancelling |
422 | payment_method_unusable | Confirm is not available through the API yet | Use hosted checkout or a payment link |
429 | rate_limit_exceeded | Too many requests | Wait for the Retry-After seconds, then retry with the same idempotency key |
5xx | internal_error | The outcome is unknown | Retrieve 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.
Related
Owner: david · Reviewed 10 Oct 2026 · Next review 30 Oct 2026