Autenticación

Todas las solicitudes (excepto /health) requieren su clave API en el header HTTP:

HTTP Headercopiar
X-API-Key: votre_api_key_ici

O mediante Bearer token:

HTTP Headercopiar
Authorization: Bearer votre_api_key_ici

Modo TEST / LIVE

Dos modos disponibles para desarrollar y probar sin riesgo.

Flujo de pago

Endpoints

curlcopiar
curl https://pslwallet.com/pslwallet/api/v1/health

Respuesta 200
{
  "success": true,
  "status":  "ok",
  "api":     "PSLWallet v1",
  "mode":    "live",
  "db":      "connected"
}

curlcopiar
curl -X POST https://pslwallet.com/pslwallet/api/v1/payment/initiate \
  -H "X-API-Key: votre_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount":         25.00,
    "description":    "Commande #1042",
    "customer_email": "client@email.com",
    "order_id":       "CMD-1042",
    "redirect_url":   "https://monsite.com/confirm",
    "metadata": { "product_id": "42", "user_id": "789" }
  }'

Respuesta 201
{
  "success":        true,
  "order_id":       "CMD-1042",
  "reference":      "PSL-71F9B1C08DA0EA84",
  "payment_url":    "https://pslwallet.com/pslwallet/pay/PSL-71F9B1C08DA0EA84",
  "amount":         25.00,
  "currency":       "USD",
  "status":         "pending",
  "mode":           "live",
  "expires_at":     "2026-03-16T21:30:00+00:00",
  "customer": { "name": "Jean Dupont", "can_pay": true, "balance": 100.00 }
}

Por order_id — recomendadocopiar
curl "https://pslwallet.com/pslwallet/api/v1/payment/status?order_id=CMD-1042" \
  -H "X-API-Key: votre_api_key"

Por reference PSLWalletcopiar
curl "https://pslwallet.com/pslwallet/api/v1/payment/status?ref=PSL-71F9B1C08DA0EA84" \
  -H "X-API-Key: votre_api_key"

curlcopiar
curl https://pslwallet.com/pslwallet/api/v1/payment/verify/PSL-71F9B1C08DA0EA84 \
  -H "X-API-Key: votre_api_key"

curlcopiar
curl -X POST https://pslwallet.com/pslwallet/api/v1/payment/refund \
  -H "X-API-Key: votre_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "order_id": "CMD-1042", "reason": "Client annulé" }'

curlcopiar
curl "https://pslwallet.com/pslwallet/api/v1/balance?email=votre@email.com" \
  -H "X-API-Key: votre_api_key"

Respuesta 200
{
  "success":       true,
  "has_account":   true,
  "customer_name": "Jean Dupont",
  "balance":       100.00,
  "pending_holds": 0.00,
  "available":     100.00,
  "currency":      "USD",
  "can_pay":       true
}

Respuesta 403
{
  "success": false,
  "error": {
    "code":    "FORBIDDEN",
    "message": "Vous ne pouvez consulter que le solde de votre propre compte."
  }
}

Códigos de error

Todos los errores devuelven este formato JSON con el código HTTP apropiado.

Formato error JSON
{
  "success": false,
  "error": {
    "code":    "INVALID_AMOUNT",
    "message": "Montant doit être > 0"
  }
}

Webhook

PSLWallet envía un POST JSON a su webhook_url (configurado en su cuenta asociada) tras cada evento de pago. Su endpoint debe responder HTTP 200.

Payload — payment.completed

JSON recibido en su servidor
{
  "event":         "payment.completed",
  "order_id":      "CMD-1042",
  "reference":     "PSL-71F9B1C08DA0EA84",
  "amount":        25.00,
  "currency":      "USD",
  "customer":      "client@email.com",
  "customer_name": "Jean Dupont",
  "description":   "Commande #1042",
  "partner":       "Solisyon",
  "tx_id":         471,
  "metadata": { "product_id": "42", "user_id": "789" },
  "mode":    "live",
  "paid_at": "2026-03-16T21:00:00+00:00"
}

Recibir el webhook — PHP

PHP — webhook/pslwallet.phpcopiar
$payload = json_decode(file_get_contents('php://input'), true);
if (!$payload) { http_response_code(400); exit; }

if ($payload['event'] === 'payment.completed'
    && $payload['mode'] === 'live') {

    $orderId = $payload['order_id'];
    $txId    = $payload['tx_id'];
    $order   = get_order($orderId);
    if ($order && $order['status'] === 'pending') {
        mark_order_paid($orderId, $txId);
        send_confirmation_email($payload['customer'], $orderId);
        unlock_product_access($orderId);
    }
}

http_response_code(200);
echo 'OK';

Integración PHP completa

Archivo helper pslgateway.php

PHP — pslgateway.phpcopiar
define('PSL_KEY', getenv('PSL_API_KEY'));
define('PSL_URL', 'https://pslwallet.com/pslwallet/api/v1');

function psl($method, $path, $body = []) {
    $ch = curl_init(PSL_URL . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_HTTPHEADER     => ['X-API-Key: '.PSL_KEY, 'Content-Type: application/json'],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 15,
        ...($body ? [CURLOPT_POSTFIELDS => json_encode($body)] : []),
    ]);
    $r = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $r;
}

Página checkout — iniciar pago

PHP — checkout.phpcopiar
require_once 'pslgateway.php';

