Overview

Installing the Library

1- Download the library on GitHub:

2- Add to all your pages that use the API:

<?php
require_once('PATH_TO_PAYPLUG/payplug_php/lib/init.php');

import payplug

Authentication

Verify your identity when communicating with the API by providing a secret key in all your requests.

To submit your credentials, include your key in all pages that use the API:

<?php
\Payplug\Payplug::init(array(
  'secretKey' => 'sk_live_YOUR_PRIVATE_KEY',
  'apiVersion' => 'THE_API_VERSION',
));

payplug.set_secret_key('sk_live_YOUR_PRIVATE_KEY')

API keys start with “sk_”.
They are available in My account, then API Credentials in the PayPlug portal.

Access LIVE and TEST modes using the same endpoint. To switch between modes, simply provide the related secret key to the mode you wish to access.

Take a look at the changelog to know which api version you should use.

Create a payment

The payment creation process

create a payment

Create the payment; a link to a payment page will be generated.
Redirect the customer to the payment page.
After entering card details, your customer is automatically redirected to the return page on your site.
PayPlug sends you a confirmation via IPN (Instant Payment Notification).

Creating a payment

The following code shows an example of a payment request that automatically redirects your client to the payment page:

<?php
$email = 'john.watson@example.net';
$amount = 33;
$customer_id = '42710';

$payment = \Payplug\Payment::create(array(
  'amount'           => $amount * 100,
  'currency'         => 'EUR',
  'billing'  => array(
    'title'        => 'mr',
    'first_name'   => 'John',
    'last_name'    => 'Watson',
    'email'        => 'john.watson@example.net',
    'address1'     => '221B Baker Street',
    'postcode'     => 'NW16XE',
    'city'         => 'London',
    'country'      => 'GB',
    'language'     => 'en'
  ),
  'shipping'  => array(
    'title'         => 'mr',
    'first_name'    => 'John',
    'last_name'     => 'Watson',
    'email'         => 'john.watson@example.net',
    'address1'      => '221B Baker Street',
    'postcode'      => 'NW16XE',
    'city'          => 'London',
    'country'       => 'GB',
    'language'      => 'en',
    'delivery_type' => 'BILLING'
  ),
  'hosted_payment'   => array(
    'return_url'     => 'https://example.net/return?id='.$customer_id,
    'cancel_url'     => 'https://example.net/cancel?id='.$customer_id
  ),
  'notification_url' => 'https://example.net/notifications?id='.$customer_id,
  'metadata'         => array(
    'customer_id'    => $customer_id
    )
));

$payment_url = $payment->hosted_payment->payment_url;
$payment_id = $payment->id;
header('Location:' . $payment_url);

payment_data = {
  'amount': 3300,
  'currency': 'EUR',
  'customer': {
    'email': 'john.watson@example.net'
  },
  'hosted_payment': {
    'return_url': 'https://example.net/return?id=42710',
    'cancel_url': 'https://example.net/cancel?id=42710',
  },
  'notification_url': 'https://example.net/notifications?id=42710',
  'metadata': {
    'customer_id': 42710,
  },
}
payment = payplug.Payment.create(**payment_data)
payment_id = str(payment.id)

IMPORTANT: Please note that all amounts must be expressed in centimes as positive whole numbers (1€ = 100 centimes).

Confirmation

Option 1: Instant Payment Notification (IPN)

When creating a payment, you can specify a notification URL for use with IPN: notification_url. Whether the payment is successful or is fails, a POST query containing an object corresponding to the payment will be sent to your server.

<?php
$input = file_get_contents('php://input');
try {
  $resource = \Payplug\Notification::treat($input);
  if ($resource instanceof \Payplug\Resource\Payment
    && $resource->is_paid) {
    $payment_id = $resource->id;
    $payment_state = $resource->is_paid;
    $payment_date = $resource->hosted_payment->paid_at;
    $payment_amount = $resource->amount;
    $payment_data = $resource->metadata[customer_id];
  }
}
catch (\Payplug\Exception\PayplugException $exception) {
    echo htmlentities($exception);
}

request_body = request.body
try:
  resource = payplug.notifications.treat(request_body)
except payplug.exceptions.PayplugError:
  pass
