Skip to content
Developer guide

Introduction

What Key2Pay is and how the API is shaped.

The Key2Pay API exposes a small, opinionated surface for accepting local payments across LATAM, EU, and APAC and settling them as crypto. It is RESTful, returns JSON, and uses standard HTTP verbs and status codes. Everything you can do from the dashboard, you can do from the API.

Operation currency is USD by default. Settlement follows the shop balance model. The `amount` you send is in USD major units unless you pass a `currency`. Optionally you can initiate in a PRESENTMENT currency (`currency: "EUR"`, `"MXN"`, …): we convert `amount` (in that currency) to a USD headline at our rate minus the FX markup. Ledger credits and settlement follow the shop balance model (USD or local currency). In the RESPONSE your presentment values come back as `inputCurrency` + `inputAmount`, and `currency` is ALWAYS `"USD"` (the converted USD is `amount`). New fractional requests round upward before FX. When presentment matches the rail currency, the accepted amount is the local request; otherwise it is converted once at creation. `amountLocal` + `currencyLocal` describe the local request, with exact provider-calculated amounts preserved.
USD-model shops accept USD or supported local-currency requests and are credited in USD. Local Currency shops require the country's enabled native currency: MXN for Mexico, BRL for Brazil, USD for Ecuador. A different currency is rejected. Local principal stays in that currency without entry FX markup; converting available funds to USD is a separate quoted swap. Each provider's currency contract is preserved, including a provider-fixed USD amount when applicable.

Highlights

Hosted checkout
Drop-in payment page with live cascade and risk routing.
Server APIs
Direct charge, refund, retrieve, and list with offset-based pagination.
Signed webhooks
HMAC-SHA256 with replay protection and timestamp window.

Design principles

  • Predictable: standard HTTP semantics, no envelope on success bodies, never an HTML error.
  • Idempotent: every money-moving POST (/payments, /withdrawals, /payments/{id}/refund) accepts Idempotency-Key.
  • Versioned: pin a date and stay on it. New optional fields are not breaking changes.
  • Compliant by default: hosted checkout keeps PAN out of your servers; webhooks are signed.
Key2Pay Developer documentationAPI v1
Documentation
Dashboard