Overview

Based on simple REST concepts, the PayPlug API returns JSON objects for your payments, refunds, installment plans, etc.

All API URLs listed in this documentation are relative to https://api.payplug.com. For example, the create payment API call is reachable at https://api.payplug.com/v1/payments.

Authentication

Example:

$ curl -X GET https://api.payplug.com/v1/payments \
   -H "Authorization: Bearer sk_live_43b7e007298f57f732800a52" \
   -H "PayPlug-Version: 2019-08-06"

<?php
// Not required using composer
require_once('PATH_TO_PAYPLUG/payplug_php/lib/init.php');
\Payplug\Payplug::setSecretKey('sk_live_43b7e007298f57f732800a52');

import payplug

payplug.set_secret_key('sk_live_43b7e007298f57f732800a52')

You must authenticate to the PayPlug API by providing in all your requests one of your secret Keys available in the My account section of the PayPlug Portal.

Authentication occurs using the HTTP Authorization header. You do not need to provide your password in your requests.

All API requests must use HTTPS: every call made over simple HTTP will fail.

Access LIVE and TEST modes using the same endpoint. To switch between each mode you have 2 differents secret keys:

You simply have to provide the secret key from the mode you wish to use.

Because the prefix is different, you will easily recognize them. ;)

Version

You can specify which version of the API to use by sending the custom PayPlug-Version HTTP header. By convention, PayPlug uses datetimes in the ISO 8601 format for its versions. This documentation assumes the usage of the most up-to-date version of the API. A request without the header will fall back to the legacy version of the API. You can find version history in the changelog.

Current version is 2019-08-06.

PSD2

PSD2 (Payment Service Directive 2, DSP2 in French) is enforcing new technical standards on payment authentication, you can find more about the details of the directive in our FAQ.

The current version of the API is PSD2 ready, if you are using a previous version of the API, we strongly recommend that you update your integration. Moreover, as acquiring and issuing banks are gradually updating their resources to PSD2’s requirements, you should expect changes to come to the API in the coming months.

Find the documentation of the previous version as a printable pdf here.

Delivery type

The field shipping.delivery_type is required to create PSD2-compliant payments and installment plans. It accepts the following values:

• BILLING: Ship to cardholder’s billing address
• VERIFIED: Ship to another verified address on file with merchant
• NEW: Ship to an address that is different than the cardholder’s billing address
• SHIP_TO_STORE: Pick-up at a local store (store address shall be populated in shipping address fields)
• DIGITAL_GOODS: Online services, electronic gift cards, redemption codes, and other digital goods
• TRAVEL_OR_EVENT: Travel and Event tickets, not shipped
• OTHER: Other (for example, Gaming, digital services not shipped, e-media subscriptions, etc.)

Notifications

A notification is a POST HTTP request sent by PayPlug to your server to notify your system that some object (a payment, an installment plan, etc) was updated.

When creating an object (e.g a payment), you can provide a notification URL that will be used for updates related to this object.

Notifications content

Example:

{
  "id": "pay_5iHMDxy4ABR4YBVW4UscIn",
  "object": "payment",
  "is_live": true
}

The POST request includes a JSON body with at least three attributes.

Object attributes:

Notifications management

Notifications management example:

import payplug


request_body = request.body  # This line may depend on your framework.
try:
  resource = payplug.notifications.treat(request_body)
except payplug.exceptions.PayplugError:
  # Handle errors
  pass
else:
  if resource.object == 'payment' and resource.is_paid:
    # Process the paid payment
    pass
  elif resource.object == 'refund':
    # Process the refund
    pass

<?php
require_once('PATH_TO_PAYPLUG/payplug_php/lib/init.php');
\Payplug\Payplug::setSecretKey('sk_test_500e54fxx362355a7xx00ad');

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

  if ($resource instanceof \Payplug\Resource\Payment
    && $resource->is_paid 
    // Ensure that the payment was paid
    ) {
    // Process a paid payment.
  } else if ($resource instanceof \Payplug\Resource\Refund) {
    // Process the refund.
  }
}
catch (\Payplug\Exception\PayplugException $exception) {
 // Handle errors
}

When you implement a notifications management system, you first need to:

• Use the object attribute to determine what the notification is about (a payment, or a refund, etc).
• Use the is_live attribute to determine whether the notification concerns a LIVE or TEST object.

Then, you need to retrieve the object using its id, using a GET request (e.g. retrieve a payment).

Specific documentation for notifications

• Payment notifications.
• Refund notifications.
• Installment plan notifications.
• Accounting report notifications.

Pagination

Example:

$ curl -X GET https://api.payplug.com/v1/payments?page=1&per_page=5 \
  -H "Authorization: Bearer sk_live_43b7e007298f57f732800a52" \
  -H "PayPlug-Version: 2019-08-06"

<?php
$perPage = 5;
$page = 1;
$payments = \Payplug\Payment::listPayments($perPage, $page);

per_page = 5
page = 1
payments = payplug.Payment.list(per_page, page)

Example response:

{
  "object": "list",
  "page": 1,
  "per_page": 1,
  "has_more": true,
  "data": [{
    "id": "pay_5iHMDxy4ABR4YBVW4UscIn",
    "object": "payment",
    "is_live": true,
    "amount": 3300
  }]
}

The PayPlug API uses the same pagination structure for requests to list payments and refunds.

URL arguments:

The page parameter is based on the maximum number listed in the per_page parameter. For exemple, if you have 12 objects and you have specified into your request: per_page=8, if you want to see the part of the list with the ninth object you should use: page=1.

If you don’t specify the page parameter in your request, you will receive the last 10 objects of the list.

Response detail:

Metadata

All PayPlug’s API objects support additional custom metadata.

Metadata enables you to store information as user-defined key-value pairs. You can define JSON data up to 1000 characters long, without limitation of keys or levels.