else:
  if resource.object == 'payment' and resource.is_paid:
    payment_id = str(resource.id)
    payment_state = str(resource.is_paid)
    payment_date = datetime.datetime.fromtimestamp(resource.hosted_payment.paid_at).strftime('%d/%m/%Y %H:%M:%S')
    payment_amount = str(resource.amount)
    payment_data = resource.metadata['customer_id']
    pass

The notification URL must be publicly accessible via the internet. It will not work if you are operating offline or if the page is protected with a firewall or proxy.

Confirmation

Option 2: Extracting payment details

If you prefer not to use IPN, you may use the following method to extract payment details:

payment notifications

Steps one to three are the same as in the first diagram. In step four, make an API call using the payment ID that was generated when the payment was created:

<?php
$payment = \Payplug\Payment::retrieve($payment_id);

payment = payplug.Payment.retrieve(payment_id)

Managing metadata

Metadata allow you to include additional information when processing payments or refunds.

{
  "metadata": {
    "transaction_id": "tsct_201506023456",
    "customer_id": 58790,
    "product_id": "ts_blk_00234",
    "shipping": "The delivery was delayed"
  }
}

You can add up to ten keys. Names cannot exceed twenty (20) characters, and stored content cannot exceed five hundred (500) characters.

Refund a payment

The refund creation process

create a refund

Create a refund using the payment ID of the payment you wish to refund.
PayPlug sends you a confirmation via IPN (instant payment notification).

Processing a refund

Option 1: Full refunds

In order to process a refund, you will need the payment ID of the payment you wish to refund.

The following code shows an example of a full refund:

<?php
$payment_id = 'pay_5iHMDxy4ABR4YBVW4UscIn';
$refund = \Payplug\Refund::create($payment_id);

payment_id = 'pay_5iHMDxy4ABR4YBVW4UscIn'
refund = payplug.Refund.create(payment_id)

Processing a refund

Option 2: Partial refunds

If you only need to refund a portion of the payment, the following in an example of a partial refund:

<?php
$payment_id = 'pay_5iHMDxy4ABR4YBVW4UscIn';
$data = array(
  'amount' => 358,
  'metadata'          => array(
      'customer_id'       => 42710,
      'reason'            => 'The delivery was delayed'
    )
  );
$refund = \Payplug\Refund::create($payment_id, $data);

payment_id = 'pay_5iHMDxy4ABR4YBVW4UscIn'
refund_data = {
  'amount': 358,
  'metadata': {
    'customer_id': 42710,
    'reason': 'The delivery was delayed',
  },
}
refund = payplug.Refund.create(payment_id, **refund_data)

The example above includes metadata useful in tracking the refund.

Confirmation

Option 1: Instant Payment Notification (IPN)

If you specified a notification URL for use with IPN when the payment was created, after the refund is processed, a POST query containing an object corresponding to the refund will be sent to your server using the provided URL.

<?php
$input = file_get_contents('php://input');
try {
  $resource = \Payplug\Notification::treat($input);

  if ($resource->object == "refund")) {
    $refund_id = $resource->id;
    $payment_id = $resource->payment_id;
    $refund_date = $resource->created_at;
    $refund_amount = $resource->amount;
    $refund_data = $resource->metadata[reason];
  }
}
catch (\Payplug\Exception\PayplugException $exception) {
  echo htmlentities($exception);
}

request_body = request.body
try:
  resource = payplug.notifications.treat(request_body)
except payplug.exceptions.PayplugError:
  pass
else:
  if resource.object == 'refund':
    refund_id = str(resource.id)
    payment_id = str(resource.payment_id)
    refund_date = datetime.datetime.fromtimestamp(resource.created_at).strftime('%d/%m/%Y %H:%M:%S')
    refund_amount = str(resource.amount)
    refund_data = resource.metadata['reason']
    pass

The notification URL must be publicly accessible via the internet.
It will not work if you are operating offline or if the page is protected with a firewall or proxy.

Confirmation

Option 2: Extracting payment details

If you prefer not to use IPN, you may use the following method to extract payment details:

refund notifications

Step one is the same as in the first diagram.
In step two, make an API call using the payment ID and the refund ID:

<?php
$paymentId  = 'pay_5iHMDxy4ABR4YBVW4UscIn';
$refundId   = 're_3NxGqPfSGMHQgLSZH0Mv3B';
$refund = \Payplug\Refund::retrieve($paymentId, $refundId);

payment_id = 'pay_5iHMDxy4ABR4YBVW4UscIn'
refund_id = 're_3NxGqPfSGMHQgLSZH0Mv3B'
refund = payplug.Refund.retrieve(payment_id, refund_id)

Managing metadata

Metadata allow you to include additional information when processing payments or refunds.

{
  "metadata": {
    "transaction_id": "tsct_201506023456",
    "customer_id": 58790,
    "product_id": "ts_blk_00234",
    "shipping": "The delivery was delayed"
  }
}

You can add up to ten keys. Names cannot exceed twenty (20) characters,
and stored content cannot exceed five hundred (500) characters.

Create a payment request

The payment request creation process

create a payment

Create the payment request using sent_by for the delivery method; A link to a payment page will be generated.
Based on the delivery method a SMS or an e-mail will be sent to your customer.
Alternatively you can handle the redirection.
After entering his card details, your customer is automatically redirected to the return page on your site.
PayPlug sends you a confirmation via IPN (Instant Payment Notification).

Payment request delivery methods

With the payement request you can define the way you are delivering the URL to
the payment page to your customer :

Options	Expiration	Description
SMS		Send a SMS to your customer with the payment URL.
EMAIL		Send an e-mail to your customer with the payment URL.
OTHER		A payment URL with no expiration is generated. You are responsible for sharing the payment URL to your customer.
NULL		A payment URL is generated and will expire 15 minutes after the first access.

Creating a payment request by e-mail

The following code shows an example of a payment request that automatically sends an e-mail to your client with a link to the payment page:

<?php
$email = 'john.watson@example.net';
$amount = 33;
$customer_id = '42710';

$payment = \Payplug\Payment::create(array(
  'amount'           => $amount * 100,
  'currency'         => 'EUR',
  'billing'  => array(
    'title'        => 'mr',
    'first_name'   => 'John',
    'last_name'    => 'Watson',
    'email'        => 'john.watson@example.net',
    'address1'     => '221B Baker Street',
    'postcode'     => 'NW16XE',
    'city'         => 'London',
    'country'      => 'GB',
    'language'     => 'en'
  ),
  'shipping'  => array(
    'title'         => 'mr',
    'first_name'    => 'John',
    'last_name'     => 'Watson',
    'email'         => 'john.watson@example.net',
    'address1'      => '221B Baker Street',
    'postcode'      => 'NW16XE',
    'city'          => 'London',
    'country'       => 'GB',
    'language'      => 'en',
    'delivery_type' => 'BILLING'
  ),
  'hosted_payment'   => array(
    'return_url'     => 'https://example.net/return?id='.$customer_id,
    'cancel_url'     => 'https://example.net/cancel?id='.$customer_id,
    'sent_by'        => 'EMAIL'
  ),
  'notification_url' => 'https://example.net/notifications?id='.$customer_id,
  'metadata'         => array(
    'customer_id'    => $customer_id
    )
));

$payment_url = $payment->hosted_payment->payment_url;
$payment_id = $payment->id;

payment_data = {
  'amount': 3300,
  'currency': 'EUR',
  'customer': {
    'email': 'john.watson@example.net'
  },
  'hosted_payment': {
    'return_url': 'https://example.net/return?id=42710',
    'cancel_url': 'https://example.net/cancel?id=42710',
    'sent_by': 'EMAIL',
  },
  'notification_url': 'https://example.net/notifications?id=42710',
  'metadata': {
    'customer_id': 42710,
  },
}
payment = payplug.Payment.create(**payment_data)
payment_id = str(payment.id)

IMPORTANT: Please note that all amounts must be expressed in centimes as positive whole numbers
(1€ = 100 centimes).

Creating a payment request by SMS

The following code shows an example of a payment request that automatically sends an SMS to your client with a link to the payment page:

<?php
$email = 'john.watson@example.net';
$phone_number = '+33600000000';
$amount = 33;
$customer_id = '42710';

