Skip to content

Localpayment for developers

Build around the local details.

Find the API guides, country requirements, testing tools and implementation examples behind each supported payment flow.

Go to our docsStart the quickstart
  • REST + JSON
  • HMAC-signed webhooks
  • Stage sandbox
  • Public MCP server

Developer essentials

Documentation

Jump straight to what you need

Deep links into docs.localpayment.com: guides, API reference and tools.

Your first calls

Authenticate, collect, confirm

Three steps cover the core loop: get a token, create a pay-in, and verify the signed webhook that confirms it. The same request, status and webhook model applies across countries and payment methods.

  • Tokens expire after 5 minutes — refresh with POST /api/token/refresh/
  • Send your own unique externalId on every transaction
  • The final status arrives by webhook, signed with HMAC-SHA256
Open the API reference
# 1) Get an access token (Stage · valid for 5 minutes)
ACCESS_TOKEN=$(curl -s -X POST https://api.stage.localpayment.com/api/token/ \
  -H "Content-Type: application/json" \
  -d "{\"username\": \"$LP_API_USER\", \"password\": \"$LP_API_PASSWORD\"}" \
  | jq -r .access)

# 2) Create a Pix pay-in (illustrative, fictitious values)
curl -X POST https://api.stage.localpayment.com/api/payin/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethod": { "type": "BankTransfer", "code": "1314", "flow": "DIRECT" },
    "externalId": "7c1e2f7a-0000-4000-8000-000000000001",
    "country": "BRA",
    "currency": "USD",
    "amount": 100,
    "accountNumber": "<your-account-number>",
    "conceptCode": "0003",
    "merchant": { "type": "COMPANY", "name": "Nortia Commerce Ltda" },
    "payer": {
      "type": "INDIVIDUAL",
      "name": "Maria",
      "lastname": "Silva",
      "document": { "type": "CPF", "id": "000.000.000-00" }
    }
  }'

API design

Predictable by design

Conventions that stay the same across products and countries, so your integration code does too.

  • REST and JSON

    Resource-oriented URLs, standard HTTP verbs and status codes, JSON bodies. Countries use ISO-3 codes such as BRA or MEX.

  • Short-lived bearer tokens

    POST /api/token/ returns an access token valid for 5 minutes and a refresh token valid for 24 hours, sent as Authorization: Bearer.

  • Your ID and ours

    Every transaction carries your externalId, and we return our internalId. Use either one to query status or reconcile.

  • Duplicate-safe

    Reusing an externalId returns 409 Conflict instead of creating a second transaction, so you can safely retry a request that timed out.

  • Status codes you can branch on

    Every response has a status object with code, description and detail, plus an errors array. Code families tell you what to do next.

  • Rate limits with backoff

    Too many requests return 429. Retry with exponential backoff and a circuit breaker — the same for 5xx responses and code 800.

Error handling

Status code families at a glance

Every response includes status.code. The first digit tells you whether to wait, fix, retry or reverse.

  • 1xx

    Meaning
    Pending
    Examples
    100 INPROGRESS
    What to do
    Wait for the webhook, or query the status

  • 2xx

    Meaning
    Success
    Examples
    200 COMPLETED
    What to do
    Fulfill the order and update your ledger

  • 3xx

    Meaning
    Validation
    Examples
    300 rejected (invalid parameter) · 301 not authorized for the country
    What to do
    Fix the request — do not retry it unchanged

  • 7xx

    Meaning
    Business rules
    Examples
    701 invalid account · 702 insufficient funds
    What to do
    Show a clear message or alert your operations team

  • 8xx

    Meaning
    Provider or system
    Examples
    800 retryable error
    What to do
    Retry with exponential backoff

  • 9xx

    Meaning
    Reversals
    Examples
    902 refunded · 904 subscription canceled after failed retries · 906 chargeback
    What to do
    Reverse the fulfillment and update your ledger

HTTP statuses in use: 200, 201, 400, 401, 403, 404, 409, 429, 500, 502 and 503. Code tables for each transaction type are in the docs reference.

Integration journey

From first call to production

Most of the work happens on Stage. Production access follows a security review and business verification.

  1. 01

    Get Stage credentials

    Stage credentials are issued when the partnership starts. Allow-list your server IPs in the Business Portal.

    Stage

  2. 02

    Build and test

    Integrate pay-ins, payouts or virtual accounts, handle webhooks and run failure scenarios with test data.

    Stage

  3. 03

    Security review and KYB

    We review your integration and complete business verification (KYB) before issuing production credentials.

    Compliance

  4. 04

    Go live and expand

    Switch to production credentials and IPs. Add countries and methods through configuration, not reintegration.

    Production

AI developer tools

Let your AI assistant read the docs

Localpayment’s documentation is built to work with AI-assisted development tools, including an MCP server, ready-to-use prompts, and structured access designed for AI systems.

  • MCP server at docs.localpayment.com/mcp — no authentication needed
  • An llms.txt index and a Markdown version of every docs page
  • A prompt library, plus integrator and QA agents for popular agent frameworks
  • “Ask AI” built into the documentation
Explore AI tools
{
  "mcpServers": {
    "localpayment-docs": {
      "url": "https://docs.localpayment.com/mcp"
    }
  }
}

Security

Secure by default, from the first request

Controls built into the API and the Business Portal, not bolted on later.

  • Encryption in transit and at rest

    TLS 1.2+ in transit and AES-256 at rest, with keys rotated through AWS KMS.

  • Server-to-server only

    Calls go over HTTPS from your backend. Never expose credentials or tokens in a browser or mobile app.

  • IP allow-listing

    Only the server IPs you allow-list in the Business Portal can call the API, for Stage and for Production.

  • Signed webhooks

    Every notification carries an HMAC-SHA256 signature, so you can reject anything we did not send.

  • Double-signature payouts

    Require a second approver before a payout leaves your account, through the API or in the portal.

  • MFA and role-based access

    Business Portal users sign in with multi-factor authentication and get only the permissions their role needs.

Developer FAQ

Is there an SDK?

There are no official server SDKs: the API is plain REST and JSON, so any HTTP client works. For card forms, the Smart Fields JavaScript SDK tokenizes card data in hosted fields to reduce your PCI scope.

How do I get sandbox credentials?

Stage credentials are issued at the start of the partnership. Tell us about your project through the contact form and our team will guide you through onboarding.

Which base URLs do I use?

Stage: https://api.stage.localpayment.com. Production: https://api.v3.localpayment.com. Each environment has its own credentials.

How long does an integration take?

Teams typically go live in weeks. Once you are integrated, new markets are added by configuration, without reintegrating.

How are retries and duplicates handled?

Send a unique externalId per transaction. If you retry with the same externalId, you get 409 Conflict instead of a duplicate. Retry 429, 5xx and code 800 with exponential backoff.

Where can I check service health?

At status.localpayment.com, which covers pay-in, payout and authentication services, local rails and incident history. For help, email support@localpayment.com — support is available 24/7.

Developer guides

Ready to build?

Talk to our team to start your partnership and receive Stage credentials, or explore the docs right now.

Go to our docsRequest Stage access

How can we help?

Download your copy

Leave your details and get the full edition instantly.