Pledg API Reference

Welcome on Pledg payment API.

What is Pledg ?

Pledg is a shared payment solution for groups. A buyer, the leader, books for the whole group, the pledgers, without having to advance any cash !

Pledg takes care of the advance backed by a preauthorization on the leader's credit card for the full amount of the purchase.

When the leader clicks on the "Pay with Pledg" button, the purchase data and the leader's information are sent to Pledg REST API. The API returns an url pointing to a page, hosted by Pledg, that allows the leader to pay.

On this page, the leader :

  • Keys in his card details to setup the preauthorization
  • Split the amount of the purchase between the members of the group. He inputs the email of the pledgers and optionally the amounts due by each pledger

The API allows to :

  • Split the amount of a purchase between friends
  • Make group buying and paying back easier

Each merchant has a back-office allowing to setup the API and to report on the purchases.

Glossary

Object Description
Merchant Pledg's partner. You
Client The Merchant's customer
Purchase Content of the cart on the Merchant site

Webhooks

At each event on Pledg's back-end, the Merchant receives a notification. The notification is a POST request on a URL configured on the merchant's back-office. The webhook's payload contains a token that authenticates the request was done by Pledg.

The webhook's payload contains :

  • The identifier of the event (uuid)
  • The name of the event
  • The date of the purchase
  • The token
  • Data related to the event. Cf. table below.

Exemple :

          {
            "triggerID": 123,
            "triggerName": "paymentProcessed",
            "triggerDate": "2016-11-11T08:00:00.000Z",
            "token": "6153A6FA0E4880D9B8D0BE4720F78E895265D0A9",
            "objects": {
                "purchaseId": "110e8400-e29b-11d4-a716-446655440000"
            }
          }
          
Name of the trigger Data related to the event Description
paymentProcessed Purchase The preauthorization of the leader is validated (meaning 3D-Secure was successfull)
paymentFailed Purchase The card details of the leader are not valid or there was a problem with the preauthorization
pledgerContributes Client & Purchase A pledger paid his share

Each webhook only contains the id of the objects related to the event, this is the reason why we strongly encourage you to make an additionnal request after you receive the webhook to check the current status of these objects.

Explanatory picture

API Authentication

We use the JWT authentication method.

You have to add the API token to the Authorization header, for each request.

API Endpoint
https://app.pledg.co/api/merchants/v1/
Contact: hi@pledg.co
Request Content-Types: application/json
Response Content-Types: application/json
Schemes: https
Version: 1.0.0

Authentication

Authorization

name
Authorization
in
header

Paths

Get details of a Purchase

GET /purchases/{id}
id

Pledg identifier for the Purchase

type
string (uuid)
in
path
200 OK

Valid Purchase object

404 Not Found

Unknown Purchase object

