Cartes bancaires BaaS

Vue d'ensemble

YaniPay propose deux types de cartes bancaires via ses fournisseurs BaaS (Swan ou Treezor). Chaque carte est rattachee a un compte IBAN et peut etre geree entierement depuis l'application mobile ou l'API.

Types de cartes BaaS

Chaque carte emise par le fournisseur BaaS est representee par l'interface BaaSCard. Elle normalise les reponses Swan (GraphQL) et Treezor (REST) en un format commun.

1
interface BaaSCard {
2
  providerCardId: string;
3
  platformUserId: string;
4
  providerAccountId: string;
5
  status: 'PENDING' | 'ACTIVATED' | 'LOCKED' | 'CANCELED';
6
  maskedPan?: string;    // **** **** **** 1234
7
  brand: 'VISA' | 'MASTERCARD';
8
  type: 'VIRTUAL' | 'PHYSICAL';
9
  expiryDate?: string;
10
  createdAt: string;
11
}

Le champ maskedPanne contient que les 4 derniers chiffres de la carte, masques selon la norme PCI-DSS. Pour obtenir le numero complet (PAN), le CVV et la date d'expiration, utilisez la methode viewCardNumbers qui requiert une authentification forte PSD2/SCA.

Cycle de vie

Une carte passe par plusieurs etats au cours de sa vie. Le diagramme ci-dessous illustre les transitions possibles entre chaque statut.

Une carte CANCELED ne peut pas etre reactivee. Il faudra en creer une nouvelle. Le gel (LOCKED) est reversible et peut etre effectue par l'utilisateur depuis l'application mobile a tout moment.

Creer une carte

La creation d'une carte se fait via la methode createCarddu provider BaaS. Pour une carte physique, l'adresse de livraison est obligatoire.

1
interface CreateCardInput {
2
  platformUserId: string;
3
  providerAccountId: string;
4
  type: 'VIRTUAL' | 'PHYSICAL';
5
  deliveryAddress?: {    // Required for PHYSICAL
6
    firstName: string;
7
    lastName: string;
8
    addressLine1: string;
9
    city: string;
10
    postalCode: string;
11
    country: string;
12
  };
13
}

1
import { getBaaSProvider } from '@platform/core/baas/factory';
2
3
const baas = getBaaSProvider();
4
5
// Create a virtual card
6
const card = await baas.createCard({
7
  platformUserId: 'usr_123',
8
  providerAccountId: 'acc_456',
9
  type: 'VIRTUAL',
10
});
11
12
console.log(card.maskedPan);  // **** **** **** 7891
13
console.log(card.status);     // 'PENDING' or 'ACTIVATED'
14
console.log(card.brand);      // 'VISA' or 'MASTERCARD'

Les cartes virtuelles sont generalement activees immediatement (statut ACTIVATED). Les cartes physiques restent en statut PENDINGjusqu'a leur activation par l'utilisateur apres reception.

Voir les numeros (SCA)

La directive europeenne DSP2 (PSD2) impose une authentification forte du client(SCA - Strong Customer Authentication) pour l'affichage des donnees sensibles de la carte : numero complet (PAN), CVV et date d'expiration.

La methode viewCardNumbersdeclenche un flux de consentement qui redirige l'utilisateur vers la page d'authentification du fournisseur BaaS, puis le renvoie vers votre application avec les donnees dechiffrees.

1
import { getBaaSProvider } from '@platform/core/baas/factory';
2
import { redirect } from 'next/navigation';
3
4
const baas = getBaaSProvider();
5
6
// viewCardNumbers requires PSD2 Strong Customer Authentication
7
const numbers = await baas.viewCardNumbers?.(
8
  'card_789',
9
  'https://app.yanipay.com/consent/callback'
10
);
11
12
if (numbers?.consentUrl) {
13
  // Redirect user for SCA verification
14
  redirect(numbers.consentUrl);
15
}
16
17
// After consent approval:
18
// numbers.pan        -> '4970 1012 3456 7891'
19
// numbers.cvv        -> '123'
20
// numbers.expiryDate -> '12/28'

Gerer une carte

Le gel et le degel d'une carte sont des operations instantanees qui permettent a l'utilisateur de bloquer temporairement sa carte en cas de perte ou de doute sur une transaction frauduleuse.

1
import { getBaaSProvider } from '@platform/core/baas/factory';
2
3
const baas = getBaaSProvider();
4
5
// Lock (freeze) a card — blocks all transactions
6
await baas.lockCard('card_789');
7
// card.status -> 'LOCKED'
8
9
// Unlock (unfreeze) a card — re-enables transactions
10
await baas.unlockCard('card_789');
11
// card.status -> 'ACTIVATED'

Lorsqu'une carte est gelee (LOCKED), toutes les transactions sont refusees (paiements, retraits, abonnements). Le degel restaure immediatement la capacite de paiement. Ces operations sont egalement disponibles depuis l'ecran de gestion des cartes dans l'application mobile.

Livraison physique

Les cartes physiques suivent un processus de livraison en plusieurs etapes. Le fournisseur BaaS gere la fabrication et l'envoi postal de la carte a l'adresse fournie lors de la creation.

Le code PIN est envoye separement par courrier ou defini directement dans l'application mobile selon le fournisseur BaaS utilise. Pour les DOM-TOM, les delais de livraison peuvent etre legerement superieurs (7-10 jours ouvrables).

Integration mobile

L'application mobile React Native (Expo Router) expose un ecran dedie a la gestion des cartes bancaires dans mobile/app/banking/cards.tsx. Cet ecran permet de :

• Visualiser toutes les cartes (virtuelles et physiques)
• Creer une nouvelle carte virtuelle en un tap
• Geler / degeler une carte instantanement
• Afficher les numeros de carte via SCA (biometrie)
• Commander une carte physique avec saisie d'adresse

L'ecran communique avec l'API YaniPay via les endpoints documentes ci-dessous, en utilisant le service CardService (mobile/src/services/cardService.ts) qui encapsule les appels HTTP et la gestion du cache React Query.

Endpoints API

Les endpoints suivants permettent de gerer les cartes bancaires via l'API YaniPay. Tous les endpoints necessitent un token JWT valide dans le header Authorization.

Pages associees

Explorez les autres sections de la documentation BaaS pour comprendre l'ecosysteme complet :