Key2Pay - Payment Gateway Processor

Create → accept → pay

POST /payments returns 201 awaiting_consent and a sessionId; no transaction exists and the provider has not been called. Redirect the buyer to the Key2Pay checkoutUrl. The buyer reviews the amount, currency, method and terms and explicitly accepts before payment is initiated.

json

{
  "sessionId": "cs_example",
  "transactionId": null,
  "status": "awaiting_consent",
  "consentRequired": true,
  "checkoutUrl": "https://sandbox.key2pay.ai/checkout/cs_example",
  "amount": 600,
  "currency": "USD"
}

The same rule applies to every method, including Boleto, PIX, SPEI, cards and redirect payments. hostedCheckout: false, an API key or a consent field cannot bypass this step. Optional document policies do not disable buyer acknowledgement.

Retrieve the result

After acceptance, retrieve completedTxId from GET /checkout/sessions/{token}, query GET /payments by merchantOrderId or receive the normal webhooks. A 201 session does not confirm a payment. Keep the same Idempotency-Key and body for retries; they return the original session.

Existing payments and limits

Retries preserve the original contract and response even when the requested version changes. Legacy API operations retain their instructions. Consent operations remain protected until valid acceptance is verified. Completed historical operations do not receive invented retrospective acceptance. Out-of-range amounts still return 422 amount_out_of_limits before any provider call.