Example refund object:

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

For example, when you create a payment, you could add information about your customer such as a customer ID, a product ID, a transaction ID, shipping information…

Metadata example:

Errors

Example response:

{
  "object": "error",
  "message": "You did not provide any Authentication HTTP header. You must authenticate with your LIVE or TEST API key.",
  "id": "2fa981d70eaa11e58abba8206650bd9f"
}

The PayPlug API use standard HTTP response status code. Errors are returned with additional data in the body of the return call (JSON-formatted).

HTTP status codes

Example response:

{
  "object": "error",
  "message": "Wrong or missing parameters (see details).",
  "id": "349c30b00eac11e5a301a8206650bd9f",
  "details": {
    "amount": "The minimum amount is 1 EUR (100 cents). The amount you provided is 5 cents.",
    "customer": {
      "first_name": "The first_name is too long. The maximum length is 100 characters."
    },
    "force_3ds": "This parameter must be a boolean (true or false)."
  }
}

Codes in the 4xx range indicate an error. An object is returned to your requests including information about the error with a reference ID.

400 error code (Bad Request) is including additional information about which parameters are wrong or missing in your request.

Codes in the 2xx range indicate your request worked whitout any issues and 5xx range appear when something went wrong on PayPlug’s end.

Payment failure codes

Unsuccessful payment return information about the error in the response with a failure code and a failure message.

Installment plan failure codes

Unsuccessful installment plan return information about the error in the response with a failure code and a failure message.

API Testing

Best practices when testing the PayPlug API

When integrating the PayPlug API you should use the TEST mode to ensure the following:

1. Card number, expiration, amount and CVC are set correctly
2. Error messages from the API are handled and displayed correctly
3. Sensitive information about the cards (number and CVC) are not stored on your server
4. All information and values related to payments sent to the API are valid and correctly formatted
5. Never hardcode your secret key into your code, use configuration values

Card numbers available for testing

Using TEST mode, the following test cards are available for testing your integration:

Any CVC numbers and any expiration date in the future will be considered valid.

All others card numbers even if they are valid will fail (Failure code: card_declined).

It is not possible to use these card numbers for Bancontact payments.

More information about error codes is available here.

Payments

Use the /payments endpoint to create a payment, list the payments or retrieve a payment.

Payments endpoint reference:

The payment object

Example:

{
  "id": "pay_5iHMDxy4ABR4YBVW4UscIn",
  "object": "payment",
  "is_live": true,
  "amount": 3300,
  "amount_refunded": 0,
  "authorization": null,
  "currency": "EUR",
  "created_at": 1434010787,
  "refundable_after": 1449157171,
  "refundable_until": 1459157171,
  "installment_plan_id": null,
  "is_paid": true,
  "paid_at": 1555073519,
  "is_refunded": false,
  "is_3ds": false,
  "save_card": false,
  "card": {
    "last4": "1800",
    "country": "FR",
    "exp_month": 9,
    "exp_year": 2017,
    "brand": "Mastercard",
    "id": null
  },
  "billing": {
    "title": "mr",
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "mobile_phone_number": null,
    "landline_phone_number": null,
    "address1": "221B Baker Street",
    "address2": null,
    "postcode": "NW16XE",
    "city": "London",
    "state": null,
    "country": "GB",
    "language": "en"
  },
  "shipping": {
    "title": "mr",
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "mobile_phone_number": null,
    "landline_phone_number": null,
    "address1": "221B Baker Street",
    "address2": null,
    "postcode": "NW16XE",
    "city": "London",
    "state": null,
    "country": "GB",
    "language": "en",
    "delivery_type": "BILLING"
  },
  "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
  },
  "notification": {
    "url": "https://example.net/notifications?id=42",
    "response_code": 200
  },
  "failure": null,
  "description": null,
  "metadata": {
    "customer_id": 42
  }
}

<?php
// Get an attribute of the payment object:
// Print the payment amount
echo htmlentities($payment->amount);
// Print the payment id
echo htmlentities($payment->id);
// Print the payment creation time in an human readable way
echo htmlentities(date('d/m/Y H:i:s', $payment->created_at));

// Chain relations between objects:
// Print the payment URL
echo htmlentities($payment->hosted_payment->payment_url);
// Print the customer email
echo htmlentities($payment->billing->email);

// Retrieve metadata
echo htmlentities($payment->metadata['customer_id']);
echo htmlentities($payment->metadata['type']);

# Get an attribute of the payment object:
# Print the payment amount
print(str(payment.amount))
# Print the payment id
print(str(payment.id))
# Print the payment creation time in an human readable way
print(datetime.datetime.fromtimestamp(payment.created_at).strftime('%d/%m/%Y %H:%M:%S'))

# Chain relations between objects:
# Print the payment URL
print(payment.hosted_payment.payment_url)
# Print the customer email
print(payment.customer.email)

# Retrieve metadata
print(payment.metadata['customer_id'])
print(payment.metadata['type'])

Object attributes:

Create a payment

Example:

$ curl -X POST https://api.payplug.com/v1/payments \
  -H 'Authorization: Bearer sk_test_9898098098guGYUG9' \
  -H 'PayPlug-Version: 2019-08-06' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 3300,
    "currency": "EUR",
    "billing": {
      "title": "mr",
      "first_name": "John",
      "last_name": "Watson",
      "mobile_phone_number": "+33612345678",
      "email": "john.watson@example.net",
      "address1": "221B Baker Street",
      "postcode": "NW16XE",
      "city": "London",
      "country": "GB",
      "language": "en"
    },
    "shipping": {
      "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": {
      "return_url": "https://example.net/success?id=42",
      "cancel_url": "https://example.net/cancel?id=42"
    },
    "notification_url": "https://example.net/notifications?id=42",
    "metadata": {
      "customer_id": "42"
     },
     "save_card": false,
     "force_3ds": true
  }'

