@monedo/payments-react-native

SDK-ul mobil oficial Monedo Payments. Aplicația importă numai interfața Monedo; datele sensibile ale cardului sunt colectate direct de componentele native ale furnizorului de servicii de plată și nu tranzitează API-ul Monedo. Wallet-urile, SCA și 3DS sunt executate în același flux securizat al furnizorului.

Instalare

npx expo install @monedo/payments-react-native

În proiectele Expo, activează pluginul oficial Monedo:

{
  "expo": {
    "plugins": [
      ["@monedo/payments-react-native/app.plugin.cjs", { "enableGooglePay": true }]
    ]
  }
}

Pluginul configurează automat dependențele native necesare. Aplicația gazdă nu trebuie să importe sau să configureze direct infrastructura furnizorului de plăți.

Cerințe

• React Native 0.81 sau mai nou;
• Expo Go SDK 54 poate rula checkout, 3DS și adăugarea cardurilor;
• un build nativ nou este necesar numai dacă aplicația schimbă versiunea nativă inclusă;
• sesiuni mobile create de backendul aplicației cu @monedo/payments;
• niciodată chei API secrete în aplicația mobilă.

Codul aplicației importă și configurează numai @monedo/payments-react-native.

Provider

import { MonedoPaymentsProvider } from '@monedo/payments-react-native';

export function App() {
  return (
    <MonedoPaymentsProvider
      publishableKey={bootstrap.publishable_key}
      clientAccountId={bootstrap.client_account_id}
      urlScheme="com.example.app"
    >
      <RootNavigator />
    </MonedoPaymentsProvider>
  );
}

client_account_id este opac și apare numai pentru integrările cu plăți directe într-un cont conectat. Nu îl deduce și nu îl înlocui cu ID-ul public al comerciantului.

Checkout

import { useMonedoPayments } from '@monedo/payments-react-native';

const { presentCheckout } = useMonedoPayments();
const result = await presentCheckout(sessionFromBackend, {
  merchantDisplayName: 'Example',
  returnURL: 'com.example.app://payments-return',
});

if (result.status === 'succeeded') {
  // Backendul confirmă starea finală din API/webhook.
}

Pentru o autorizare cu un card salvat care necesită 3DS, folosește același contract de sesiune și nu importa direct SDK-ul procesatorului:

import { presentMonedoNextAction } from '@monedo/payments-react-native';

const result = await presentMonedoNextAction(sessionFromBackend, {
  returnURL: 'com.example.app://payments-return',
});

Checkout-ul acceptă atât sesiuni cu customer_session_client_secret, cât și plăți fără client salvat. Nu considera rezultatul UI drept sursă contabilă finală; confirmă plata din backend.

CustomerSheet

CustomerSheet-ul modern necesită un development build compatibil. Pentru Expo Go folosește presentMonedoSetup, apoi listează, selectează și șterge cardurile prin API-ul Monedo.

Pentru administrarea cardurilor, backendul creează o sesiune nouă folosind:

const session = await monedo.customers.createCustomerSheetSession(customerId, {
  usage: 'on_session',
}, {
  idempotencyKey: crypto.randomUUID(),
});

În aplicația mobilă, furnizează o funcție care poate obține secrete proaspete. CustomerSession este single-use și poate fi solicitat din nou de componenta nativă:

const result = await presentMonedoCustomerSheet(
  () => api.createCustomerSheetSession(),
  {
    merchantDisplayName: 'Example',
    returnURL: 'com.example.app://payments-return',
    style: 'alwaysDark',
  },
);

Poți transmite și un obiect sesiune pentru o singură prezentare. Varianta callback este recomandată pentru refresh și reîncercări.

Contractul modern folosește:

• customer: ID-ul public Monedo, folosit numai în API-ul server-side;
• client_customer_id: contextul nativ opac, consumat numai de SDK;
• client_account_id: contextul Connect opac, dacă este necesar;
• customer_session_client_secret: acces temporar la cardurile clientului;
• setup_intent_client_secret: adăugarea securizată a unui card;
• publishable_key: cheia publicabilă a mediului.

SDK-ul nu transformă customer_session_client_secret într-un ephemeral key. Fluxul legacy cu ephemeral_key_secret este acceptat numai dacă backendul îl returnează explicit.

Adăugare card în Expo Go

import { presentMonedoSetup } from '@monedo/payments-react-native';

const result = await presentMonedoSetup(
  () => api.createCustomerSheetSession(),
  {
    merchantDisplayName: 'Example',
    returnURL: 'com.example.app://payments-return',
  },
);

Acest flux consumă numai setup_intent_client_secret și este compatibil cu PaymentSheet-ul livrat de Expo Go SDK 54.

Componente declarative

<MonedoCheckout
  visible={checkoutVisible}
  session={checkoutSession}
  options={{ merchantDisplayName: 'Example' }}
  onResult={handleCheckoutResult}
/>

<MonedoCustomerSheet
  visible={cardsVisible}
  session={() => api.createCustomerSheetSession()}
  options={{ merchantDisplayName: 'Example' }}
  onResult={handleCardsResult}
/>

Componentele sunt headless: afișează interfața nativă numai la tranziția visible=false -> visible=true și întorc rezultatul prin onResult.

Rezultate și erori

Toate prezentările întorc unul dintre statusurile:

• succeeded;
• cancelled;
• failed.

Erorile au forma { code, message, localizedMessage }. SDK-ul aruncă MonedoPaymentsSdkError numai pentru configurare sau contract invalid; erorile de prezentare sunt întoarse în rezultat.

Reguli de securitate

• Nu loga client_secret, customer_session_client_secret sau setup_intent_client_secret.
• Nu persista secretele mobile.
• Nu pune cheia secretă Monedo în aplicație.
• Nu folosi ID-urile client_* în endpointurile server-side.
• Confirmă statusul financiar prin webhook sau citirea plății din backend.