Pledg API Reference

Bienvenue sur la documentation de l'API Merchant de Pledg.

Pledg est une solution de paiement partagé, permettant aux clients d'acheter des biens et des services sur des sites Web de fournisseurs, puis de demander à leurs amis de participer.

Nomenclature

Object Description
Merchant Partenaire de Pledg. Vous.
Client Client du Merchant
Purchase Contenu du panier acheté sur le site du Merchant

Webhooks

Après chaque action réalisée sur le site de Pledg, le Merchant reçoit une alerte sous forme de requête HTTP POST sur l'URL configurée.

Vous pouvez renseigner une URL de webhook dans votre backoffice. Un token sera alors généré, qui sera intégré dans le payload à chaque appel, vous permettant ainsi de vérifier que Pledg en est bien la source.

Le payload d'un webhook est composé de :

  • L'identifiant du l'événement
  • Le nom de l'événement
  • La date d'execution de la commande
  • Un token
  • Des données contextuelles. Cf tableau ci-dessous.

Exemple :

          {
            "triggerID": 123,
            "triggerName": "paymentProcessed",
            "triggerDate": "2016-11-11T08:00:00.000Z",
            "token": "6153A6FA0E4880D9B8D0BE4720F78E895265D0A9",
            "objects": {
                "purchaseId": "110e8400-e29b-11d4-a716-446655440000"
            }
          }
          
Nom du trigger Données contextuelles Description
paymentProcessed Purchase Lorsque l'autorisation de prélèvement du leader est validé. (Et validé 3DSecure)
paymentFailed Purchase Si une erreur se produit lors de la saisie de la carte ou si la banque renvoie une erreur
pledgerContributes Client & Purchase Lorsqu'un pledger (ex. un ami du Client) participe à la cagnotte

Lorsque nous déclenchons un webhook vers l'URL configurée, nous vous transmettons uniquement l'identifiant des objets concernés, c'est pourquoi nous vous encourageons fortement à effectuer une requête supplémentaire vers nos serveurs afin de vous assurer de leur état actuel.

Graphique explicatif

Authentification

L'authentification à l'API s'effectue en ajoutant votre token dans le header Authorization de chaque requête.

API Endpoint
https://staging.pledg.co/api/merchants/v1/
Contact: contact@pledg.co
Schemes: https
Version: 1.0.0

Authentication

Authorization

name
Authorization
in
header

Purchase

Objet principal, le contenu du panier client.

Obtenir le détail d'un Purchase

GET /purchases/{id}
id

Identifiant Pledg du Purchase

type
string (uuid)
in
path
200 OK

Objet Purchase valide

404 Not Found

Objet Purchase inconnu