<?php
$payment = \Payplug\Payment::create(array(
  'amount'           => 3300,
  'currency'         => 'EUR',
  'save_card'        => false,
  'billing'               => array(
    'title'               => 'mr',
    'first_name'          => 'John',
    'last_name'           => 'Watson',
    'mobile_phone_number' => '+33612345678',
    '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/success?id=42',
    'cancel_url'   => 'https://example.net/cancel?id=42'
  ),
  'notification_url' => 'https://example.net/notifications?id=42',
  'metadata'      => array(
    'customer_id' => 42
  )
));

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

payment_data = {
  'amount': 3300,
  'currency': 'EUR',
  'save_card': False,
  'billing': {
    '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': {
    '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': {
    'return_url': 'https://example.net/success?id=42',
    'cancel_url': 'https://example.net/cancel?id=42',
  },
  'notification_url': 'https://example.net/notifications?id=42',
  'metadata': {
    'customer_id': 42,
  },
}
payment = payplug.Payment.create(**payment_data)

Example response:

{
  "amount": 3300,
  "amount_refunded": 0,
  "authorization": null,
  "card": {
    "brand": null,
    "country": null,
    "exp_month": null,
    "exp_year": null,
    "id": null,
    "last4": null
  },
  "created_at": 1449157171,
  "refundable_after": 1449157171,
  "refundable_until": 1459157171,
  "currency": "EUR",
  "billing": {
    "title": "mr",
    "first_name": "John",
    "last_name": "Watson",
    "mobile_phone_number": "+33612345678",
    "email": "john.watson@example.net",
    "mobile_phone_number": null,
    "landline_phone_number": null,
    "address1": "221B Baker Street",
    "address2": null,
    "postcode": "NW16XE",
    "city": "London",
    "state": null,
    "country": "GB",
    "language": "en"
  },
  "shipping": {
    "title": "mr",
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "mobile_phone_number": null,
    "landline_phone_number": null,
    "address1": "221B Baker Street",
    "address2": null,
    "postcode": "NW16XE",
    "city": "London",
    "state": null,
    "country": "GB",
    "language": "en",
    "delivery_type": "BILLING"
  },
  "failure": null,
  "hosted_payment": {
    "cancel_url": "https://example.net/cancel?id=42",
    "paid_at": null,
    "payment_url": "https://secure.payplug.com/pay/test/2DNkjF024bcLFhTn7OBfcc",
    "return_url": "https://example.net/success?id=42",
    "sent_by": null
  },
  "id": "pay_2DNkjF024bcLFhTn7OBfcc",
  "is_3ds": null,
  "is_live": false,
  "is_paid": false,
  "paid_at": null,
  "is_refunded": false,
  "installment_plan_id": null,
  "description": null,
  "metadata": {
    "customer_id": "42"
  },
  "notification": {
    "response_code": null,
    "url": "https://example.net/notifications?id=42"
  },
  "object": "payment",
  "save_card": false
}

To accept a payment from your customer, first create a payment and then redirect to the payment_url provided in the response object. Once your customer has attempted to pay, he will be redirected to your return_url.

Once a payment URL is obtained and the payment page is displayed to your client, he will be able to try multiple times to pay using the same payment URL, in case the previous payment attempts fail.

A notification will also be sent (if notification_url was provided) in case the payment is successful (is paid).

The payment URL will be available for 15 minutes. If the payment was not successfully paid during this time period, it will automatically expire after 15 minutes and a notification will be sent (if notification_url was provided) containing the last attempt’s failure code and failure reason.

You can create a hosted payment that will never expire (the hosted_payment.payment_url will always be available), by providing hosted_payment.sent_by value:

• EMAIL or SMS: an email or an SMS will be sent to the customer by PayPlug.
• OTHER: you are responsible for sharing the payment URL to your customer.

If you saved a card and use it to create a payment, the payment will be paid directly, so that there is no payment_url.

If you create a deferred payment (see parameter authorized_amount), then when the customer pays using the payment page, the payment is only authorized, meaning the funds are locked in the customer’s account, but no transaction is issued yet. You should then capture the payment up to 7 days following the authorization (see Capture a payment).

For a better integration to your site, you can create a more customised look and feel to your payment page with your own custom logo, background and colors.

Parameters:

Specific parameters rules for Oney payments

Some of the previous parameters are marked as optional, but are required for Oney payments. Additionally, some specific limitations apply for Oney payments:

• Oney payments must be deffered payments. It means that if method_method is one of the oney_* payment methods, then the payment’s amount must be given through the field authorized_amount and not amount.
• The amount for an Oney payment ranges between 10000 and 300000 cents
• The following fields are mandatory for Oney payments:
  • payment_context
  • In shipping and billing objects:
    • first_name
    • last_name
    • address1
    • postcode
    • city
    • country
    • email
    • mobile_phone_number
  • In shipping object only:
    • company_name
    • delivery_type
• billing.country must be the same as shipping.country
• Available countries are France (FR), Italy (IT), and France’s overseas departments and regions (GP, MQ, GF, RE, YT).
• Email addresses cannot contain a plus sign (+). Affected fields are billing.email and shipping.email.
• The sum of quantities of the cart (field payment_context.cart) must be less than 1000.

Retrieve a payment

Example:

$ curl -X GET https://api.payplug.com/v1/payments/pay_5iHMDxy4ABR4YBVW4UscIn \
  -H 'Authorization: Bearer sk_test_9898098098guGYUG9' \
  -H 'PayPlug-Version: 2019-08-06'

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

payment = payplug.Payment.retrieve('pay_5iHMDxy4ABR4YBVW4UscIn')

Example response:

{
  "id": "pay_5iHMDxy4ABR4YBVW4UscIn",
  "object": "payment",
  "is_live": true,
  "amount": 3300,
  "amount_refunded": 0,
  "authorization": null,
  "currency": "EUR",
  "created_at": 1434010787,
  "refundable_after": 1449157171,
  "refundable_until": 1459157171,
  "installment_plan_id": null,
  "is_paid": true,
  "paid_at": 1555073519,
  "is_refunded": false,
  "is_3ds": false,
  "save_card": false,
  "card": {
    "last4": "1800",
    "country": "FR",
    "exp_month": 9,
    "exp_year": 2017,
    "brand": "Mastercard",
    "id": null
  },
  "billing": {
    "title": "mr",
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "mobile_phone_number": "+33612345678",
    "landline_phone_number": null,
    "address1": "221B Baker Street",
    "address2": null,
    "postcode": "NW16XE",
    "city": "London",
    "state": null,
    "country": "GB",
    "language": "en"
  },
  "shipping": {
    "title": "mr",
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "mobile_phone_number": null,
    "landline_phone_number": null,
    "address1": "221B Baker Street",
    "address2": null,
    "postcode": "NW16XE",
    "city": "London",
    "state": null,
    "country": "GB",
    "language": "en",
    "delivery_type": "BILLING"
  },
  "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
  },
  "notification": {
    "url": "https://example.net/notifications?id=42",
    "response_code": 200
  },
  "failure": null,
  "description": null,
  "metadata": {
    "customer_id": 42
  }
}

Retrieves the information of a specific payment that has already been created.

The request will return a payment object if the ID provided is valid, and it will return an error object otherwise.

URL arguments:

Update a payment

Example :

$ curl -X PATCH https://api.payplug.com/v1/payments/pay_5iHMDxy4ABR4YBVW4UscIn \
  -H 'Authorization: Bearer sk_test_9898098098guGYUG9' \
  -H 'PayPlug-Version: 2019-08-06' \
  -H 'Content-Type: application/json' \
  -d '{
    "metadata": {
      "customer_id": 42,
      "comment": "asked questions about size"
     }
  }'