$payment = \Payplug\Payment::create(array(
  'amount'           => $amount * 100,
  'currency'         => 'EUR',
  'billing'  => array(
    'title'                => 'mr',
    'first_name'           => 'John',
    'last_name'            => 'Watson',
    'email'                => $email,
    'mobile_phone_number'  => $phone_number,
    'address1'             => '221B Baker Street',
    'postcode'             => 'NW16XE',
    'city'                 => 'London',
    'country'              => 'GB',
    'language'             => 'en'
  ),
  'shipping'  => array(
    'title'                => 'mr',
    'first_name'           => 'John',
    'last_name'            => 'Watson',
    'email'                => $email,
    'mobile_phone_number'  => $phone_number,
    'address1'             => '221B Baker Street',
    'postcode'             => 'NW16XE',
    'city'                 => 'London',
    'country'              => 'GB',
    'language'             => 'en'
    'delivery_type'        => 'BILLING'
  ),
  'hosted_payment'   => array(
    'return_url'     => 'https://example.net/return?id='.$customer_id,
    'cancel_url'     => 'https://example.net/cancel?id='.$customer_id,
    'sent_by'        => 'SMS'
  ),
  'notification_url' => 'https://example.net/notifications?id='.$customer_id,
  'metadata'         => array(
    'customer_id'    => $customer_id
    )
));

$payment_url = $payment->hosted_payment->payment_url;
$payment_id = $payment->id;

payment_data = {
  'amount': 3300,
  'currency': 'EUR',
  'customer': {
    'email': 'john.watson@example.net',
    'phone_number':'+33600000000',
  },
  'hosted_payment': {
    'return_url': 'https://example.net/return?id=42710',
    'cancel_url': 'https://example.net/cancel?id=42710',
    'sent_by': 'SMS',
  },
  'notification_url': 'https://example.net/notifications?id=42710',
  'metadata': {
    'customer_id': 42710,
  },
}
payment = payplug.Payment.create(**payment_data)
payment_id = str(payment.id)

IMPORTANT: Please note that for sending a SMS, the phone_number key has to be provided.

Payment requests compatibility

Payment requests are now compatible with most of the API features. It will allow to build powerfull integrations.

API feature	Compatibility
Refund a payment request
Retrieve a payment request
Update a payment request
Capture a payment request
Abort a payment request
Save a card
Notifications
Installment plans

Save a card

Using the “save card” feature

create a payment

Create the payment using save_card = true; a link to a payment page will be generated.
Redirect the customer to the payment page.
After entering card details, your customer is automatically redirected to the previously-indicated return page on your site.
PayPlug sends you a confirmation including the secure card ID via IPN (Instant Payment Notification).

This save_card option is not yet available for other payment methods.

Combining the “save card” with a payment

The following is an example of a payment with the “save card” feature that automatically redirects your client to the payment page:

<?php
$email = 'john.watson@example.net';
$amount = 33;
$customer_id = '42710';

$payment = \Payplug\Payment::create(array(
  'amount'           => $amount * 100,
  'currency'         => 'EUR',
  'save_card'        => true,
  'billing'  => array(
    'title'        => 'mr',
    'first_name'   => 'John',
    'last_name'    => 'Watson',
    'email'        => $email,
    'address1'     => '221B Baker Street',
    'postcode'     => 'NW16XE',
    'city'         => 'London',
    'country'      => 'GB',
    'language'     => 'en'
  ),
  'shipping'  => array(
    'title'         => 'mr',
    'first_name'    => 'John',
    'last_name'     => 'Watson',
    'email'         => $email,
    'address1'      => '221B Baker Street',
    'postcode'      => 'NW16XE',
    'city'          => 'London',
    'country'       => 'GB',
    'language'      => 'en',
    'delivery_type' => 'BILLING'
  ),
  'hosted_payment'   => array(
    'return_url'     => 'https://example.net/success?id='.$customer_id,
    'cancel_url'     => 'https://example.net/cancel?id='.$customer_id
  ),
  'notification_url' => 'https://example.net/notifications?id='.$customer_id,
  'metadata'         => array(
    'customer_id'    => $customer_id
  )
));