Response Example (200 OK)
{
  "id": "string (uuid)",
  "payment_url": "string (url)",
  "state": "string",
  "comment": "string",
  "ref": "string",
  "title": "string",
  "subtitle": "string",
  "description": "string",
  "client": {
    "id": "string (UUID)",
    "ref": "string",
    "last_name": "string",
    "first_name": "string",
    "email": "string (email)",
    "purchases": "array"
  },
  "picture_url": "string (url)",
  "amount": "integer",
  "currency": "string",
  "callback_url": "string (url)",
  "products": [
    {
      "ref": "string",
      "label": "string",
      "amount": "integer",
      "currency": "string"
    }
  ]
}
Response Example (404 Not Found)
{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Création d'un nouvel objet Purchase

POST /purchases

L'objet Purchase correspondant au paiement initié. Transmis en JSON dans le body de la requête

Request Example
{
  "ref": "string",
  "title": "string",
  "subtitle": "string",
  "description": "string",
  "client": {
    "id": "string (UUID)",
    "ref": "string",
    "last_name": "string",
    "first_name": "string",
    "email": "string (email)",
    "purchases": "array"
  },
  "picture_url": "string (url)",
  "amount": "integer",
  "currency": "string",
  "callback_url": "string (url)",
  "products": [
    {
      "ref": "string",
      "label": "string",
      "amount": "integer",
      "currency": "string"
    }
  ]
}
201 Created

Création réussie

406 Not Acceptable

Données d'entrée incorrectes'

default

Erreur non anticipée

Response Example (201 Created)
{
  "id": "string (uuid)",
  "payment_url": "string (url)",
  "state": "string",
  "comment": "string",
  "ref": "string",
  "title": "string",
  "subtitle": "string",
  "description": "string",
  "client": {
    "id": "string (UUID)",
    "ref": "string",
    "last_name": "string",
    "first_name": "string",
    "email": "string (email)",
    "purchases": "array"
  },
  "picture_url": "string (url)",
  "amount": "integer",
  "currency": "string",
  "callback_url": "string (url)",
  "products": [
    {
      "ref": "string",
      "label": "string",
      "amount": "integer",
      "currency": "string"
    }
  ]
}
Response Example (406 Not Acceptable)
{
  "error": {
    "code": "string",
    "message": "string"
  }
}
Response Example (default )
{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Client

Obtenir le détail d'un Client

GET /clients/{id}
id

Identifiant Pledg du Client

type
string (uuid)
in
path
200 OK

Objet Client valide

Response Example (200 OK)
{
  "id": "string (UUID)",
  "ref": "string",
  "last_name": "string",
  "first_name": "string",
  "email": "string (email)",
  "purchases": "array"
}

Schema Definitions

NewPurchasePayload: object

L'objet du paiement demandé

ref: string

Référence de l'achat interne au Vendor

title: string

Quelques mots définissant l'achat (Par exemple le nom de l'objet de l'achat)

subtitle: string

Informations supplémentaires concernant l'achat (Par exemple la date d'un spectacle ou la durée d'une location)

description: string

Description complète de l'achat

client: Client
picture_url: string (url)

Une URL pointant vers une image représentant l'achat

amount: integer , { x ∈ ℤ | x ≥ 0 }

Le montant de l'achat, en cents de la monnaie sélectionnée

currency: string EUR

Monnaie dans laquelle l'achat est effectué, au format ISO 4217

callback_url: string (url)

L'URL vers laquelle sera redirigé le client après finalisation du paiement

products: object[]
Example
{
  "ref": "string",
  "title": "string",
  "subtitle": "string",
  "description": "string",
  "client": {
    "id": "string (UUID)",
    "ref": "string",
    "last_name": "string",
    "first_name": "string",
    "email": "string (email)",
    "purchases": "array"
  },
  "picture_url": "string (url)",
  "amount": "integer",
  "currency": "string",
  "callback_url": "string (url)",
  "products": [
    {
      "ref": "string",
      "label": "string",
      "amount": "integer",
      "currency": "string"
    }
  ]
}

Client: object

id: string (UUID)

Référence client Pledg

ref: string

Référence client interne au Vendor

last_name: string

Nom de famille du client

first_name: string

Prénom du client

email: string (email)

E-mail du client

purchases: array

Liste des achats réalisés

Example
{
  "id": "string (UUID)",
  "ref": "string",
  "last_name": "string",
  "first_name": "string",
  "email": "string (email)",
  "purchases": "array"
}

Product: object

ref: string

Référence du produit interne au Vendor

label: string
amount: integer , { x ∈ ℤ | x ≥ 0 }

Le prix du produit, en cents de la monnaie sélectionné

currency: string EUR

Monnaie dans laquelle l'achat est effectué, au format ISO 4217

Example
{
  "ref": "string",
  "label": "string",
  "amount": "integer",
  "currency": "string"
}

Purchase: object

id: string (uuid)

Identifiant interne Pledg

payment_url: string (url)

L'URL de la page de paiement. Il s'agit de la page vers laquelle vous devrez rediriger votre client.

state: string , x ∈ { INITIALIZED , CANCELLED , FAILED , REFUNDED , LEADER_PROCESSED , SUCCESSFUL }

État du paiement

comment: string

Détails supplémentaires sur l'état du paiement

ref: string

Référence de l'achat interne au Vendor

title: string

Quelques mots définissant l'achat (Par exemple le nom de l'objet de l'achat)

subtitle: string

Informations supplémentaires concernant l'achat (Par exemple la date d'un spectacle ou la durée d'une location)

description: string

Description complète de l'achat

client: Client
picture_url: string (url)

Une URL pointant vers une image représentant l'achat

amount: integer , { x ∈ ℤ | x ≥ 0 }

Le montant de l'achat, en cents de la monnaie sélectionnée

currency: string EUR

Monnaie dans laquelle l'achat est effectué, au format ISO 4217

callback_url: string (url)

L'URL vers laquelle sera redirigé le client après finalisation du paiement

products: object[]
Example
{
  "id": "string (uuid)",
  "payment_url": "string (url)",
  "state": "string",
  "comment": "string",
  "ref": "string",
  "title": "string",
  "subtitle": "string",
  "description": "string",
  "client": {
    "id": "string (UUID)",
    "ref": "string",
    "last_name": "string",
    "first_name": "string",
    "email": "string (email)",
    "purchases": "array"
  },
  "picture_url": "string (url)",
  "amount": "integer",
  "currency": "string",
  "callback_url": "string (url)",
  "products": [
    {
      "ref": "string",
      "label": "string",
      "amount": "integer",
      "currency": "string"
    }
  ]
}

Error: object

error: object
Example
{
  "error": {
    "code": "string",
    "message": "string"
  }
}