Skip to main content

Getting a payment-method token

A server-side charge needs a vp_pmt_* payment-method token — the Payment Intents body has no card fields — and the token has to come from somewhere the card number never reaches your server.

The flow​

┌─────────────────────────────────────────────────────────────┐
│ Buyer's browser │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Iframe-vault provider's SDK │ │
│ │ [Card #][Exp][CVV][Billing address] (PCI-isolated) │ │
│ └────────────────────────────────────────────────────────┘ │
│ │ tokenize │
│ ▼ │
│ provider_reference handle │
└───────────────────────┼─────────────────────────────────────┘
│
▼ (sent to your server)
POST /v1/tokens
{ provider_reference: "..." }
│
▼
vp_pmt_test_QAqnXEJF...
│
▼
POST /v1/payment_intents
{ amount, currency,
payment_method: { id: "vp_pmt_..." } }

Three steps: (1) browser-side tokenize the card, (2) server-side mint a vp_pmt_* from the iframe handle, (3) charge it via Payment Intents. Card data flows browser → vault → token; never to your server, never to ours.

What you integrate browser-side​

Your iframe-vault provider's SDK is what renders the card form on your checkout page. The path:

  1. Load your iframe-vault provider's JS SDK on your checkout page.
  2. Render their card-form iframe. The buyer enters card + billing address inside the iframe.
  3. The iframe SDK returns a provider_reference (a vault-side token, format depends on the provider) once tokenization succeeds.
  4. POST that handle to your server.

Mint a vp_pmt_* token​

Your server posts the iframe-minted handle to /v1/tokens. The body takes provider_reference (required) and an optional buyer_id (a nested buyer profile object is also accepted — see Tokens):

provider_reference must be the provider's handle, not one of ours

Anything beginning vp_ is rejected with 400 validation_error. The usual mistake is passing a vp_pmt_* — but that is already the reusable token this endpoint produces. If you hold a vp_pmt_*, you don't need this endpoint at all: charge it directly with payment_method.id on POST /v1/payment_intents.

Using embedded fields? Prefer POST /v1/public/tokens, which resolves the provider-side handle from the session, so you never supply this field.

curl -X POST https://checkout.vonpay.com/v1/tokens \
-H "Authorization: Bearer vp_sk_test_xxx" \
-H "Content-Type: application/json" \
-d '{
"provider_reference": "<the iframe-minted handle>",
"buyer_id": "buyer_abc"
}'
{
"id": "vp_pmt_test_QAqnXEJF_TCum1jg",
"status": "active",
"card": { "brand": "visa", "last4": "4242", "exp_month": 12, "exp_year": 2030 }
}

The response carries display-safe metadata (brand, last4, exp_month, exp_year — exp_month and exp_year are integers) you can show in your UI for "card on file" displays. They are read from the payment provider's record of the saved card, and each is null if it could not be read (the card is still saved), so render a fallback rather than assuming a value. The PAN itself never appears.

provider_reference is required with a test key too: a request without it is rejected with validation_error.

Now charge it​

Pass the vp_pmt_* ID into payment_method.id on paymentIntents.create:

const intent = await vonpay.paymentIntents.create(
{
amount: 1499,
currency: "USD",
captureMethod: "automatic", // sale
paymentMethod: { id: "vp_pmt_test_QAqnXEJF_TCum1jg" },
returnUrl: "https://mystore.com/checkout/return?order=ord_42", // where the bank returns the buyer; your order ref tells the page which order
metadata: { orderId: "ord_42" },
},
{ idempotencyKey: "ord_42_create" },
);

That's the full server-side flow.

Billing address & AVS​

When you charge a card server-side, pass the buyer's billing address on the request so the processor can run Address Verification (AVS). Supply it as an optional top-level billing_address object on POST /v1/payment_intents — ordinary data from your own checkout form:

curl -X POST https://checkout.vonpay.com/v1/payment_intents \
-H "Authorization: Bearer $VON_PAY_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ord_42_create" \
-d '{
"amount": 1499,
"currency": "USD",
"capture_method": "automatic",
"payment_method": { "id": "vp_pmt_test_QAqnXEJF_TCum1jg" },
"return_url": "https://mystore.com/checkout/return?order=ord_42",
"billing_address": {
"address_line1": "1600 Pennsylvania Ave NW",
"postal_code": "20500",
"country": "US"
}
}'

The object is strict — unknown keys are rejected:

FieldRequiredConstraint
address_line1recommendedstring, 1–60 chars
address_line2optionalstring, ≤ 60 chars
cityoptionalstring, ≤ 40 chars
stateoptionalstring, ≤ 40 chars
postal_coderecommendedstring, 1–16 chars
countryrequired2-letter ISO 3166-1 alpha-2, uppercase (e.g. US)

Only country is required. If all you have is the country, or the country and postal code, send that. The address check reads the street and the postal code, so send both when you have them. A partial address is used for this charge only: it is not stored with the saved card, and it is never combined with an address stored earlier. Leave out a street or postal code you do not have: an empty value, or one with only spaces, is refused. A value that is too long, empty or only spaces returns 400 validation_error, and the error names the field (for example billing_address.address_line1 must be 60 characters or fewer). Nothing is charged.