<?php
$paymentId = 'pay_5iHMDxy4ABR4YBVW4UscIn';
$payment = \Payplug\Payment::retrieve($paymentId);

// To update metadatas keys
$data = array(
  'metadata'      => array(
    'customer_id' => 42,
    'comment'     => 'asked questions about size'
  )
);
$update = payment->update($data);

// To remove all metadatas
$update = payment->update();

# Currently not available in Python library

Example response:

{
  "amount": 3300,
  "amount_refunded": 0,
  "authorization": null,
  "card": {
    "brand": null,
    "country": null,
    "exp_month": null,
    "exp_year": null,
    "id": null,
    "last4": null
  },
  "created_at": 1449157475,
  "refundable_after": 1449157171,
  "refundable_until": 1459157171,
  "currency": "EUR",
  "billing": {
    "title": "mr",
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "mobile_phone_number": null,
    "landline_phone_number": null,
    "address1": "221B Baker Street",
    "address2": null,
    "postcode": "NW16XE",
    "city": "London",
    "state": null,
    "country": "GB",
    "language": "en"
  },
  "shipping": {
    "title": "mr",
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "mobile_phone_number": null,
    "landline_phone_number": null,
    "address1": "221B Baker Street",
    "address2": null,
    "postcode": "NW16XE",
    "city": "London",
    "state": null,
    "country": "GB",
    "language": "en",
    "delivery_type": "BILLING"
  },
  "failure": {
    "code": "aborted",
    "message": "You have aborted the transaction."
  },
  "hosted_payment": {
    "cancel_url": "https://example.net/cancel?id=42",
    "paid_at": null,
    "payment_url": "https://secure.payplug.com/pay/test/5iHMDxy4ABR4YBVW4UscIn",
    "return_url": "https://example.net/success?id=42",
    "sent_by": null
  },
  "id": "pay_5iHMDxy4ABR4YBVW4UscIn",
  "is_3ds": null,
  "is_live": false,
  "is_paid": false,
  "paid_at": null,
  "is_refunded": false,
  "installment_plan_id": null,
  "description": null,
  "metadata": {
      "customer_id": "42",
      "comment": "asked questions about size"
  },
  "notification": {
    "response_code": null,
    "url": "https://example.net/notifications?id=42"
  },
  "object": "payment",
  "save_card": false
}

Update Metadata for a payment that has already been created to update custom information you have defined.

The request will respond with an updated payment object if the ID provided is valid, and it will respond with an error object otherwise.

Parameters:

Capture a payment

Create a deferred payment:

$ curl -X POST https://api.payplug.com/v1/payments \
  -H 'Authorization: Bearer sk_test_9898098098guGYUG9' \
  -H 'PayPlug-Version: 2019-08-06' \
  -H 'Content-Type: application/json' \
  -d '{
    "authorized_amount": 3300,
    "currency": "EUR",
    "billing": {
      "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": {
      "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": {
      "return_url": "https://example.net/success?id=42",
      "cancel_url": "https://example.net/cancel?id=42"
    },
    "notification_url": "https://example.net/notifications?id=42",
    "metadata": {
      "customer_id": "42"
     }
  }'

<?php
$payment = \Payplug\Payment::create(array(
  'authorized_amount' => 3300,
  'currency'          => 'EUR',
  'save_card'         => false,
  '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/success?id=42',
    'cancel_url'      => 'https://example.net/cancel?id=42'
  ),
  'notification_url' => 'https://example.net/notifications?id=42',
  'metadata'      => array(
    'customer_id' => 42
  )
));

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

Capture the payment:

$ curl -X PATCH https://api.payplug.com/v1/payments/pay_5iHMDxy4ABR4YBV \
  -H 'Authorization: Bearer sk_test_9898098098guGYUG9' \
  -H 'PayPlug-Version: 2019-08-06' \
  -H 'Content-Type: application/json' \
  -d '{"captured": true}'

<?php
// Capture from a payment ID
$payment_capture = \Payplug\Payment::capture($payment_id);

// Capture from a payment object
$payment_capture = \Payplug\Payment::retrieve($payment_id);
$payment_capture = $payment_capture->capture();

Example response:

{
  "id": "pay_5iHMDxy4ABR4YBVW4UscIn",
  "object": "payment",
  "is_live": true,
  "amount": 3300,
  "amount_refunded": 0,
  "authorization": {
    "authorized_at": 1555073502,
    "expires_at": 1555632000,
    "authorized_amount": 3300
  },
  "currency": "EUR",
  "created_at": 1434010787,
  "refundable_after": 1449157171,
  "refundable_until": 1459157171,
  "installment_plan_id": null,
  "is_paid": true,
  "paid_at": 1555073519,
  "is_refunded": false,
  "is_3ds": false,
  "save_card": false,
  "card": {
    "last4": "1800",
    "country": "FR",
    "exp_month": 9,
    "exp_year": 2017,
    "brand": "Mastercard",
    "id": null
  },
  "billing": {
    "title": "mr",
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "mobile_phone_number": null,
    "landline_phone_number": null,
    "address1": "221B Baker Street",
    "address2": null,
    "postcode": "NW16XE",
    "city": "London",
    "state": null,
    "country": "GB",
    "language": "en"
  },
  "shipping": {
    "title": "mr",
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "mobile_phone_number": null,
    "landline_phone_number": null,
    "address1": "221B Baker Street",
    "address2": null,
    "postcode": "NW16XE",
    "city": "London",
    "state": null,
    "country": "GB",
    "language": "en",
    "delivery_type": "BILLING"
  },
  "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
  },
  "notification": {
    "url": "https://example.net/notifications?id=42",
    "response_code": 200
  },
  "failure": null,
  "description": null,
  "metadata": {
    "customer_id": 42
  }
}

Capture a deferred payment that has been authorized.

The request will respond with a payment object if the ID provided is valid, and it will respond with an error object otherwise.

URL arguments:

Parameters:

Abort a payment

Example:

$ curl -X PATCH https://api.payplug.com/v1/payments/pay_5iHMDxy4ABR4YBVW4UscIn \
  -H 'Authorization: Bearer sk_test_9898098098guGYUG9' \
  -H 'PayPlug-Version: 2019-08-06' \
  -H 'Content-Type: application/json' \
  -d '{"aborted": true}'

<?php
// Abort from a payment ID
$paymentId = 'pay_5iHMDxy4ABR4YBVW4UscIn';
$payment = \Payplug\Payment::abort($paymentId);

// Abort from a payment object
$paymentId = 'pay_5iHMDxy4ABR4YBVW4UscIn';
$payment = \Payplug\Payment::retrieve($paymentId);
$payment = $payment->abort();

# Abort from a payment ID
payment_id = 'pay_5iHMDxy4ABR4YBVW4UscIn'
payment = payplug.Payment.abort(payment_id)

# Abort from a payment object
payment = payplug.Payment.retrieve(payment_id)
payment = payment.abort()

Example response:

{
  "amount": 3300,
  "amount_refunded": 0,
  "authorization": null,
  "card": {
    "brand": null,
    "country": null,
    "exp_month": null,
    "exp_year": null,
    "id": null,
    "last4": null
  },
  "created_at": 1449157475,
  "refundable_after": 1449157171,
  "refundable_until": 1459157171,
  "currency": "EUR",
  "billing": {
    "title": "mr",
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "mobile_phone_number": null,
    "landline_phone_number": null,
    "address1": "221B Baker Street",
    "address2": null,
    "postcode": "NW16XE",
    "city": "London",
    "state": null,
    "country": "GB",
    "language": "en"
  },
  "shipping": {
    "title": "mr",
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "mobile_phone_number": null,
    "landline_phone_number": null,
    "address1": "221B Baker Street",
    "address2": null,
    "postcode": "NW16XE",
    "city": "London",
    "state": null,
    "country": "GB",
    "language": "en",
    "delivery_type": "BILLING"
  },
  "failure": {
    "code": "aborted",
    "message": "You have aborted the transaction."
  },
  "hosted_payment": {
    "cancel_url": "https://example.net/cancel?id=42",
    "paid_at": null,
    "payment_url": "https://secure.payplug.com/pay/test/5iHMDxy4ABR4YBVW4UscIn",
    "return_url": "https://example.net/success?id=42",
    "sent_by": null
  },
  "id": "pay_5iHMDxy4ABR4YBVW4UscIn",
  "is_3ds": null,
  "is_live": false,
  "is_paid": false,
  "paid_at": null,
  "is_refunded": false,
  "installment_plan_id": null,
  "description": null,
  "metadata": {
      "customer_id": "42"
  },
  "notification": {
    "response_code": null,
    "url": "https://example.net/notifications?id=42"
  },
  "object": "payment",
  "save_card": false
}

Abort a payment that has already been created to prevent its utilization.

The payment page will display a message explaining this payment is no longer available.

When a payment is aborted, the failure attribute will return: aborted.

The request will respond with a payment object if the ID provided is valid, and it will respond with an error object otherwise.

URL arguments:

Parameters:

List all payments

Example:

$ curl -X GET https://api.payplug.com/v1/payments \
  -H 'Authorization: Bearer sk_test_9898098098guGYUG9' \
  -H 'PayPlug-Version: 2019-08-06'

<?php
$payments = \Payplug\Payment::listPayments();
$payment = $payments[0];

payments = payplug.Payment.list()
payment = next(payments)

