Create payment
Create a payment and receive the payment instructions or redirect URL supported by the selected method.
/api/v1/paymentsSelect a stage to see what happens.
/payments- amount
- 50.00 USD
- paymentMethod
- Available for your shop
Create the payment
Your backend sends the amount and a method available for your shop. Keep the returned transactionId.
Illustrative flow · no data is sent
How this endpoint works
Starts a server-to-server charge. The shop is identified via the Bearer token (POST /api/v1/auth/token). Pass `paymentMethodId` with the 4-digit id returned by GET /api/v1/payment-methods. Each retailer / bank / native method has its own unique id (e.g. 1001 → SPEI, 1002 → OXXO, 1003 → Walmart, 1004 → 7-Eleven, 1005 → BBVA, 1006 → Scotiabank) and the cascade routes exactly to that upstream. The same `paymentMethodId` comes back in the response and is queryable via GET /api/v1/payments. The response includes `paymentFormUrl` (the upstream provider's URL — you redirect to or embed it). If you prefer our hosted UI, use POST /api/v1/checkout/sessions which returns its own `checkoutUrl`. The settlement crypto, the destination wallet, and the KYC level are derived internally from the merchant's config — they are not sent in the body. Note: the legacy path `POST /api/v1/transactions` works exactly the same; use whichever you prefer.
Request parameters
Expand a field to see its format and requirements.
amountnumberRequired
Charge amount, in `currency` (major units). USD by default (e.g. 50 = US$50.00). With a non-USD `currency` (presentment) this is the amount in that currency; we convert it to a USD headline (max 100,000 USD) at our rate minus the FX markup. > 0.
currencystring
OPTIONAL presentment currency (ISO-4217, 3 letters, default "USD"). Pass e.g. "EUR"/"GBP"/"MXN" to price in that currency — we convert `amount` to USD (our rate minus the FX markup); ledger credits and settlement follow the shop balance model (USD or local currency). In the response your value comes back as `inputCurrency` (NOT `currency`, which stays "USD"). No FX rate for the currency → 422 fx_unavailable.
paymentMethodIdstringRequired
The 4-digit code from GET /api/v1/payment-methods. Each retailer / bank / native method has its own unique code (e.g. "1001" SPEI, "1002" OXXO, "1003" Walmart, "1005" BBVA). The codes are OURS — assigned by the platform and stable even when we rotate upstream providers. This is the recommended field and the only one that guarantees deterministic routing to the specific rail.
userNamestring
Required in the hosted-checkout / payment-link flow (the checkout collects it); recommended but not enforced on a direct API call. The buyer's full name (at least 2 words), max 120 chars. In the checkout flow, if absent or malformed the response is 422 `missing_required_fields` naming `userName`.
userEmailstring
Required in the hosted-checkout / payment-link flow (the checkout collects it); recommended but not enforced on a direct API call. The buyer's email (valid address), max 254 chars. In the checkout flow, if absent or malformed the response is 422 `missing_required_fields` naming `email`.
documentIdstring
Required in the hosted-checkout / payment-link flow (the checkout collects it); recommended on a direct API call (some rails — Brazil PIX, Mexico OXXO — still need it for the upstream charge). The buyer's identity document — RFC/CURP (Mexico), CPF (Brazil PIX, 11 digits), or CC/DNI/etc. elsewhere. Forwarded to the provider; not persisted on the tx.
paymentMethodstring
Legacy. Ambiguous slug (card · debit · spei · pix · oxxo · voucher · bank_transfer · …). Accepted only as a fallback when `paymentMethodId` is not sent. The cascade picks any provider in the slug + country bucket, without guaranteeing a specific retailer — for example `voucher` + MEX could route Walmart or 7-Eleven. Use `paymentMethodId` in new code.
countrystring
Payer's country. Accepts ISO-3 (BRA, MEX, COL, ARG, CHL, PER, …) or ISO-2 (BR, MX, CO, AR, CL, PE, …) interchangeably — we normalize to ISO-3 internally. Default: USA.
userPhonestring
Payer's phone (include the country code, e.g. +52). Some rails (OXXO, PIX, voucher) require it for the upstream charge.
userIpstring
Payer's IP (we also infer it from the request).
merchantOrderIdstring
Your own reference id (any string ≤120 chars). Stored on the transaction and queryable via GET /transactions?merchantOrderId=… for disaster-recovery lookup.
tag1string
OPTIONAL free-form tag (≤200 chars) for any info of your interest (order refs, campaign ids, internal notes). Stored on the transaction and echoed back verbatim on this response and on GET /payments (single + list). Pure pass-through — never affects routing, pricing, or the provider. Same in sandbox + production.
tag2string
OPTIONAL free-form tag (≤200 chars). See tag1.
tag3string
OPTIONAL free-form tag (≤200 chars). See tag1.
hostedCheckoutboolean
When true, the response includes `checkoutUrl` — a Key2Pay-hosted page that renders QR / CLABE / redirect UI per the selected method. Redirect the customer there and listen for the webhook.
returnUrlstring
Where the hosted checkout sends the customer once they finish (or click Return). Only used when `hostedCheckout: true`.
merchantIdstring
Only if your token covers multiple merchants; default: the shop's.
shopIdstring
Same, for multiple shops.
Integration details
Currency, behavior and additional notes for this operation.
Contract examples
curl https://sandbox.key2pay.ai/api/v1/payments \
-H "Authorization: Bearer sk_test_51N8mP...exampleK3Y" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"amount": 50,
"paymentMethodId": "sbx_spei",
"country": "MEX",
"userName": "Test Buyer",
"userEmail": "test@test.com",
"documentId": "TESTDOC12345",
"merchantOrderId": "ORD-12345",
"tag1": "campaign:black-friday",
"tag2": "channel:mobile-app",
"tag3": "note:vip-customer"
}'
# tag1/tag2/tag3: OPTIONAL free-form tags (<=200 chars each) — echoed back verbatim on the
# response and on GET /payments. Same in sandbox + production.
# userName + userEmail + documentId: required in the hosted-checkout/payment-link flow (else 422
# missing_required_fields); recommended but optional on a direct API call. Sent here for completeness.
# sandbox: use a sbx_ test method (sbx_pix/sbx_spei/sbx_card/sbx_pse/sbx_cash).
# production: use the 4-digit code from GET /payment-methods (e.g. 1001 SPEI).
# For OUR hosted checkout page add "hostedCheckout": true → response carries checkoutUrl
# instead of paymentFormUrl. See /docs/endpoints/hosted-checkout.amount you send is in USD (major units, e.g. 50 = US$50.00) unless you pass a currency. Optionally initiate in a presentment currency (currency: "EUR", "MXN", …): we convert amount to a USD headline at our rate minus the FX markup (the response returns inputCurrency + inputAmount; currency stays "USD"). No FX rate for the currency → 422 fx_unavailable. Key2Pay returns the requested local amount as amountLocal + currencyLocal. Matching presentment and rail currencies avoid a second conversion. (The refund takes the amount in the original tx's LOCAL currency.)rounding snapshot in create, GET/list and payment webhooks contains requestedAmount, chargeAmount, currency and policy: ceil_whole_unit. inputAmount still preserves the original non-USD input. Provider-calculated final local amounts may contain decimals and must be paid exactly as instructed. Existing completed charges, receipts and recorded balances retain their precision; retries return their stored response.Presentment currency — worked example (EUR). Send currency: "EUR"; your value comes back as inputCurrency / inputAmount, currency stays "USD", and amount is the converted USD:
# Initiate in EUR; settlement follows the shop balance model. Two DIFFERENT currencies → two DIFFERENT amountLocal.
curl https://sandbox.key2pay.ai/api/v1/payments \
-H "Authorization: Bearer $K2P" \
-H "Content-Type: application/json" \
-d '{ "currency": "EUR", "amount": 100, "paymentMethodId": "1008", "country": "MEX" }'
# Response — 'currency' is ALWAYS "USD"; your EUR comes back as inputCurrency/inputAmount:
# {
# "transactionId": "TXN-…",
# "status": "pending",
# "currency": "USD", // USD reference currency; settlement follows the shop balance model
# "inputCurrency": "EUR", // <-- what you sent
# "inputAmount": 100, // <-- the amount you sent, in EUR
# "amount": 114.45, // converted USD headline (our rate − FX markup)
# "amountLocal": 1994.16, // buyer pays this in their local currency
# "currencyLocal": "MXN"
# }
#
# Sending "GBP" instead of "EUR" (same amount 100) yields a DIFFERENT amount/amountLocal
# (e.g. amount 134.78 → amountLocal 2348.40 MXN). If both give the SAME MXN, you did NOT
# send 'currency' (it defaulted to USD) — check the request body.userName, userEmail and documentId behave differently per flow. In the hosted-checkout / payment-link flow all three are required — the checkout asks the buyer for them so the "Datos del cliente" record is complete; if any is absent or malformed you get a 422 missing_required_fields with details.missingFields naming each one (userName · email · documentId), no transaction is created, and the hosted modal collects whatever's missing automatically. On a direct API call they are recommended but not enforced — pass them when you have them (some rails still need documentId for the upstream charge), but the platform won't reject the request for their absence. Either way, errors are never cached, so you may reuse the same Idempotency-Key on a retry.cascade_exhausted with reason no_provider_for_method_region — retry once before doing anything else. The cascade engine already does a force-reload of its internal state in this scenario, so a second attempt sees the same truth as your listing. If the retry also fails:details.paymentMethodEnabledForShop === false→ you hardcoded a code that isn't from YOUR shop. Call GET /api/v1/payment-methods again.details.paymentMethodEnabledForShop === true→ there's a real mismatch in our config; open a ticket with therequestIdand we'll unblock it in minutes.
paymentFormUrl(e.g. secure-int.key2pay.io/checkout?token=…). You redirect to or embed that URL. Gives you more control over the UI.checkoutUrl and handle all the per-method UI (QR, CLABE, redirect, voucher). You just redirect. 1 line of integration.country format: we accept ISO-2 ("MX", "BR","CO", …) and ISO-3 ("MEX", "BRA","COL", …) interchangeably. Internally we normalize to ISO-3 before routing, so either format works the same. If you pass paymentMethodId without country, the country is inferred from the 4-digit id (each one is tied to a specific country).