SDK

Introduction

Nos bibliothèques connectent votre code à notre API de paiement.

Python, Typescript (NodeJS) et PHP sont pris en charge.

Installation

Prérequis

Version du SDK	PHP minimum	Testé jusqu'à
1.x	7.1	8.2
2.x	8.1	8.4

Utilisez composer :

composer install stancer/stancer

Configuration

Définissez vos clés API une fois par requête :

use Stancer;

$config = new Stancer\Config();
$config->setKeys(["ptest_xxxx", "pprod_xxx", "stest_xxx", "sprod_xxx"]);

WARNING

N'écrivez jamais les clés API dans votre code. Utilisez un vault ou des variables d'environnement, pour les garder en sécurité.

Version de l'API

La version par défaut pour le SDK php et python est la version 1 (legacy). Pour changer de version :

$config->setVersion(2);

Concepts fondamentaux

Créer un objet

$object = new Stancer\Object();

Créer un objet avec des données

$object = new Stancer\Object(["data1" => 0, "data2" => "foo"]);

Récupérer un objet existant

$object = new Stancer\Object("obj_xxx");

Les données ne se chargent que lorsque vous y accédez (par exemple, $object->getData()).

Lister les objets

Tous les objets peuvent être listés.

$listOfObjects = object::list([
    'created' => 1761661063,
    'created_until' => 1900000000,
    'limit' => 100,
    'start' => 0,
]);

Paramètre	Type	Requis
created	DateTime, timestamp ou DatePeriod	Oui
created_until	DateTime ou timestamp	Non
limit	int	Non
start	int	Non

Envoyer un objet

$object->send();

Cela gère automatiquement GET, POST et PATCH en fonction de l'état de l'objet.

Récupérer la date de création

$object->getCreated();
// ou
$object->getCreatedAt();

Vue d'ensemble des objets

Objet	Rôle
Payment Intents	Créer et gérer des transactions
Payment	Créer et gérer des paiements
Card	Moyen de paiement par carte bancaire
SEPA	Moyen de paiement par prélèvement
Customer	Informations sur le client
Refund	Traiter des remboursements
Payout	Consulter les virements (lecture seule)
Dispute	Consulter les litiges (lecture seule)

Payment Intents

Le payment intent est l'objet central. Utilisez-le pour créer des transactions et traiter des paiements.

Créer un payment intent

$paymentIntent = new Stancer\PaymentIntent();

Authentification

$paymentIntent->setAuth(true);

INFO

L'envoi sans authentification est déprécié. Utilisez un booléen (true).

Envoyer un paiement

Un payment intent a besoin au minimum d'un amount (en centimes, et supérieur à 50 centimes) et d'une currency pour pouvoir être envoyé.

$paymentIntent->setAmount(100); // en centimes
$paymentIntent->setcurrency(Stancer\Currency::EUR);
$paymentIntent->send();

Capturer un payment intent

Capture manuelle (par défaut) : À la fin du processus de paiement, le payment intent est authorized (autorisé). Vous devez encore le capturer pour changer son statut en processing (en cours de traitement).

$paymentIntent->capture();

Capture instantanée : Si vous définissez capture à true, le payment intent sera automatiquement capturé à la fin du processus de paiement.

$paymentIntent->setCapture(true);

Traiter un payment intent

Récupérer l'URL d'une page de paiement :

$paymentIntent->setReturnUrl("https://stancer.com");
$url = $paymentIntent->getPaymentPageUrl();

L'URL peut être intégrée (embed) ou utilisée comme redirection.

Payments

Privilégiez l'utilisation du payment intent plutôt que du payment.

Certains statuts peuvent être plus détaillés sur le payment.

Récupérer un payment

1. Via un payment intent a. Récupérer le dernier payment lié à un payment intent

$payment = $paymentIntent->getPayment();

b. Récupérer la liste des payments liés à un payment intent

$paymentList = $paymentIntent->getPayments();

2. Directement par ID

$payment = new Stancer\Payment('paym_xxx');

Rembourser un payment

$payment->refund(50); // centimes, laisser vide pour un remboursement total

WARNING

Remboursement total : nécessite un payment autorisé.

Remboursement partiel : nécessite un payment capturé (généralement 24 heures après l'autorisation).

Cartes

WARNING

Les données de carte sont sensibles. Vous devez respecter les règles PCI DSS en fonction de votre volume de transactions.

Champ	Exigence
Number	16 à 19 chiffres (à ne jamais stocker)
Exp Month	1 à 12
Exp Year	De l'année courante à 2099
CVC	3 chiffres (à ne jamais stocker)

$card = new Stancer\Card();
$card->setNumber("4242424242424242"); // numéro de carte de test
$card->setExpMonth(12);
$card->setExpYear(2050);
$card->setCvc("021"); // Le CVC est de type string, pas de type int

INFO

Ne stockez que les last4 (4 derniers chiffres), jamais le numéro de carte complet.

SEPA

Le prélèvement SEPA nécessite une activation sur votre compte.

Champ	Exigence
Name	Nom du titulaire
IBAN	IBAN valide
Mandate	Pour la capture du paiement
Mandate Date	Pour la capture du paiement

$sepa = new Stancer\Sepa();
$sepa->setName("Gilles Dupont");
$sepa->setIban("FR9430003000409249176322Z50");
$sepa->setMandate("mndt_xxx");
$sepa->setDateMandate($date_mandate); // objet DateTime

Customers

L'email ou le mobile est obligatoire (au moins l'un des deux).

Champ	Exigence
Name	3 à 64 caractères
Email	3 à 64 caractères
Mobile	Numéro de téléphone valide
BillingAddress	Adresse

$customer = new Stancer\Customer();
$customer->setName('John Doe');
$customer->setEmail("example@example.com");

Refunds

Création via l'objet Payment ou via l'objet Refund :

$refund = new Stancer\Refund();
$refund->setPayment($payment);
$refund->setAmount(50); // centimes, omettre pour un remboursement total
$refund->send();

Payouts and Disputes

Créés par l'API Stancer.

Vous pouvez uniquement les lire ou les lister.

$payout = new Stancer\Payout("pout_xxx");
$dispute = new Stancer\Dispute("dspt_xxx");