Example response:

{
  "object": "list",
  "page": 0,
  "per_page": 10,
  "has_more": true,
  "data": [{
    "id": "pay_5iHMDxy4ABR4YBVW4UscIn",
    "object": "payment",
    "is_live": true,
    "amount": 3300
  }]
}

Retrieves a list of all the payment objects created for this authentication ID. All the payments are returned as a sorted list object (learn more in pagination section).

Save a card

Create a payment and save the card:

$ curl -X POST https://api.payplug.com/v1/payments \
  -H 'Authorization: Bearer sk_test_9898098098guGYUG9' \
  -H 'PayPlug-Version: 2019-08-06' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 3300,
    "currency": "EUR",
    "save_card": true,
    "billing": {
      "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": {
      "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": {
      "return_url": "https://example.net/success?id=42",
      "cancel_url": "https://example.net/cancel?id=42"
    },
    "notification_url": "https://example.net/notifications?id=42",
    "metadata": {
      "customer_id": "42"
    }
  }'

<?php
$payment = \Payplug\Payment::create(array(
  'amount'           => 3300,
  'currency'         => 'EUR',
  'save_card'        => true,
  '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://www.example.net/success?id=42',
    'cancel_url'   => 'https://www.example.net/cancel?id=42'
  ),
  'notification_url' => 'https://example.net/notifications?id=42',
  'metadata'      => array(
    'customer_id' => 42
  )
));

payment_data = {
  'amount': 3300,
  'currency': 'EUR',
  'save_card': True,
  'billing': {
    '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': {
    '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': {
    'return_url': 'https://example.net/success?id=42',
    'cancel_url': 'https://example.net/cancel?id=42',
  },
  'notification_url': 'https://example.net/notifications?id=42',
  'metadata': {
    'customer_id': 42,
  },
}
payment = payplug.Payment.create(**payment_data)

Example object once the payment is completed:

{
  "id": "pay_5iHMDxy4ABR4YBVW4UscIn",
  "object": "payment",
  "is_live": true,
  "amount": 3300,
  "amount_refunded": 0,
  "authorization": null,
  "currency": "EUR",
  "created_at": 1434010787,
  "refundable_after": 1449157171,
  "refundable_until": 1459157171,
  "is_paid": true,
  "paid_at": 1555073519,
  "is_refunded": false,
  "is_3ds": true,
  "installment_plan_id": null,
  "save_card": true,
  "card": {
    "last4": "1800",
    "country": "FR",
    "exp_month": 9,
    "exp_year": 2017,
    "brand": "Mastercard",
    "id": "card_e7133426b8de947b37161dfba1897dd1"
  },
  "billing": {
    "title": "mr",
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "mobile_phone_number": null,
    "landline_phone_number": null,
    "address1": "221B Baker Street",
    "address2": null,
    "postcode": "NW16XE",
    "city": "London",
    "state": null,
    "country": "GB",
    "language": "en"
  },
  "shipping": {
    "title": "mr",
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "mobile_phone_number": null,
    "landline_phone_number": null,
    "address1": "221B Baker Street",
    "address2": null,
    "postcode": "NW16XE",
    "city": "London",
    "state": null,
    "country": "GB",
    "language": "en",
    "delivery_type": "BILLING"
  },
  "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
  },
  "notification": {
    "url": "https://example.net/notifications?id=42",
    "response_code": 200
  },
  "failure": null,
  "description": null,
  "metadata": {
    "customer_id": 42
  }
}

You may save a card in order to create a payment later. The same card will be used with no need of the payment page.

Saving a card is very simple. You can just use the property save_card = true or allow_save_card = true when you create a new payment.

The response object will include a card ID (id) once the payment has been done (via notification or by retrieving the payment).

This card id can then be used to create a new payment with the same card.

With save_card key, the customer is required to save the card when completing the payment.
The box is checked by default on the payment page and the customer will not be able to validate the payment if he tries to uncheck the box.

Alternatively, when using allow_save_card key parameter, saving the card is optional to complete the payment.
The customer will be able to choose to save or not the card, by checking the box on the payment page.

save_card and allow_save_card can not be used at the same time.

Pay with a saved card

Create a payment with the card ID:

$ curl -X POST https://api.payplug.com/v1/payments \
  -H 'Authorization: Bearer sk_test_9898098098guGYUG9' \
  -H 'PayPlug-Version: 2019-08-06' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 1000,
    "currency": "EUR",
    "payment_method": "card_e7133426b8de947b37161dfba1897dd1",
    "initiator": "PAYER",
    "billing": {
      "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": {
      "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"
    }
  }'

<?php
$payment = \Payplug\Payment::create(array(
  'amount'         => 1000,
  'currency'       => 'EUR',
  'payment_method' => 'card_e7133426b8de947b37161dfba1897dd1',
  'initiator'      => 'PAYER',
  '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'
  ),
  'notification_url' => 'https://example.net/notifications?id=42',
  'metadata'      => array(
    'customer_id' => 42
  )
));