$r = psl('POST', '/payment/initiate', [
    'amount'         => 25.00,
    'description'    => 'Commande #1042',
    'customer_email' => 'client@email.com',
    'order_id'       => 'CMD-1042',
    'redirect_url'   => 'https://monsite.com/confirm',
    'metadata'       => ['product_id' => '42'],
]);

if ($r['success']) {
    db_query("UPDATE orders SET psl_order_id=?, psl_ref=? WHERE id=?",
        [$r['order_id'], $r['reference'], '1042']);
    header('Location: ' . $r['payment_url']);
    exit;
} else {
    $error = $r['error']['message'];
}

Integración Node.js

JavaScript — pslgateway.js + Expresscopiar
const PSL = {
  key: process.env.PSL_API_KEY,
  url: 'https://pslwallet.com/pslwallet/api/v1',

  async req(method, path, body) {
    const r = await fetch(this.url + path, {
      method,
      headers: { 'X-API-Key': this.key, 'Content-Type': 'application/json' },
      ...(body ? { body: JSON.stringify(body) } : {}),
    });
    const data = await r.json();
    if (!data.success) throw new Error(data.error?.message);
    return data;
  },

  initiate(amount, desc, email, orderId, meta = {}) {
    return this.req('POST', '/payment/initiate', {
      amount, description: desc, customer_email: email,
      order_id: orderId, redirect_url: `${process.env.APP_URL}/confirm`, metadata: meta,
    });
  },

  status(orderId)         { return this.req('GET', `/payment/status?order_id=${orderId}`); },
  refund(orderId, reason) { return this.req('POST', '/payment/refund', { order_id: orderId, reason }); },
};

// Checkout
app.post('/checkout/pslwallet', async (req, res) => {
  const { orderId, amount, email } = req.body;
  const payment = await PSL.initiate(amount, `Commande #${orderId}`, email, `CMD-${orderId}`);
  await Order.update(orderId, { pslOrderId: payment.order_id, pslRef: payment.reference });
  res.json({ payment_url: payment.payment_url });
});

// Webhook
app.post('/webhook/pslwallet', (req, res) => {
  const { event, order_id, tx_id, mode } = req.body;
  if (event === 'payment.completed' && mode === 'live')
    Order.markPaid(order_id, tx_id);
  res.json({ ok: true });
});

WooCommerce

PHP — psl-gateway.phpcopiar
/*
 * Plugin Name: PSL Gateway
 * Description: Paiements USD via PSL Wallet
 * Version: 1.0
 */

add_filter('woocommerce_payment_gateways', fn($g) => [...$g, 'WC_PSL_Gateway']);

add_action('plugins_loaded', function() {
  class WC_PSL_Gateway extends WC_Payment_Gateway {

    public function __construct() {
      $this->id                 = 'psl_gateway';
      $this->method_title       = 'PSL Wallet';
      $this->method_description = 'Paiement USD sécurisé via PSL Wallet';
      $this->has_fields         = false;
      $this->init_form_fields();
      $this->init_settings();
      $this->title   = $this->get_option('title');
      $this->api_key = $this->get_option('api_key');
      add_action('woocommerce_update_options_payment_gateways_psl_gateway',
        [$this, 'process_admin_options']);
    }

    public function init_form_fields() {
      $this->form_fields = [
        'title'   => ['title'=>'Titre affiché',    'type'=>'text',     'default'=>'PSL Wallet (USD)'],
        'api_key' => ['title'=>'Clé API PSLWallet', 'type'=>'password'],
      ];
    }

    public function process_payment($wc_order_id) {
      $order    = wc_get_order($wc_order_id);
      $order_id = 'WC-' . $wc_order_id;

      $ch = curl_init('https://pslwallet.com/pslwallet/api/v1/payment/initiate');
      curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => ['X-API-Key: '.$this->api_key, 'Content-Type: application/json'],
        CURLOPT_POSTFIELDS     => json_encode([
          'amount'         => (float)$order->get_total(),
          'description'    => 'Commande #'.$wc_order_id.' — '.get_bloginfo('name'),
          'customer_email' => $order->get_billing_email(),
          'order_id'       => $order_id,
          'redirect_url'   => $this->get_return_url($order),
          'webhook_url'    => home_url('/wp-json/psl/webhook'),
          'metadata'       => ['wc_order_id' => $wc_order_id],
        ]),
      ]);
      $r = json_decode(curl_exec($ch), true);
      curl_close($ch);

      if ($r['success']) {
        $order->update_meta_data('_psl_order_id', $r['order_id']);
        $order->update_meta_data('_psl_reference', $r['reference']);
        $order->save();
        return ['result'=>'success', 'redirect'=>$r['payment_url']];
      }

      wc_add_notice($r['error']['message'] ?? 'Erreur PSL Wallet', 'error');
      return ['result'=>'failure'];
    }
  }
});

// Webhook REST WooCommerce
add_action('rest_api_init', function() {
  register_rest_route('psl', '/webhook', [
    'methods'             => 'POST',
    'permission_callback' => '__return_true',
    'callback'            => function($req) {
      $p = $req->get_json_params();
      if (($p['mode'] ?? '') !== 'live')
        return new WP_REST_Response(['ok'=>true]);
      if ($p['event'] === 'payment.completed') {
        $wc_id = $p['metadata']['wc_order_id'];
        $order = wc_get_order($wc_id);
        if ($order && $order->get_status() === 'pending') {
          $order->payment_complete($p['tx_id']);
          $order->add_order_note('Payé via PSL Wallet · order: '.$p['order_id']);
        }
      }
      return new WP_REST_Response(['ok'=>true], 200);
    },
  ]);
});