payment_data = {
  'amount': 3300,
  'currency': 'EUR',
  'save_card': True,
  'customer': {
    'email': 'john.watson@example.net'
  },
  'hosted_payment': {
    'return_url': 'https://example.net/success?id=42710',
    'cancel_url': 'https://example.net/cancel?id=42710',
  },
  'notification_url': 'https://example.net/notifications?id=42710',
  'metadata': {
    'customer_id': 42710,
  },
}
payment = payplug.Payment.create(**payment_data)

All amounts must be expressed in centimes as positive whole numbers (1€ = 100 centimes).

Confirmation

When creating a payment, you can specify a notification URL for use with IPN: notification_url. Whether the payment is successful or fails, a POST query containing an object corresponding to the payment will be sent to your server.

<?php
$input = file_get_contents('php://input');
try {
  $resource = \Payplug\Notification::treat($input);
  if ($resource instanceof \Payplug\Resource\Payment && $resource->is_paid) {
    $payment_id = $resource->id;
    $payment_state = $resource->is_paid,true;
    $payment_date = $resource->hosted_payment->paid_at;
    $payment_amount = $resource->amount;
    if ($resource->save_card == true) {
      $card_id = $resource->card->id;
      $card_exp_month = $resource->card->exp_month;
      $card_exp_year = $resource->card->exp_year;
    }
    $payment_data = $resource->metadata[customer_id];
  }
}
catch (\Payplug\Exception\PayplugException $exception) {
    echo htmlentities($exception);
}

request_body = request.body
try:
  resource = payplug.notifications.treat(request_body)
except payplug.exceptions.PayplugError:
  pass
else:
  if resource.object == 'payment' and resource.is_paid:
    payment_id = str(resource.id)
    payment_state = str(resource.is_paid)
    payment_date = datetime.datetime.fromtimestamp(resource.hosted_payment.paid_at).strftime('%d/%m/%Y %H:%M:%S')
    payment_amount = str(resource.amount)
    if resource.save_card == True
      card_id = str(resource.card.id)
      card_exp_month = str(resource.card.exp_month)
      card_exp_year = str(resource.card.exp_year)
      pass
    payment_data = resource.metadata['customer_id']
    pass

You may now extract the card ID from the object in the IPN. This is what you will use to initiate future transactions. We recommend that you also document the card’s expiration date in order to verify that the card is still valid before attempting future payments.

Payments using a card ID

create a payment with a card id

Create the payment using payment_method and the previously saved card ID.
PayPlug sends you a confirmation via IPN.

Processing a payment using a card ID

Now that you have a card ID, you can initiate new payments without necessarily sending your customer to a payment page:

<?php
$email = 'john.watson@example.net';
$amount = 33;
$customer_id = '42710';
$card_id = 'card_e7133426b8de947b37161dfba1897dd1';
$initiator = 'PAYER';

$payment = \Payplug\Payment::create(array(
  'amount'         => $amount * 100,
  'currency'       => 'EUR',
  'payment_method' => $card_id,
  'initiator'      => $initiator,
  'billing'      => array(
    'title'      => 'mr',
    'first_name' => 'John',
    'last_name'  => 'Watson',
    'email'      => $email,
    'address1'   => '221B Baker Street',
    'postcode'   => 'NW16XE',
    'city'       => 'London',
    'country'    => 'GB',
    'language'   => 'en'
  ),
  'shipping'        => array(
    'title'         => 'mr',
    'first_name'    => 'John',
    'last_name'     => 'Watson',
    'email'         => $email,
    'address1'      => '221B Baker Street',
    'postcode'      => 'NW16XE',
    'city'          => 'London',
    'country'       => 'GB',
    'language'      => 'en',
    'delivery_type' => 'BILLING'
  ),
  'notification_url'  => 'https://example.net/notifications?id='.$customer_id,
  'metadata'        => array(
      'customer_id' => $customer_id
  )
));

payment_data = {
  'amount': 1000,
  'currency': 'EUR',
  'payment_method': 'card_e7133426b8de947b37161dfba1897dd1',
  'customer': {
    'email': 'john.watson@example.net'
  },
  'notification_url': 'https://example.net/notifications?id=42710',
  'metadata': {
    'customer_id': 42710,
  },
}
payment = payplug.Payment.create(**payment_data)

