Aller au contenu

Localpayment pour les développeurs

Construisez autour des spécificités locales.

Trouvez les guides de l’API, les exigences par pays, les outils de test et les exemples d’implémentation derrière chaque flux de paiement pris en charge.

Voir la documentationDémarrer le quickstart
  • REST + JSON
  • Webhooks signés HMAC
  • Sandbox Stage
  • Serveur MCP public

L’essentiel pour les développeurs

Documentation

Allez droit à l’essentiel

Liens directs vers docs.localpayment.com : guides, référence de l’API et outils.

Vos premiers appels

S’authentifier, encaisser, confirmer

Trois étapes couvrent la boucle principale : obtenir un jeton, créer un encaissement et vérifier le webhook signé qui le confirme. Le même modèle de requête, de statuts et de webhooks s’applique à tous les pays et moyens de paiement.

  • Les jetons expirent au bout de 5 minutes : renouvelez-les avec POST /api/token/refresh/
  • Envoyez votre propre externalId unique pour chaque transaction
  • Le statut final arrive par webhook, signé en HMAC-SHA256
Ouvrir la référence de l’API
# 1) Obtenez un jeton d’accès (Stage · valable 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) Créez un encaissement Pix (illustratif, valeurs fictives)
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" }
    }
  }'

Conception de l’API

Prévisible par conception

Des conventions identiques d’un produit et d’un pays à l’autre, pour que votre code d’intégration le reste aussi.

  • REST et JSON

    URL orientées ressources, verbes et codes HTTP standard, corps JSON. Les pays utilisent des codes ISO-3 comme BRA ou MEX.

  • Jetons Bearer de courte durée

    POST /api/token/ renvoie un jeton d’accès valable 5 minutes et un jeton de rafraîchissement valable 24 heures, envoyé en Authorization: Bearer.

  • Votre ID et le nôtre

    Chaque transaction porte votre externalId, et nous renvoyons notre internalId. Utilisez l’un ou l’autre pour consulter le statut ou rapprocher.

  • Protégé contre les doublons

    Réutiliser un externalId renvoie 409 Conflict au lieu de créer une seconde transaction : vous pouvez relancer sans risque une requête expirée.

  • Des codes pour décider

    Chaque réponse contient un objet status avec code, description et detail, plus un tableau errors. Les familles de codes indiquent la marche à suivre.

  • Limites de débit avec backoff

    Trop de requêtes renvoient 429. Relancez avec un backoff exponentiel et un circuit breaker, comme pour les réponses 5xx et le code 800.

Gestion des erreurs

Les familles de codes de statut en un coup d’œil

Chaque réponse inclut status.code. Le premier chiffre vous dit s’il faut attendre, corriger, relancer ou annuler.

  • 1xx

    Signification
    En attente
    Exemples
    100 INPROGRESS
    Que faire
    Attendre le webhook ou consulter le statut

  • 2xx

    Signification
    Succès
    Exemples
    200 COMPLETED
    Que faire
    Honorer la commande et mettre à jour votre registre

  • 3xx

    Signification
    Validation
    Exemples
    300 rejeté (paramètre invalide) · 301 non autorisé pour le pays
    Que faire
    Corriger la requête, ne pas la relancer telle quelle

  • 7xx

    Signification
    Règles métier
    Exemples
    701 compte invalide · 702 fonds insuffisants
    Que faire
    Afficher un message clair ou alerter votre équipe opérations

  • 8xx

    Signification
    Prestataire ou système
    Exemples
    800 erreur réessayable
    Que faire
    Relancer avec un backoff exponentiel

  • 9xx

    Signification
    Annulations
    Exemples
    902 remboursé · 904 abonnement annulé après échecs répétés · 906 rétrofacturation
    Que faire
    Annuler la livraison et mettre à jour votre registre

Statuts HTTP utilisés : 200, 201, 400, 401, 403, 404, 409, 429, 500, 502 et 503. Les tables de codes par type de transaction figurent dans la référence de la documentation.

Parcours d’intégration

Du premier appel à la production