Raw REST only. The Node and Python SDKs don't accept billing_address on paymentIntents.create yet — send it on the raw request body shown above. (Don't confuse it with the mirror block's own address, which routes connected-platform orders, not AVS.)

When AVS is enabled for your merchant, the create response carries a vendor-neutral avs_result_code:

avs_result_codeMeaning
matchAddress and postal code both matched
partial_postalPostal code matched, street did not
partial_addressStreet matched, postal code did not
no_matchNeither matched
unavailable / not_supportedThe issuer/processor didn't return a result

The response also carries cvv_result_code, but a charge against a stored token can't verify one — a vaulted vp_pmt_* carries no security code, so where the field is populated it reads not_provided (a distinct enum member, not JSON null). To actually check a CVV you have to catch it on the buyer's first charge: see charge at submit, where the security code rides the charge in elements mode. Both codes are null when no billing_address is sent or AVS/CVV didn't run for your merchant/processor. Treat a no_match as a risk signal, not an automatic decline — you own the accept / review / refund decision.

Shipping address: there is no shipping_details field on the Payment Intents body. Keep shipping on metadata for your own records, or — to create a matching already-paid order in a connected store (with its shipping address) — send order and mirrorTo. They work the same way here as on hosted checkout: order.lineItems describes the purchase once, and the store order's customer and addresses are inherited from buyer. The older mirror block is still accepted; send one or the other, never both.

Buyer IP address​

Send the shopper's address on a server-side charge and your processor's risk rules judge the person paying instead of us. Leave it out and every charge your backend makes arrives carrying one of our datacenter addresses, so velocity limits, IP blocklists and regional filters all evaluate the same few addresses rather than your buyer. On card-not-present traffic that is a real and avoidable source of declines.

Pass it as an optional top-level buyer_ip_address on POST /v1/payment_intents:

curl -X POST https://checkout.vonpay.com/v1/payment_intents \
-H "Authorization: Bearer $VON_PAY_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ord_42_ip_create" \
-d '{
"amount": 1499,
"currency": "USD",
"payment_method": { "id": "vp_pmt_test_QAqnXEJF_TCum1jg" },
"return_url": "https://mystore.com/checkout/return?order=ord_42",
"buyer_ip_address": "203.0.113.7"
}'
RuleDetail
FormatA public IPv4 or IPv6 address, 45 characters or fewer.
RejectedPrivate, loopback and reserved ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8, 169.254.0.0/16, fc00::/7, fe80::/10 among others) return 400 validation_error. An IPv4 address wrapped as IPv6 is judged by its IPv4 part, so ::ffff:10.0.0.1 is refused too. Send the address the buyer connected from, not your proxy's.
Not assertedMerchant-initiated charges. A rebill or retry your server triggers has no shopper present, so no address is sent, the same rule return_url follows.

Both server SDKs carry it from 2.9.0: buyerIpAddress in Node, buyer_ip_address in Python.

The create response confirms what happened. buyer_ip_address_forwarded comes back true when the address reached the processor and false when it was accepted but not sent. Read it from the charge response rather than a later fetch, and treat false as "this charge got no IP-based screening" rather than an error. The address itself is never echoed back, and never appears in webhooks or logs.

Embedded Fields and hosted checkout resolve this for you. There the buyer connects to us directly, so you do not send buyer_ip_address yourself. It exists for server-to-server charges, where the request reaches us from your backend and we never see the shopper.

Fraud evidence​

Attach up to five standard fraud-evidence fields to a charge and they are recorded on your payment processor's own record of that charge, each under a fixed label. When the charge is disputed, you or your processor can read them back from that record, for example for card-network programs that ask for the IP address, device, email and account of earlier undisputed purchases (such as Visa Compelling Evidence 3.0).

Pass them as an optional fraud_evidence object on POST /v1/payment_intents:

curl -X POST https://checkout.vonpay.com/v1/payment_intents \
-H "Authorization: Bearer $VON_PAY_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ord_42_evidence_create" \
-d '{
"amount": 1499,
"currency": "USD",
"payment_method": { "id": "vp_pmt_test_QAqnXEJF_TCum1jg" },
"return_url": "https://mystore.com/checkout/return?order=ord_42",
"fraud_evidence": {
"customer_ip": "203.0.113.7",
"device_fingerprint": "dfp_8c2e41a9",
"customer_email": "jane@example.com",
"customer_account_id": "cust_1042",
"product_description": "Annual plan, one seat"
}
}'
FieldLabel on the processor's recordWhat to send
customer_ipevidence_customer_ipThe customer's public IPv4 or IPv6 address when they placed the order, 45 characters or fewer. Private, loopback and reserved ranges are rejected.
device_fingerprintevidence_device_fingerprintYour identifier for the customer's device, for example from your own device-fingerprinting tool.
customer_emailevidence_customer_emailThe email address on the customer's account. Must be a valid email address.
customer_account_idevidence_customer_account_idYour id or login for the customer's account.
product_descriptionevidence_product_descriptionA short description of what was bought, as the customer would recognise it.
  • Only these five fields, and at least one of them. Your metadata is still not sent to the processor.
  • Every value is at most 80 characters, because the processor refuses a longer one. Leading and trailing spaces are trimmed first. A value that is empty, too long, more than one line, or looks like a card number or an API key is rejected with 400 validation_error and nothing is charged.
  • Sent on every charge, including a merchant-initiated one. It describes what you know about the customer and does not claim the customer is present. customer_ip is only a labelled entry: the address your processor's IP rules judge is still the one in buyer_ip_address.
  • Not every payment connection carries these fields. If yours does not, the field is still checked and the charge goes ahead as normal, but nothing is sent to the processor.
  • We do not store, log or echo the values. The create response carries fraud_evidence_forwarded: true when the fields were sent with the charge, false when they were accepted but not sent. It is absent when you did not send fraud_evidence.
  • A retry with the same Idempotency-Key returns the original charge. The evidence that charge was sent with is the evidence on the processor's record; fraud_evidence on the retry is ignored, and fraud_evidence_forwarded is not repeated, so read it from the first response.

Buyer attribution​

POST /v1/payment_intents accepts optional buyer fields (snake_case on this surface) so a server-side charge is attributed to the same buyer record the checkout flows use:

FieldTypeDescription
buyer_idstringYour own customer reference (1–200 chars) — the same value you pass as buyerId on session create. Links the charge to the buyer record (best-effort; never blocks the charge). Also the saved-card ownership assertion: when the stored payment_method was saved against a buyer, this must match the buyer the card was saved for — a mismatch returns 404 payment_method_not_found, so a saved card can't be charged against the wrong customer. Send it on every charge against a saved card; omit it for guest or one-off charges.
buyer_emailstringThe buyer's email (valid email, max 254 chars) — for flows that start from a payment intent instead of a checkout session (saved-card charges, subscription rebills, server-side charges). Links the charge to the buyer record (best-effort; never blocks the charge). We never email the buyer — no receipt is sent from this field. It is forwarded to your payment provider on the charge's billing block, where a complete billing block helps the processor authorize and gives you stronger evidence when defending a dispute. ⚠️ Forwarding is an account-level setting, not a per-request one, so a successful response does not by itself confirm the billing block was sent — ask us if you need it switched on. Send it explicitly on every charge you want it applied to: there is a fallback to the email already on file, but it is off by default and can only find a buyer you also identify by buyer_id / buyer.external_id — it cannot look one up by email alone.
buyerobjectNested buyer profile: external_id, email, first_name, last_name, name, phone, company, address, metadata. Upserts the same buyer record as POST /v1/buyers and links the charge to it — the richer alternative to the flat fields above, which remain supported. Must carry an identity (buyer.external_id or buyer.email) directly or via a flat field, else 400 validation_error. ⚠️ first_name / last_name are the exception: they are the structured pair that reaches the processor's billing block (see what reaches your provider), they belong to this charge and are not stored on the buyer record, and they cannot be added to an existing buyer later — see Putting a name on the payment. A combined name is stored but never split.
session_idstringThe checkout session (vp_cs_*) this charge belongs to. Arms the double-charge guard: if that session already charged the buyer at submit time, this call is refused with 409 session_already_completed instead of billing the card a second time. Send it on charges related to that session. The refusal is deliberately conservative: it also fires after the session expired, because then we cannot prove no money moved. While the session's own charge is still running (processing), the refusal is 409 session_payment_in_progress instead. Neither refusal charges the card. Don't attach an unrelated session ID to a fresh charge.

session_id and buyer_id each arm a server-side guard and are silent no-ops when omitted — an integration that leaves them out looks healthy until it double-charges someone or bills the wrong customer's saved card.

Sending a flat field AND its nested counterpart with equal values is fine; different identity values return 400 validation_error rather than silently preferring one (buyer_id doubles as the ownership assertion above, so the server never guesses which value you meant). The accepted buyer fields are echoed back on the response so a successful write is verifiable (buyer.metadata echoed post-scrub). When the stored payment_method already carries a buyer from vault time, that saved buyer still wins for attribution and is echoed as the effective buyer_id.

The linkage reads back on GET /v1/payment_intents/{id}: a buyer-linked charge includes buyer_id and buyer_email; charges with no buyer linkage omit both keys. This applies to automatic and manual (authorize-then-capture) captures — buyer identity sent at create carries through the capture. See the Buyers API for the full buyer-record reference.

Per-merchant requirements​

The payment_method field's required-ness depends on which underlying processor your merchant is configured for — read /v1/capabilities once at startup and branch on the response. Some configurations require a vp_pmt_* token for direct charges; others accept intents created without one (used by the hosted-page flow). The capabilities matrix is the canonical source — don't hard-code per-processor assumptions.

Live activation gate. Direct server-side charges with payment_method may not be enabled on production for every processor; sandbox works regardless. If you need direct-charge support on live keys, contact your VORA point of contact to enable it for your merchant.