Rely SDK

SDK serveur sans dépendance runtime pour les API publiques Identity, Organization, Billing, Wallet, Transactions, User et Inventory/POS de Rely.

Ne l'utilisez pas dans un navigateur ou une application mobile : secrets marchands, jetons de session/SDK et secrets webhook doivent rester côté serveur.

📖 Manuel d'utilisation complet : USAGE.md (configuration, tous les modules, gestion d'erreurs, webhooks, retries, sécurité). 📋 Contrats couverts et règles d'accès : API-COVERAGE.md.

Installation

npm install @relyfinancials/sdk

Checkout

import { Rely } from "@relyfinancials/sdk";

const rely = new Rely({
  clientId: process.env.RELY_CLIENT_ID,
  clientSecret: process.env.RELY_CLIENT_SECRET,
});

const checkout = await rely.checkout.create({
  amount: "499.00",
  currency: "HTG",
  destinationWalletId: process.env.RELY_ORGANIZATION_WALLET_ID,
  orderId: "ACME-1001",
  successUrl: "https://shop.example/orders/ACME-1001/success",
  cancelUrl: "https://shop.example/orders/ACME-1001/cancel",
  webhookUrl: "https://shop.example/webhooks/rely",
});

return checkout.checkout_url;

Lien de paiement

Les opérations Organization utilisent un bearer d'utilisateur ou un jeton SDK autorisé et propagent automatiquement X-Organization-ID.

const link = await rely.paymentLinks.create(organizationId, ownerAccessToken, {
  amount: "2500.00",
  currency: "HTG",
  destinationWalletId: organizationWalletId,
  webhookUrl: "https://shop.example/webhooks/rely",
  idempotencyKey: "invoice-2026-42",
});

Les helpers directs rely.paymentLinks.cancel(...) et rely.paymentLinks.refund(...) annulent un lien impayé et remboursent un paiement collecté. rely.checkout.cancel(...) et rely.checkout.refund(...) utilisent les identifiants Basic du marchand déjà configurés sur Rely. Un remboursement requiert amount et idempotencyKey; réutilisez la même clé après une réponse interrompue. Les opérations POS sont également disponibles sous rely.pos.refundSale(...), rely.pos.cancelSalePaymentLink(...), rely.billing.organization.cancelPosPaymentLink(...) et rely.billing.organization.refundPosPaymentLink(...).

Webhooks

Vérifier la signature sur le corps brut avant de parser le JSON, puis dédupliquer event_id (= en-tête X-Rely-Event-Id) durablement.

constructEvent vérifie et parse en une seule étape (rejette une signature invalide avant tout JSON.parse) :

import { constructWebhookEvent } from "@relyfinancials/sdk";

// rawBody = corps brut de la requête (Buffer/string), PAS un objet re-sérialisé.
const event = constructWebhookEvent(rawBody, request.headers["x-rely-signature"], process.env.RELY_WEBHOOK_SECRET);
// event = { event_id, event_type, data, ... }

if (await alreadyProcessed(event.event_id)) return; // idempotence
await handle(event);

La vérification seule reste disponible via verifyWebhookSignature(rawBody, signature, secret) (ou rely.webhooks.verifySignature(...)).

Modules

• checkout: création, lecture, annulation et remboursement de sessions checkout ;
• paymentLinks: création, liste, lecture, annulation et remboursement de paiements par lien ;
• organizations: liste, création, lecture et mise à jour d'organisation ;
• branches: création, lecture, modification, aperçu et cycle de vie des branches ;
• members et branchMembers: gestion des membres d'organisation et de branche ;
• invitations: consultation et acceptation des invitations par leur destinataire ;
• identity.sdkTokens: demande OTP, émission, liste et révocation de jetons SDK ;
• merchantApplications: création de l'identité technique marchande ;
• subscriptions: checkout d'abonnement, lecture et annulation ;
• webhooks: enregistrement, vérification HMAC et constructEvent (vérifie + parse).
• extensions: catalogue, installation et configuration des extensions d'organisation et de branche ;
• billing: paiements, factures, liens, abonnements, cotisations, dons, documents de vente, sol et airtime ;
• wallet et transactions: portefeuilles, demandes d'espèces et transferts ;
• user: profil, KYC, préférences, consentement et confidentialité ;
• inventory et pos: catalogue, stock, achats, caisse, ventes et reçus.

Les nouveaux domaines utilisent des méthodes nommées. Passez les variables de route dans l'objet d'options, les paramètres URL sous query et le JSON sous body, par exemple :

const products = await rely.inventory.listProducts(orgId, accessToken, {
  query: { branch_id: branchId },
});

const me = await rely.user.getMe(accessToken);
await rely.extensions.install(orgId, accessToken, {
  key: "pos",
  body: { plan_key: "standard", settings: {} },
});

Les routes d'organisation ajoutent X-Organization-ID. Les droits effectifs restent appliqués par les services. Les routes internes, console admin et appels d'usage interservices ne sont pas exposés.

La gestion des jetons SDK utilise une session utilisateur. L'acceptation d'une invitation utilise le bearer de la personne invitée. Le jeton SDK émis sert ensuite aux appels d'organisation autorisés.

Tests

npm test