L’essentiel du travail se fait sur Stage. L’accès à la production suit une revue de sécurité et la vérification de votre entreprise.

  1. 01

    Obtenir les identifiants Stage

    Les identifiants Stage sont délivrés au démarrage du partenariat. Enregistrez les IP de vos serveurs dans le Business Portal.

    Stage

  2. 02

    Développer et tester

    Intégrez encaissements, décaissements ou comptes virtuels, traitez les webhooks et jouez des scénarios d’échec avec des données de test.

    Stage

  3. 03

    Revue de sécurité et KYB

    Nous examinons votre intégration et finalisons la vérification de l’entreprise (KYB) avant de délivrer les identifiants de production.

    Conformité

  4. 04

    Passer en production et vous développer

    Basculez sur les identifiants et IP de production. Ajoutez des pays et des moyens de paiement par configuration, sans réintégration.

    Production

Outils IA pour développeurs

Laissez votre assistant IA lire la documentation

La documentation de Localpayment est conçue pour fonctionner avec les outils de développement assistés par IA, avec un serveur MCP, des prompts prêts à l’emploi et un accès structuré pensé pour les systèmes d’IA.

  • Serveur MCP sur docs.localpayment.com/mcp, sans authentification
  • Un index llms.txt et une version Markdown de chaque page de la documentation
  • Une bibliothèque de prompts et des agents d’intégration et de QA pour les frameworks d’agents les plus répandus
  • « Ask AI » intégré à la documentation
Découvrir les outils IA
{
  "mcpServers": {
    "localpayment-docs": {
      "url": "https://docs.localpayment.com/mcp"
    }
  }
}

Sécurité

Sécurisé par défaut, dès la première requête

Des contrôles intégrés à l’API et au Business Portal, pas ajoutés après coup.

  • Chiffrement en transit et au repos

    TLS 1.2+ en transit et AES-256 au repos, avec rotation des clés via AWS KMS.

  • Serveur à serveur uniquement

    Les appels transitent en HTTPS depuis votre backend. N’exposez jamais d’identifiants ni de jetons dans un navigateur ou une application mobile.

  • Liste blanche d’IP

    Seules les IP de serveur que vous autorisez dans le Business Portal peuvent appeler l’API, sur Stage comme en production.

  • Webhooks signés

    Chaque notification porte une signature HMAC-SHA256 : vous pouvez rejeter tout ce qui ne vient pas de nous.

  • Décaissements à double signature

    Exigez un second approbateur avant qu’un paiement sortant ne quitte votre compte, via l’API ou dans le portail.

  • MFA et accès par rôle

    Les utilisateurs du Business Portal se connectent avec une authentification multifacteur et ne reçoivent que les droits nécessaires à leur rôle.

FAQ développeurs

Existe-t-il un SDK ?

Il n’existe pas de SDK serveur officiel : l’API est du REST et du JSON standard, tout client HTTP convient. Pour les formulaires de carte, le SDK JavaScript Smart Fields tokenise les données de carte dans des champs hébergés afin de réduire votre périmètre PCI.

Comment obtenir des identifiants sandbox ?

Les identifiants Stage sont délivrés au démarrage du partenariat. Présentez-nous votre projet via le formulaire de contact et notre équipe vous accompagnera tout au long de l’onboarding.

Quelles URL de base utiliser ?

Stage : https://api.stage.localpayment.com. Production : https://api.v3.localpayment.com. Chaque environnement dispose de ses propres identifiants.

Combien de temps prend une intégration ?

Les équipes passent généralement en production en quelques semaines. Une fois intégré, vous ajoutez de nouveaux marchés par configuration, sans réintégration.

Comment sont gérés les relances et les doublons ?

Envoyez un externalId unique par transaction. Si vous relancez avec le même externalId, vous recevez 409 Conflict au lieu d’un doublon. Relancez les 429, 5xx et le code 800 avec un backoff exponentiel.

Où consulter l’état du service ?

Sur status.localpayment.com, qui couvre les services d’encaissement, de décaissement et d’authentification, les rails locaux et l’historique des incidents. Pour toute aide, écrivez à support@localpayment.com : le support est disponible 24/7.

Guides pour développeurs

Prêt à développer ?

Échangez avec notre équipe pour lancer le partenariat et recevoir vos identifiants Stage, ou explorez la documentation dès maintenant.

Voir la documentationDemander l’accès à Stage

Comment pouvons-nous vous aider ?

Téléchargez votre exemplaire

Laissez vos coordonnées et recevez l’édition complète immédiatement.