Once the payment is created, you have to handle the response as explained in the next page.

Payment processing

The payment object holds many fields that you’ll need to process the payment, especially:

{
  "id": "pay_5iHMDxy4ABR4YBVW4UscIn",
  "amount": 1000,
  "is_paid": true,
  "authorization": null,
  "failure": null,
  "hosted_payment": {
    "payment_url": "https://secure.payplug.com/pay/5iHMDxy4ABR4YBVW4UscIn",
    "return_url": "https://example.net/success?id=42",
    "cancel_url": "https://example.net/cancel?id=42",
    "paid_at": 1434010827,
    "sent_by": null
  },
  [...]
}

Then you have to handle the response with this logic and in the following order:

if is_paid is true, you can consider the payment as being fully paid,
if both fields authorization and authorized_at are present and filled, the authorization was successful,
if you got a failure, well you got a failed payment,
otherwise you’ll have a hosted_payment.payment_url where the payer has to be redirected to complete the payment.

Your customer will receive a confirmation email after each new transaction.

Advantages

The ‘save card’ feature makes the following payment options possible:

1-click ordering

Customers can pay securely without typing in their card details for every purchase.

Recurring payments

Customers can subscribe to services on your site using recurring payments.

Instalments

Customers can pay in three or four interest-free instalments (within a maximum 90-day period).

Please note that recurring payments and instalments are not automated; you will need to manage the payment schedules internally.

Display an Oney pop-in

The Oney pop-in

Oney pop-in

The data used to display the pop-in can be acquired using the Oney payment simulation endpoint.

The Oney payment simulation request

The following code shows an example of an Oney payment simulation request.

<?php
$simulations = \Payplug\OneySimulation::getSimulations(array(
  'amount' => 17266,
  'country' => 'FR',
  'operations' => ['x3_with_fees', 'x4_with_fees']
));

data = {
  'amount': 17266,
  'country': 'FR',
  'operations': ['x3_with_fees', 'x4_with_fees']
}
simulations = payplug.OneyPaymentSimulation.get_simulation(**data)

The Oney payment simulation data

The data can be used to display the pop-in.

{
  "result": true,
  "simulations": {
    "x3_with_fees": {...},
    "x4_with_fees": {
      "installments": [
        {
          "date": "2021-01-22T01:00:00.000Z",
          "amount": 4316
        },
        {
          "date": "2021-02-22T01:00:00.000Z",
          "amount": 4316
        },
        {
          "date": "2021-03-22T01:00:00.000Z",
          "amount": 4317
        }
      ],
      "total_cost": 380,
      "nominal_annual_percentage_rate": 18.05,
      "effective_annual_percentage_rate": 19.62,
      "down_payment_amount": 4697
    }
  }
}

Mapping the fields

Pop-in	Data
Pour un montant de	`amount` sent as request data
Premier apport	`down_payment_amount`
Coût du financement	`total_cost`
TAEG	`effective_annual_percentage_rate`
Mensualité n°1	`installments[0]['amount']`
Mensualité n°2	`installments[1]['amount']`
Mensualité n°3	`installments[2]['amount']`
Total	`down_payment_amount` + `installments[0]['amount']` + `installments[1]['amount']` + `installments[2]['amount']`

PayPlug API Quick guides

[ PHP ]

Installing the Library

Authentication

The payment creation process

Creating a payment

Confirmation

Option 1: Instant Payment Notification (IPN)

Confirmation

Option 2: Extracting payment details

Managing metadata

The refund creation process

Processing a refund

Option 1: Full refunds

Processing a refund

Option 2: Partial refunds

Confirmation

Option 1: Instant Payment Notification (IPN)

Confirmation

Option 2: Extracting payment details

Managing metadata

The payment request creation process

Payment request delivery methods

Creating a payment request by e-mail

Creating a payment request by SMS

Payment requests compatibility

Using the “save card” feature

Combining the “save card” with a payment

Confirmation

Payments using a card ID

Processing a payment using a card ID

Payment processing

Advantages

1-click ordering

Recurring payments

Instalments

The Oney pop-in

The Oney payment simulation request

The Oney payment simulation data

Mapping the fields