payment_data = {
  'amount': 1000,
  'currency': 'EUR',
  'payment_method': 'card_e7133426b8de947b37161dfba1897dd1',
  'initiator': 'PAYER',
  'billing': {
    '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': {
    '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'
  },
  'notification_url': 'https://example.net/notifications?id=42',
  'metadata': {
    'customer_id': 42,
  },
}
payment = payplug.Payment.create(**payment_data)

Example response:

{
  "amount": 1000,
  "amount_refunded": 0,
  "authorization": null,
  "card": {
    "brand": null,
    "country": null,
    "exp_month": null,
    "exp_year": null,
    "id": "card_e7133426b8de947b37161dfba1897dd1",
    "last4": null
  },
  "created_at": 1449159160,
  "refundable_after": 1449157171,
  "refundable_until": 1459157171,
  "currency": "EUR",
  "billing": {
    "title": "mr",
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "mobile_phone_number": null,
    "landline_phone_number": null,
    "address1": "221B Baker Street",
    "address2": null,
    "postcode": "NW16XE",
    "city": "London",
    "state": null,
    "country": "GB",
    "language": "en"
  },
  "shipping": {
    "title": "mr",
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "mobile_phone_number": null,
    "landline_phone_number": null,
    "address1": "221B Baker Street",
    "address2": null,
    "postcode": "NW16XE",
    "city": "London",
    "state": null,
    "country": "GB",
    "language": "en",
    "delivery_type": "BILLING"
  },
  "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
  },
  "id": "pay_5iHMDxy4ABR4YBVW4UscIn",
  "is_3ds": false,
  "is_live": false,
  "is_paid": true,
  "paid_at": 1555073519,
  "is_refunded": false,
  "installment_plan_id": null,
  "metadata": null,
  "description": null,
  "notification": {
    "response_code": null,
    "url": null
  },
  "object": "payment",
  "save_card": false
}

First, when paying with a Card ID, you must provide the initiator parameter. This will let us know who initiated the payment.

In other words, you have to set initiator to:

• PAYER if your customer has chosen to pay with this saved card at this very moment — such as a one-click payment,
• MERCHANT if the customer is absent when the payment is made — such as an automatic renewal or a subscription.

Also, please note that you have to at least provide the following parameters — since the user won’t be able to type them himself:

• billing.first_name
• billing.last_name
• billing.email

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 a failure is returned in the response object, this means your payment failed,
• otherwise you’ll have a hosted_payment.payment_url where the payer has to be redirected to complete the payment.

Payment notifications

Example:

{
  "id": "pay_5iHMDxy4ABR4YBVW4UscIn",
  "object": "payment",
  "is_live": true
}

PayPlug will send you a notification (if you provided a notification_url at creation time) when a payment fails, is paid, is refunded or when the payment times out 15 minutes after the creation if not paid.

According to the payment state, a notification can be sent shortly or after 15 minutes. Here is a summary of the different possible cases:

Refunds

The refunds object enables you to fully or partially refund a payment that has been paid. Refunds will be applied to the credit card originally used for the payment.

Refunds endpoint reference:

The refund object

Example:

# Print the amount of the refund
print(str(refund.amount))
# Print the refund creation time in an human readable way
print(datetime.datetime.fromtimestamp(refund.created_at).strftime('%d/%m/%Y %H:%M:%S'))

<?php
// Print the amount of the refund
echo htmlentities($refund->amount);
// Print the refund creation time in an human readable way
echo htmlentities(date('d/m/Y H:i:s', $refund->created_at));

{
  "id": "re_3NxGqPfSGMHQgLSZH0Mv3B",
  "payment_id": "pay_5iHMDxy4ABR4YBVW4UscIn",
  "object": "refund",
  "is_live": true,
  "amount": 358,
  "currency": "EUR",
  "created_at": 1434012358,
  "metadata": {
    "customer_id": 42,
    "reason": "The delivery was delayed"
  }
}

Object attributes:

Create a refund

Example:

$ curl -X POST https://api.payplug.com/v1/payments/pay_5iHMDxy4ABR4YBVW4UscIn/refunds \
  -H "Authorization: Bearer sk_test_9898098098guGYUG9" \
  -H "PayPlug-Version: 2019-08-06" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 358,
    "metadata": {
      "customer_id": 42,
      "reason": "The delivery was delayed"
    }
  }'

<?php
// Create a refund from a payment id
$paymentId = 'pay_5iHMDxy4ABR4YBVW4UscIn';
$data = array(
  'amount'   => 358,
  'metadata' => array(
      'customer_id' => 42,
      'reason' => 'The delivery was delayed'
    )
  );
$refund = \Payplug\Refund::create($paymentId, $data);

// Also refund a payment object directly
$payment = \Payplug\Payment::retrieve('pay_5iHMDxy4ABR4YBVW4UscIn');
$data = array('amount' => 358);
$refund = $payment->refund($data);

// Or more simply for a total refund
$payment = \Payplug\Payment::retrieve('pay_5iHMDxy4ABR4YBVW4UscIn');
$refund = $payment->refund();

# Create a refund from a payment id
payment_id = 'pay_5iHMDxy4ABR4YBVW4UscIn'
refund_data = {
  'amount': 358,
  'metadata': {
    'customer_id': 42,
    'reason': 'The delivery was delayed',
  },
}
refund = payplug.Refund.create(payment_id, **refund_data)

# Also refund a payment object directly
payment = payplug.Payment.retrieve('pay_5iHMDxy4ABR4YBVW4UscIn')
refund_data = {'amount': 358}
refund = payment.refund(**refund_data)

# Or even simpler for a total refund
payment = payplug.Payment.retrieve('pay_5iHMDxy4ABR4YBVW4UscIn')
refund = payment.refund()

Example response:

{
  "id": "re_3NxGqPfSGMHQgLSZH0Mv3B",
  "payment_id": "pay_5iHMDxy4ABR4YBVW4UscIn",
  "object": "refund",
  "is_live": true,
  "amount": 358,
  "currency": "EUR",
  "created_at": 1434012358,
  "metadata": {
    "customer_id": 42,
    "reason": "The delivery was delayed"
  }
}

To refund a payment, you can either refund the total amount without setting up any parameters, or partially refund it by providing the amount wanted. The refund will be applied to the credit card originally used for the payment. You can refund a payment several times, as long as the payment has not been fully refunded.

When a payment is entirely refunded, it will impossible to refund it again. If you try to refund a payment already entirely refunded you will get an error message.

Parameters:

Retrieve a refund

Example:

$ curl -X GET https://api.payplug.com/v1/payments/pay_5iHMDxy4ABR4YBVW4UscIn/refunds/re_3NxGqPfSGMHQgLSZH0Mv3B \
  -H "Authorization: Bearer sk_live_9898098098guGYUG9" 
  -H "PayPlug-Version: 2019-08-06"

<?php
// Retrieve a refund object from its id and its payment id
$paymentId  = 'pay_5iHMDxy4ABR4YBVW4UscIn';
$refundId   = 're_3NxGqPfSGMHQgLSZH0Mv3B';
$refund = \Payplug\Refund::retrieve($paymentId, $refundId);

# Retrieve a refund object from its id and its payment id
payment_id = 'pay_5iHMDxy4ABR4YBVW4UscIn'
refund_id = 're_3NxGqPfSGMHQgLSZH0Mv3B'
refund = payplug.Refund.retrieve(payment_id, refund_id)

Example response:

{
  "id": "re_3NxGqPfSGMHQgLSZH0Mv3B",
  "payment_id": "pay_5iHMDxy4ABR4YBVW4UscIn",
  "object": "refund",
  "is_live": true,
  "amount": 358,
  "currency": "EUR",
  "created_at": 1434012358,
  "metadata": {
    "customer_id": 42,
    "reason": "The delivery was delayed"
  }
}

Retrieve details about a refund for a given payment.

URL arguments:

List all refunds

Example:

$ curl -x GET https://api.payplug.com/v1/payments/pay_5iHMDxy4ABR4YBVW4UscIn/refunds \
   -H "Authorization: Bearer sk_live_9898098098guGYUG9" \
   -H "PayPlug-Version: 2019-08-06"

<?php
// Retrieve a list of refunds from the payment id.
$paymentId = 'pay_5iHMDxy4ABR4YBVW4UscIn';
$refunds = \Payplug\Refund::listRefunds($paymentId);
$refund = $refunds[0];

// Retrieve a list of refunds from the payment object.
$payment = \Payplug\Payment::retrieve('pay_5iHMDxy4ABR4YBVW4UscIn');
$refunds = $payment->listRefunds();
$refund = $refunds[0];

# Retrieve a list of refunds from the payment id.
payment_id = 'pay_5iHMDxy4ABR4YBVW4UscIn'
refunds = payplug.Refund.list(payment_id)
refund = refunds.data[0]

# Retrieve a list of refunds from the payment object.
payment = payplug.Payment.retrieve('pay_5iHMDxy4ABR4YBVW4UscIn')
refunds = payment.list_refunds()
refund = refunds.data[0]

# Iterate over each refund of a payment object.
payment = payplug.Payment.retrieve('pay_5iHMDxy4ABR4YBVW4UscIn')
refunds = payment.list_refunds()
for refund in refunds:
    print(str(refund.id))

Example response

{
  "object": "list",
  "page": 0,
  "per_page": 10,
  "has_more": false,
  "data": [{
    "id": "re_3NxGqPfSGMHQgLSZH0Mv3B",
    "payment_id": "pay_5iHMDxy4ABR4YBVW4UscIn",
    "object": "refund",
    "is_live": true,
    "amount": 358,
    "currency": "EUR",
    "created_at": 1434012358,
    "metadata": {
      "customer_id": 42,
      "reason": "The delivery was delayed"
    }
  }]
}

Retrieve a list of all the refund objects for a given payment. All the refunds are returned is a sorted list object (learn more in pagination section).

URL arguments:

Refund notifications

Example:

{
  "id": "re_3NxGqPfSGMHQgLSZH0Mv3B",
  "payment_id": "pay_5iHMDxy4ABR4YBVW4UscIn",
  "object": "refund",
  "is_live": true
}

PayPlug will send you a notification (if you provided a notification_url at payment creation time) when a refund succeeds.

The notification URL used for a payment will be used for notifications about all related refunds.

Installment plans

Use the /installment_plans endpoint to create an installment plan, abort an installment plan or retrieve an installment plan.

Installment plans endpoint reference:

The installment plan object

Example:

{
  "id": "inst_1FTGSRWYHla7eDkfTo2Usd",
  "object": "installment_plan",
  "is_live": true,
  "is_active": true,
  "currency": "EUR",
  "created_at": 1548326773,
  "is_fully_paid": false,
  "billing": {
    "title": "mr",
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "mobile_phone_number": null,
    "landline_phone_number": null,
    "address1": "221B Baker Street",
    "address2": null,
    "postcode": "NW16XE",
    "city": "London",
    "state": null,
    "country": "GB",
    "language": "en"
  },
  "shipping": {
    "title": "mr",
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "mobile_phone_number": null,
    "landline_phone_number": null,
    "address1": "221B Baker Street",
    "address2": null,
    "postcode": "NW16XE",
    "city": "London",
    "state": null,
    "country": "GB",
    "language": "en",
    "delivery_type": "BILLING"
  },
  "hosted_payment": {
    "payment_url": "https://secure.payplug.com/pay/1FTGSRWYHla7eDkfTo2Usd",
    "return_url": "https://example.net/success?id=42",
    "cancel_url": "https://example.net/cancel?id=42"
  },
  "notification": {
    "url": "https://example.net/notifications?id=42"
  },
  "schedule": [
    {
      "date":"2019-01-24",
      "amount": 15000,
      "payment_ids": ["pay_62VazeAbq5ttYietdC2QxR"]
    }, 
    {
      "date":"2019-02-24",
      "amount": 15000,
      "payment_ids": ["pay_12uazeAbq5ttYietdC2QxP"]
    }, 
    {
      "date":"2019-03-24",
      "amount": 10000,
      "payment_ids": []
    },
  ],
  "failure": null,
  "metadata": {
    "customer_id": 42
  }
}