API Shinpay

Démarrer

1. Le marchand crée une clé dans son tableau de bord Shinpay : Paramètres → API tokens, en choisissant l'accès adapté (voir ci-dessous). La clé n'est affichée qu'une fois.
2. Il vous la transmet par un canal sûr.
3. Vous l'envoyez dans l'en-tête Authorization de chaque appel, en HTTPS, vers https://shinpay.app.

curl https://shinpay.app/api/external/me \
  -H "Authorization: Bearer gpa_live_..."

Toutes les réponses sont en JSON. Les montants sont en centimes (8999= 89,99 €), les dates en ISO 8601 (UTC). Une clé donne accès à toutes les boutiques du marchand qui l'a créée, et à elles seules.

Accès

Une route appelée sans le droit nécessaire répond 403.

Tester la clé

GET/api/external/me

Renvoie le compte marchand lié à la clé et ses droits.

{
  "leadId": "cmf0a1b2c3d4e5f6g7h8",
  "email": "marchand@exemple.fr",
  "company": "Ma Société",
  "name": "Prénom Nom",
  "storeCount": 2,
  "scopes": ["orders:read", "orders:write"],
  "tokenId": "cmg9z8y7x6w5v4u3t2s1"
}

Lister les commandes

GET/api/external/orders

Droit requis : orders:read. Commandes triées de la plus anciennement modifiée à la plus récente.

{
  "orders": [
    {
      "id": "cmg1x2y3z4a5b6c7d8e9",
      "storeId": "cmf0a1b2c3d4e5f6g7h8",
      "orderRef": "MRX-EXT-3F9A1C07",
      "status": "SUCCEEDED",
      "paid": true,
      "currency": "eur",
      "totalAmountCents": 8999,
      "customerEmail": "client@exemple.fr",
      "customerName": "Julie Martin",
      "items": [
        { "name": "Nom du produit", "quantity": 1, "unitAmountCents": 8999,
          "totalCents": 8999, "externalVariantId": "60059323269454" }
      ],
      "createdAt": "2026-10-03T12:05:00.000Z",
      "paidAt": "2026-10-03T12:05:00.000Z",
      "updatedAt": "2026-10-03T12:05:02.000Z"
    }
  ],
  "nextCursor": null
}

Synchroniser

1. Interrogez la route toutes les quelques minutes avec since = le dernier updatedAt reçu.
2. Suivez nextCursor tant qu'il n'est pas null.
3. Enregistrez chaque commande selon son id : une même commande revient quand son statut change (remboursement, échec).

id est l'identifiant stable à conserver de votre côté ; orderRef est la référence lisible.

Déclarer une vente payée

POST/api/external/orders/paid

Droit requis : orders:write. Appelez-la dès qu'un paiement est confirmé, uniquement pour les paiements réussis. Shinpay enregistre la commande, notifie le marchand et envoie au client son récapitulatif, sa facture et son e-ticket. Pour une billetterie, les places transmises sont marquées vendues.

Le corps reprend le format d'une commande Shopify : si vous avez déjà la commande Shopify, vous pouvez la transmettre telle quelle dans order.

POST https://shinpay.app/api/external/orders/paid
Authorization: Bearer gpa_live_...
Content-Type: application/json

{
  "shop": "ma-boutique.myshopify.com",
  "order": {
    "id": "TX-123456",
    "name": "#1042",
    "created_at": "2026-10-03T14:05:00+02:00",
    "email": "client@exemple.fr",
    "phone": "+33600000000",
    "currency": "EUR",
    "total_price": "89.99",
    "customer": { "first_name": "Julie", "last_name": "Martin" },
    "billing_address": {
      "name": "Julie Martin", "address1": "1 rue de la Paix",
      "city": "Paris", "zip": "75002", "country_code": "FR"
    },
    "payment_gateway_names": ["VotreSolution"],
    "line_items": [
      {
        "product_id": 15915135107406,
        "variant_id": 60059323269454,
        "title": "Nom du produit",
        "quantity": 1,
        "price": "89.99",
        "properties": [{ "name": "Siège", "value": "A12" }]
      }
    ]
  }
}

Réponse

{
  "ok": true,
  "created": true,
  "id": "cmg1x2y3z4a5b6c7d8e9",
  "reference": "EXT-3f9a1c07...",
  "eticketUrl": "https://shinpay.app/api/eticket/EXT-3f9a1c07.../download"
}

created: falsesignifie que la vente était déjà reçue : rien n'est renvoyé au client. Vous pouvez donc réessayer sans risque après une erreur réseau ou une réponse 5xx. Si vous créez aussi la commande dans Shopify, utilisez son identifiant Shopify comme order.id pour éviter un double envoi.

Erreurs

Les erreurs répondent { "error": "message" } avec un code HTTP explicite.

Sécurité

• Gardez la clé côté serveur : jamais dans une page web, une application mobile ou un dépôt de code.
• Le marchand peut révoquer une clé à tout moment ; elle répond alors 401.
• Une clé ne voit que les boutiques du marchand qui l'a créée.

Une question ? Contactez-nous.