BCard - Documentation technique

DjomyService
in package

BCard

Client de la passerelle de paiement Djomy (Guinée).

Chaque requête porte l'en-tête X-API-KEY (<clientId>:<HMAC-SHA256 du clientId signé avec le clientSecret>). Les appels de paiement exigent en plus un jeton Bearer obtenu via POST /v1/auth et conservé dans le cache applicatif pendant sa durée de validité moins cinq minutes. Le service expose la création d'un paiement « gateway » (redirection vers la page sécurisée Djomy), la lecture du statut d'une transaction et la vérification de la signature des webhooks. Aucune clé, aucun secret ni jeton n'est écrit dans les journaux.

Constants

TIMEOUT : mixed = 20
TOKEN_MARGIN : mixed = 300

Properties

$apiUrl : string
$cache : CacheInterface
$clientId : string
$clientSecret : string
$httpClient : HttpClientInterface
$logger : LoggerInterface

Methods

__construct() : mixed
createGatewayPayment() : array{transactionId: string, redirectUrl: string, status: string|null}: Crée un paiement « gateway » et renvoie l'URL de redirection vers la page de paiement Djomy.
getPaymentStatus() : array<string, mixed>: Lit le statut d'une transaction auprès de Djomy.
isConfigured() : bool: Indique si les trois paramètres de connexion sont renseignés.
isSuccessful() : bool: Indique si les données de statut Djomy attestent d'un paiement abouti.
normalizePhone() : string|null: Normalise un numéro de téléphone au format attendu par Djomy (`00224XXXXXXXXX`).
paymentIdFromReference() : int|null: Extrait l'identifiant du paiement d'une référence marchande `BCARD-PAY-<id>` ou `BCARD-PAY-<id>-R<timestamp>`.
recordProviderStatus() : void: Mémorise sur le paiement le dernier statut communiqué par Djomy.
verifyWebhookSignature() : bool: Vérifie la signature d'un webhook.
apiKey() : string: Construit la valeur de l'en-tête `X-API-KEY`.
extractData() : array<string, mixed>: Contrôle le code HTTP et l'indicateur `success`, puis renvoie le bloc `data`.
getAccessToken() : string: Renvoie le jeton d'accès, en l'obtenant via `POST /v1/auth` s'il n'est pas en cache.
request() : array<string, mixed>: Exécute une requête authentifiée et renvoie le bloc `data` de la réponse.
safePath() : string: Chemin sans identifiant de transaction, pour des messages et journaux homogènes.
send() : array{0: int, 1: array|null}: Envoie la requête HTTP et décode le JSON de la réponse.
toInteger() : int: Convertit un montant en entier (le GNF n'a pas de décimales).
tokenCacheKey() : string: Clé de cache du jeton, propre à l'URL et à l'identifiant client (sans exposer ce dernier).

TIMEOUT


    private
        mixed
    TIMEOUT
    = 20

TOKEN_MARGIN


    private
        mixed
    TOKEN_MARGIN
    = 300

$apiUrl read-only


        private
            string
    $apiUrl

$cache read-only


        private
            CacheInterface
    $cache

$clientId read-only


        private
            string
    $clientId

$clientSecret read-only


        private
            string
    $clientSecret

$httpClient read-only


        private
            HttpClientInterface
    $httpClient

$logger read-only


        private
            LoggerInterface
    $logger

__construct()


    public
                    __construct(HttpClientInterface $httpClient, CacheInterface $cache, LoggerInterface $logger, string $apiUrl, string $clientId, string $clientSecret) : mixed

Parameters

$httpClient : HttpClientInterface: Client HTTP Symfony.
$cache : CacheInterface: Cache applicatif (cache.app) portant le jeton d'accès.
$logger : LoggerInterface: Journalise les échecs d'appel, sans donnée sensible.
$apiUrl : string: URL de base de l'API (sandbox ou production), vide si non configurée.
$clientId : string: Identifiant client Djomy.
$clientSecret : string: Secret client Djomy (signature de l'API et des webhooks).

createGatewayPayment()

Crée un paiement « gateway » et renvoie l'URL de redirection vers la page de paiement Djomy.


    public
                    createGatewayPayment(float|int|string $amount, string $payerNumber, string $merchantReference, string $description, string $returnUrl[, string|null $cancelUrl = null ]) : array{transactionId: string, redirectUrl: string, status: string|null}

Le montant est converti en entier (le GNF n'a pas de décimales ; une chaîne comme "150000.00" est tolérée). L'URL de retour doit être en HTTPS pour être acceptée par Djomy.

Parameters

$amount : float|int|string: Montant en GNF.
$payerNumber : string: Numéro du payeur au format 00224XXXXXXXXX (voir self::normalizePhone()).
$merchantReference : string: Référence marchande unique de la transaction.
$description : string: Libellé affiché au payeur.
$returnUrl : string: URL absolue de retour après paiement.
$cancelUrl : string|null = null: URL absolue en cas d'annulation (facultative).

Return values

array{transactionId: string, redirectUrl: string, status: string|null}

getPaymentStatus()

Lit le statut d'une transaction auprès de Djomy.


    public
                    getPaymentStatus(string $transactionId) : array<string, mixed>

Parameters

$transactionId : string: Identifiant de transaction renvoyé à la création.

Return values

array<string, mixed> —

Bloc data de la réponse (status, paidAmount, merchantPaymentReference, currency…).

isConfigured()

Indique si les trois paramètres de connexion sont renseignés.


    public
                    isConfigured() : bool

Return values

bool —

true si l'URL, l'identifiant et le secret sont non vides.

isSuccessful()

Indique si les données de statut Djomy attestent d'un paiement abouti.


    public
                    isSuccessful(array<string, mixed> $data) : bool

Seul status = SUCCESS fait foi : paidAmount est renseigné même pour une transaction non payée. Si une devise est fournie et diffère de GNF, le paiement n'est pas accepté (warning journalisé).

Parameters

$data : array<string, mixed>: Bloc data d'une réponse de statut.

Return values

bool —

true si le statut est SUCCESS et la devise, quand elle est fournie, est GNF.

normalizePhone()

Normalise un numéro de téléphone au format attendu par Djomy (`00224XXXXXXXXX`).


    public
            static        normalizePhone(string $phone) : string|null

Ne conserve que les chiffres. +224… et 224… deviennent 00224…, un numéro guinéen local à 9 chiffres commençant par 6 est préfixé par 00224, un numéro commençant déjà par 00 est conservé.

Parameters

$phone : string: Numéro saisi par l'utilisateur.

Return values

string|null —

Numéro normalisé, ou null s'il est invalide.

paymentIdFromReference()

Extrait l'identifiant du paiement d'une référence marchande `BCARD-PAY-<id>` ou `BCARD-PAY-<id>-R<timestamp>`.


    public
            static        paymentIdFromReference(string $reference) : int|null

Parameters

$reference : string: Référence marchande.

Return values

int|null —

Identifiant du paiement, ou null si la référence n'a pas ce format.

recordProviderStatus()

Mémorise sur le paiement le dernier statut communiqué par Djomy.


    public
                    recordProviderStatus(Payment $payment, string|null $status) : void

N'écrit que providerStatus (en majuscules) et providerStatusAt ; Payment::status n'est jamais touché et aucun flush() n'est déclenché : l'appelant persiste. Un statut vide ou null est ignoré, de même qu'un statut autre que SUCCESS sur un paiement déjà COMPLETED. Attention : PaymentFulfillmentService::fulfill() fait un refresh(), l'appelant doit donc flusher avant de valider un paiement s'il veut conserver cette valeur.

Parameters

$payment : Payment: Paiement concerné.
$status : string|null: Statut Djomy brut (SUCCESS, FAILED, CANCELLED, TIMEOUT, PENDING…).

verifyWebhookSignature()

Vérifie la signature d'un webhook.


    public
                    verifyWebhookSignature(string $rawBody, string|null $header) : bool

Hypothèse : l'en-tête X-Webhook-Signature vaut v1:<hex(HMAC_SHA256(corps brut, clientSecret))>. Le format exact n'étant pas documenté, la comparaison est à confirmer lors des premiers essais réels.

Parameters

$rawBody : string: Corps brut de la requête, tel que reçu.
$header : string|null: Valeur de l'en-tête X-Webhook-Signature.

Return values

bool —

true si la signature correspond.

apiKey()

Construit la valeur de l'en-tête `X-API-KEY`.


    private
                    apiKey() : string

Return values

string —

<clientId>:<hex(HMAC_SHA256(clientId, clientSecret))>.

extractData()

Contrôle le code HTTP et l'indicateur `success`, puis renvoie le bloc `data`.


    private
                    extractData(string $method, string $path, int $status, array<string, mixed>|null $body) : array<string, mixed>

Parameters

$method : string: Verbe HTTP (pour le message d'erreur).
$path : string: Chemin de l'API (pour le message d'erreur).
$status : int: Code HTTP reçu.
$body : array<string, mixed>|null: Corps JSON décodé.

Return values

array<string, mixed>

getAccessToken()

Renvoie le jeton d'accès, en l'obtenant via `POST /v1/auth` s'il n'est pas en cache.


    private
                    getAccessToken() : string

Return values

string —

Jeton Bearer.

request()

Exécute une requête authentifiée et renvoie le bloc `data` de la réponse.


    private
                    request(string $method, string $path[, array<string, mixed>|null $payload = null ][, bool $retry = true ]) : array<string, mixed>

Si l'API répond 401, le jeton en cache est invalidé et la requête rejouée une fois.

Parameters

$method : string: Verbe HTTP.
$path : string: Chemin de l'API, commençant par /.
$payload : array<string, mixed>|null = null: Corps JSON, null pour une requête sans corps.
$retry : bool = true: true tant qu'un rejeu après 401 est permis.

Return values

array<string, mixed>

safePath()

Chemin sans identifiant de transaction, pour des messages et journaux homogènes.


    private
                    safePath(string $path) : string

Parameters

$path : string

Return values

string

send()

Envoie la requête HTTP et décode le JSON de la réponse.


    private
                    send(string $method, string $path, array<string, mixed> $options) : array{0: int, 1: array|null}

Parameters

$method : string: Verbe HTTP.
$path : string: Chemin de l'API.
$options : array<string, mixed>: Options du client HTTP.

Return values

array{0: int, 1: array|null} —

Code HTTP et corps décodé (null si non JSON).

toInteger()

Convertit un montant en entier (le GNF n'a pas de décimales).


    private
                    toInteger(float|int|string $amount) : int

Parameters

$amount : float|int|string: Montant, éventuellement sous forme de chaîne ("150000.00").

Return values

int —

Montant arrondi à l'unité.

tokenCacheKey()

Clé de cache du jeton, propre à l'URL et à l'identifiant client (sans exposer ce dernier).


    private
                    tokenCacheKey() : string

Return values

string

DjomyService in package BCard

Table of Contents

Constants

Properties

Methods

Constants

TIMEOUT

TOKEN_MARGIN

Properties

$apiUrl read-only

$cache read-only

$clientId read-only

$clientSecret read-only

$httpClient read-only

$logger read-only

Methods

__construct()

Parameters

createGatewayPayment()

Parameters

Tags

Return values

getPaymentStatus()

Parameters

Tags

Return values

isConfigured()

Return values

isSuccessful()

Parameters

Return values

normalizePhone()

Parameters

Return values

paymentIdFromReference()

Parameters

Return values

recordProviderStatus()

Parameters

verifyWebhookSignature()

Parameters

Return values

apiKey()

Return values

extractData()

Parameters

Tags

Return values

getAccessToken()

Tags

Return values

request()

Parameters

Tags

Return values

safePath()

Parameters

Return values

send()

Parameters

Tags

Return values

toInteger()

Parameters

Tags

Return values

tokenCacheKey()

Return values

DjomyService
in package

BCard