Response Example (200 OK)
{
  "id": "string (uuid)",
  "payment_url": "string (url)",
  "state": "string",
  "ref": "string",
  "title": "string",
  "subtitle": "string",
  "description": "string",
  "client": {
    "id": "string (UUID)",
    "ref": "string",
    "last_name": "string",
    "first_name": "string",
    "email": "string (email)",
    "operation": {
      "id": "integer",
      "failed_at": "datetime",
      "failed_reason": "string",
      "created_at": "datetime",
      "updated_at": "datetime",
      "mango_id": "string",
      "mango_author_id": "string",
      "mango_status": "string",
      "mango_card_id": "string",
      "mango_redirect_url": "string",
      "pay_in_executed_at": "datetime",
      "pay_in_mango_id": "string",
      "amount_cents": "integer",
      "amount_currency": "string",
      "initial_transaction_mango_id": "string",
      "initial_transaction_type": "string",
      "traceable_type": "string",
      "traceable_id": "integer",
      "mango_result_code": "string",
      "merchant_id": "integer"
    }
  },
  "picture_url": "string (url)",
  "amount": "integer",
  "currency": "string",
  "callback_url": "string (url)",
  "products": [
    {
      "ref": "string",
      "label": "string",
      "amount": "integer",
      "currency": "string",
      "pledger_email": "string"
    }
  ],
  "pledgers_emails": "array"
}
Response Example (404 Not Found)
{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Create a new Purchase object

POST /purchases

The Purchase object is the payment being made. POSTed in JSON in the request's body

Request Example
{
  "ref": "string",
  "title": "string",
  "subtitle": "string",
  "description": "string",
  "picture_url": "string (url)",
  "state": "string",
  "amount": "integer",
  "currency": "string",
  "callback_url": "string (url)",
  "products": [
    {
      "ref": "string",
      "label": "string",
      "amount": "integer",
      "currency": "string"
    }
  ]
}
201 Created

Created successfully

406 Not Acceptable

Incorrect input

default

Unknown error

Response Example (201 Created)
{
  "id": "string (uuid)",
  "payment_url": "string (url)",
  "state": "string",
  "ref": "string",
  "title": "string",
  "subtitle": "string",
  "description": "string",
  "client": {
    "id": "string (UUID)",
    "ref": "string",
    "last_name": "string",
    "first_name": "string",
    "email": "string (email)",
    "operation": {
      "id": "integer",
      "failed_at": "datetime",
      "failed_reason": "string",
      "created_at": "datetime",
      "updated_at": "datetime",
      "mango_id": "string",
      "mango_author_id": "string",
      "mango_status": "string",
      "mango_card_id": "string",
      "mango_redirect_url": "string",
      "pay_in_executed_at": "datetime",
      "pay_in_mango_id": "string",
      "amount_cents": "integer",
      "amount_currency": "string",
      "initial_transaction_mango_id": "string",
      "initial_transaction_type": "string",
      "traceable_type": "string",
      "traceable_id": "integer",
      "mango_result_code": "string",
      "merchant_id": "integer"
    }
  },
  "picture_url": "string (url)",
  "amount": "integer",
  "currency": "string",
  "callback_url": "string (url)",
  "products": [
    {
      "ref": "string",
      "label": "string",
      "amount": "integer",
      "currency": "string",
      "pledger_email": "string"
    }
  ],
  "pledgers_emails": "array"
}
Response Example (406 Not Acceptable)
{
  "error": {
    "code": "string",
    "message": "string"
  }
}
Response Example (default )
{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema Definitions

NewPurchasePayload: object

Description of the payment being made

ref: string

Merchant's reference for the product"

title: string

Description of the product (e.g. name of the product)

subtitle: string

Additional description of the product (e.g. date of the venue or rental dates)

description: string

Complete description of the product

picture_url: string (url)

URL of the product's picture

state: string

Etat ("INITIALIZED")

amount: integer x ≥ 0

Cart amount in cents

currency: string EUR

Currency (ISO 4217 format)

callback_url: string (url)

Redirection URL (the customer will be redirected to this url when the payment is completed)

products: NewProduct
Example
{
  "ref": "string",
  "title": "string",
  "subtitle": "string",
  "description": "string",
  "picture_url": "string (url)",
  "state": "string",
  "amount": "integer",
  "currency": "string",
  "callback_url": "string (url)",
  "products": [
    {
      "ref": "string",
      "label": "string",
      "amount": "integer",
      "currency": "string"
    }
  ]
}

Client: object

id: string (UUID)

Pledg reference for the client

ref: string

Merchant's reference for the client

last_name: string

Client's family name

first_name: string

Client's first name

email: string (email)

Client's email

operation: Operation

Last payment operation on the purchase

Example
{
  "id": "string (UUID)",
  "ref": "string",
  "last_name": "string",
  "first_name": "string",
  "email": "string (email)",
  "operation": {
    "id": "integer",
    "failed_at": "datetime",
    "failed_reason": "string",
    "created_at": "datetime",
    "updated_at": "datetime",
    "mango_id": "string",
    "mango_author_id": "string",
    "mango_status": "string",
    "mango_card_id": "string",
    "mango_redirect_url": "string",
    "pay_in_executed_at": "datetime",
    "pay_in_mango_id": "string",
    "amount_cents": "integer",
    "amount_currency": "string",
    "initial_transaction_mango_id": "string",
    "initial_transaction_type": "string",
    "traceable_type": "string",
    "traceable_id": "integer",
    "mango_result_code": "string",
    "merchant_id": "integer"
  }
}

NewProduct: object

ref: string

Merchant's reference for the product

label: string
amount: integer x ≥ 0

Product price in cents

currency: string EUR

Currency (ISO 4217 format)

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

Product: object

ref: string

Merchant's reference for the product

label: string
amount: integer x ≥ 0

Product price in cents

currency: string EUR

Currency (ISO 4217 format)

pledger_email: string

Pledger email if products can be dispatched

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

Purchase: object

id: string (uuid)

Pledg identifier

payment_url: string (url)

URL of payment page. The client must be redirected to this URL to pay with Pledg.

state: string INITIALIZED, CANCELLED, FAILED, REFUNDED, LEADER_PROCESSED, SUCCESSFUL

Payment status

ref: string

Merchant's reference for the product

title: string

Description of the product (e.g. name of the product)

subtitle: string

Additional description of the product (e.g. date of the venue or rental dates)

description: string

Complete description of the product

client: Client
picture_url: string (url)

URL of the product's picture

amount: integer x ≥ 0

Cart amount in cents

currency: string EUR

Currency (ISO 4217 format)

callback_url: string (url)

Redirection URL (the customer will be redirected to this url when the payment is completed)

products: Product
pledgers_emails: array

List of pledger emails

Example
{
  "id": "string (uuid)",
  "payment_url": "string (url)",
  "state": "string",
  "ref": "string",
  "title": "string",
  "subtitle": "string",
  "description": "string",
  "client": {
    "id": "string (UUID)",
    "ref": "string",
    "last_name": "string",
    "first_name": "string",
    "email": "string (email)",
    "operation": {
      "id": "integer",
      "failed_at": "datetime",
      "failed_reason": "string",
      "created_at": "datetime",
      "updated_at": "datetime",
      "mango_id": "string",
      "mango_author_id": "string",
      "mango_status": "string",
      "mango_card_id": "string",
      "mango_redirect_url": "string",
      "pay_in_executed_at": "datetime",
      "pay_in_mango_id": "string",
      "amount_cents": "integer",
      "amount_currency": "string",
      "initial_transaction_mango_id": "string",
      "initial_transaction_type": "string",
      "traceable_type": "string",
      "traceable_id": "integer",
      "mango_result_code": "string",
      "merchant_id": "integer"
    }
  },
  "picture_url": "string (url)",
  "amount": "integer",
  "currency": "string",
  "callback_url": "string (url)",
  "products": [
    {
      "ref": "string",
      "label": "string",
      "amount": "integer",
      "currency": "string",
      "pledger_email": "string"
    }
  ],
  "pledgers_emails": "array"
}

Operation: object

id: integer

Operation id

failed_at: datetime

Date of failure if failed payment

failed_reason: string

Type of failure if failed payment

created_at: datetime

Creation date

updated_at: datetime

Last update date

mango_id: string

MangoPay id for operation

mango_author_id: string

MangoPay id for author of operation

mango_status: string

MangoPay status for operation

mango_card_id: string

MangoPay id of card used for operation

mango_redirect_url: string

MangoPay redirection url

pay_in_executed_at: datetime

Date for payin execution

pay_in_mango_id: string

MangoPay id for payin

amount_cents: integer

Transaction amount in cents

amount_currency: string

Transaction currency

initial_transaction_mango_id: string

Transaction id

initial_transaction_type: string

Type of transaction

traceable_type: string

Type of dependency for operation (Purchase, Share)

traceable_id: integer

Id of dependency for operation (Purchase, Share)

mango_result_code: string

MangoPay result code

merchant_id: integer

Merchant id

Example
{
  "id": "integer",
  "failed_at": "datetime",
  "failed_reason": "string",
  "created_at": "datetime",
  "updated_at": "datetime",
  "mango_id": "string",
  "mango_author_id": "string",
  "mango_status": "string",
  "mango_card_id": "string",
  "mango_redirect_url": "string",
  "pay_in_executed_at": "datetime",
  "pay_in_mango_id": "string",
  "amount_cents": "integer",
  "amount_currency": "string",
  "initial_transaction_mango_id": "string",
  "initial_transaction_type": "string",
  "traceable_type": "string",
  "traceable_id": "integer",
  "mango_result_code": "string",
  "merchant_id": "integer"
}

Error: object

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