Logo blk

PayPlug API Full Reference

[ PHP ]

Overview

Based on simple REST concepts, the PayPlug API returns JSON objects for your payments, refunds and notifications.

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"
<?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')
using Payplug;
Configuration.SecretKey = "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:

Mode Secret key example
Live sk_live_43b7e007298f57f7aedee32800a52301
Test sk_test_7c5cb3b54abcf5062f056639e809368c

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 ;)

Notifications

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
}
using Payplug;
using Payplug.Exceptions;

string json = new StreamReader(request.InputStream).ReadToEnd();
// This line may depend on your code.
try
{
  var payment = Notification.Treat(json);
  if (payment["object"] == "payment" && payment["is_paid"])
  {
    // Process the paid payment
  }
  else if (payment["object"] == "refund")
  {
    // Process the refund
  }
}
catch (InvalidApiResourceException $e)
{
     // Handle errors
}
{
  "id": "re_3NxGqPfSGMHQgLSZH0Mv3B",
  "payment_id": "pay_5iHMDxy4ABR4YBVW4UscIn",
  "object": "refund",
  "is_live": true,
  "amount": 358,
  "currency": "EUR",
  "created_at": 1434012358,
  "metadata": {
    "customer_id": 42710,
    "reason": "The delivery was delayed"
  }
}

You can configure a callout notification to be sent to your application when creating a payment. You will get a notification when the payment fails, is paid, is refunded or when the payment times out 15 minutes after the creation if not paid.

When you create a payment, specify the notification_url parameter. Once the payment has been created, notifications about this payment will be sent through a POST request to the provided url.

For a refund request, you will get a refund object on the notification_url specified when you created the payment.

Notification period

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

Case Period Error code  Error message
The payment was paid Shortly  -   
The payment attempt failed 15 min Last attempt error code  Last attempt error message.
The payment was not paid and then it was cancelled by the customer Never  canceled The payment was canceled by the customer.
The payment was not paid and then it was aborted by the API Never aborted You have aborted the transaction.
The payment has not been paid 15 min timeout The customer has not tried to pay and left the payment page.
The payment was cancelled after several attempts 15 min Last attempt error code  Last attempt error message.
The payment was not paid after several attempts 15 min Last attempt error code  Last attempt error message.
The payment was paid after several failed attempts Shortly  -   

Pagination

Example:

$ curl -X GET https://api.payplug.com/v1/payments?page=1&per_page=5 \
  -H "Authorization: Bearer sk_live_43b7e007298f57f732800a52"
<?php
$perPage = 5;
$page = 1;
$payments = \Payplug\Payment::listPayments($perPage, $page);
per_page = 5
page = 1
payments = payplug.Payment.list(per_page, page)
uint perPage = 5;
uint page = 1;
var payments = Payment.List(perPage, 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:

Key Description
per_page Number of objects to be listed in the request.
page Page of results to be used in the request.

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:

Key Description
page integer List page do display (Default is: 0)
per_page integer Maximum number of objects listed in data
has_more boolean Whether there are more elements or not after this page
data JSON object List of requested objects

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 up to 10 keys, keys names have a maximum length of 20 characters, and each data field have a maximum of 500 characters.

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:

Key Description
transaction_id string Id of the customer transaction related to the payment.
customer_id integer Id of the customer.
product_id string Id of the product bought by the customer.
shipping string Information about the shipping (shipping rates, delivery options, details…).

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).

Key Description
message string A short description of the cause of the error.
id string Error ID.
details string   For a 400 error, this additional field is added, so that you can easily know what are the wrong or missing parameters you sent.

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.

Code Description
200 OK – The request has succeeded as expected. The result of the request is available in the response.
201 Created – The request has been executed and a new resource has been created.
400 Bad Request – The request could not be executed due to wrong or missing parameter. The response will contain more information.
401 Unauthorized – The request requires authentication and has been refused for the provided API key.
403 Forbidden error – The request has succeed, but the access to this ressource is forbidden.
404 Resource not found – The requested resource could be found.
405 Method not allowed – The request used a method not supported by this resource.
50x Server errors – The API is currently unable to handle the request due to an unexpected temporary condition. You can try to resend the request after a couple of minutes.

Payment failure codes

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

Types Description
processing_error Error while processing the card.
card_declined The card has been rejected.
insufficient_funds Insufficient funds to cover the payment.
3ds_declined The 3-D secure code has been rejected.
incorrect_number The card number is incorrect.
fraud_suspected Payment rejected because a fraud has been detected.
aborted Payment has been aborted with the Abort a payment feature.
timeout The customer has not tried to pay and left the payment page.

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:

Test cards numbers Expected
4242 4242 4242 4242 Visa Success
5500 0055 5555 5559 MasterCard Success
4000 0000 0000 0051 Visa Failure code: card_declined
4000 0000 0000 0085 Visa Failure code: processing_error
4000 0000 0000 0077 Visa Failure code: insufficient_funds
5184 6800 0000 0170 MasterCard Failure code: ds_declined
5184 6800 0000 0097 MasterCard Failure code: incorrect_number
5184 6800 0000 0121 MasterCard Failure code: fraud_suspected

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).

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:

Method  Endpoint  Usage
POST /v1/payments Create a payment
GET /v1/payments/{payment_id} Retrieve a payment
PATCH /v1/payments/{payment_id} Abort a payment
PATCH /v1/payments/{payment_id} Update a payment
GET /v1/payments List all payments

The payment object

Example:

{
  "id": "pay_5iHMDxy4ABR4YBVW4UscIn",
  "object": "payment",
  "is_live": true,
  "amount": 3300,
  "amount_refunded": 0,
  "currency": "EUR",
  "created_at": 1434010787,
  "is_paid": true,
  "is_refunded": false,
  "is_3ds": false,
  "save_card": false,
  "card": {
    "last4": "1800",
    "country": "FR",
    "exp_month": 9,
    "exp_year": 2017,
    "brand": "Mastercard",
    "id": null
  },
  "customer": {
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "address1": null,
    "address2": null,
    "postcode": null,
    "city": null,
    "country": null
  },
  "hosted_payment": {
    "payment_url": "https://www.payplug.com/pay/5iHMDxy4ABR4YBVW4UscIn",
    "return_url": "https://example.net/success?id=42",
    "cancel_url": "https://example.net/cancel?id=42",
    "paid_at": 1434010827
  },
  "notification": {
    "url": "https://example.net/notifications?id=42",
    "response_code": 200
  },
  "failure": null,
  "metadata": {
    "customer_id": 42
  }
}
<?php
// Get an attribute of the payment object:
// Print the payment amount
echo $payment->amount;
// Print the payment id
echo $payment->id;
// Print the payment creation time in an human readable way
echo date('d/m/Y H:i:s', $payment->created_at);

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

// Retrieve metadata
echo $payment->metadata['customer_id'];
echo $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'])
// Get an attribute of the payment object:
// Print the payment amount
Console.WriteLine(payment["amount"]);
// Print the payment id
Console.WriteLine(payment["id"]);

// Print the payment creation time in an human readable way
Console.WriteLine(DateTimeOffset.FromUnixTimeSeconds(payment["created_at"]).DateTime);

// Chain relations between objects:
// Print the payment URL
Console.WriteLine(payment["hosted_payment"]["payment_url"]);
// Print the customer email
Console.WriteLine(payment["customer"]["email"]);

// Retrieve metadata
Console.WriteLine(payment["metadata"]["customer_id"]);
Console.WriteLine(payment["metadata"]["type"]);

Object attributes:

Key Description
id string Payment ID.
object string Default value is: payment.
is_live boolean true for a payment in LIVE mode, false in TEST mode.
amount positive integer Amount of the payment in cents.
amount_refunded positive integer or zero Amount that has been refunded in cents.
currency currency Currency code (three-letter ISO 4217) in which the payment was made.
is_paid boolean true if the payment has been paid, false if not.
is_refunded boolean true if this payment has been fully refunded, false if not.
is_3ds boolean or null true if the payment was processed using 3-D Secure.
save_card boolean true if the payment was used to save a card. On the payment page, saving a card was mendatory.
allow_save_card boolean Alternative to save_card. true if the payment gave the possibility to a customer to save a card. On the payment page, saving a card was optional.
created_at timestamp Creation date.
card JSON object Information about the card used for the payment.
  last4: Last 4 digits of the card number. string
  country: Country code (two-letter ISO 3166). string
  exp_year: Credit card expiration year. integer
  exp_month: Credit card expiration month. integer
  brand: Credit card brand, can be Mastercard or Visa. string
  id: Credit card ID, available when a payment has been created with save_card=true, or has been created with this id.string
customer JSON object Information about the customer.
  email: Customer email address. string
  first_name: Customer first name. string
  last_name: Customer last name. string
  address1: Customer address line 1 (Street address/PO Box/Company name). string
  address2: Customer address line 2 (Apartment/Suite/Unit/Building). string
  postcode: Customer Zip/Postal code. string
  city: Customer city. string
  country: Customer country code (two-letter ISO 3166). string
hosted_payment JSON object Information about the payment.
  payment_url: Url of the page where the customer will be redirected after the payment. string
  return_url: Url where the customer will be redirected after the payment page whether it succeeds or not. string
  cancel_url: Url where the customer will redirected after they click on “Cancel Payment”. string
  paid_at: Date at which the payment goes through. null if the payment has not been not paid yet or has failed. timestamp
notification JSON object Notifications when the payment succeeds, fails or is refunded.
  url: Url to which PayPlug will send payment notifications. string
  response_code: Integer http response code received when calling the url of your notification page. integer
failure JSON object or null Returns information for unsuccessful payments.
  code: Payment failure code if the payment has failed. string
  message: Descriptive message explaining the reason of the payment failure. string
metadata JSON object Custom metadata object added when creating the payment.

Create a payment

Example:

$ curl -X POST https://api.payplug.com/v1/payments \
  -H "Authorization: Bearer sk_test_9898098098guGYUG9" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 3300,
    "currency": "EUR",
    "customer":{
      "email": "john.watson@example.net",
      "first_name": "John",
      "last_name": "Watson"
    }, 
    "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,
  'customer'         => array(
    'email'          => 'john.watson@example.net',
    'first_name'     => 'John',
    'last_name'      => 'Watson'
  ),
  '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_data = {
  'amount': 3300,
  'currency': 'EUR',
  'save_card': False,
  'customer': {
    'email': 'john.watson@example.net',
    'first_name': 'John',
    'last_name': 'Watson',
  },
  '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)
var paymentData = new Dictionary<string, dynamic>
{
  {"amount", 3300},
  {"currency", "EUR"},
  {"customer", new Dictionary<string, object>
    {
      {"email", "john.watson@example.net"},
      {"first_name", "John"},
      {"last_name", "Watson"}
    }
  },
  {"hosted_payment", new Dictionary<string, object>
    {
      {"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", new Dictionary<string, object>
    {
      {"customer_id", "42"}
    }
  },
  {"save_card", false},
  {"force_3ds", true}
};
var payment = Payment.Create(paymentData);

Example response:

{
  "amount": 3300,
  "amount_refunded": 0,
  "card": {
    "brand": null,
    "country": null,
    "exp_month": null,
    "exp_year": null,
    "id": null,
    "last4": null
  },
  "created_at": 1449157171,
  "currency": "EUR",
  "customer": {
    "address1": null,
    "address2": null,
    "city": null,
    "country": null,
    "email": "john.watson@example.net",
    "first_name": "John",
    "last_name": "Watson",
    "postcode": null
  },
  "failure": null,
  "hosted_payment": {
    "cancel_url": "https://example.net/cancel?id=42",
    "paid_at": null,
    "payment_url": "https://www.payplug.com/pay/test/2DNkjF024bcLFhTn7OBfcc",
    "return_url": "https://example.net/success?id=42"
  },
  "id": "pay_2DNkjF024bcLFhTn7OBfcc",
  "is_3ds": null,
  "is_live": false,
  "is_paid": false,
  "is_refunded": false,
  "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.

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.

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:

Key Description
amount positive integer required Amount in cents, for instance use 4207 for a 42.07€ payment. Currently, the minimum and maximum amounts are 100 and 2,000,000 cents.
currency currency required Currency code (three-letter ISO 4217). For now, Euro is the only currency supported (value: EUR).
customer JSON object optional All customer attributes are optional. First name, last name and email will be asked on the payment page if you do not provide them.
   first_name: Customer first name (maximum length: 100 characters). string optional (required if payment_method is not null).
  last_name: Customer last name (maximum length: 100 characters). string optional (required if payment_method is not null).
   email: Customer email address (maximum length: 255 characters). email optional (required if payment_method is not null).
  address1: Customer address line 1 (maximum length: 255 characters). string optional
  address2: Customer address line 2 (maximum length: 255 characters). string optional
  postcode: Customer Zip/Postal code (maximum length: 16 characters). string optional
  city: Customer city (maximum length: 100 characters). string optional
  country: Customer country two-letter ISO 3166 code code optional
hosted_payment JSON Object optional  All urls must start with "http://" or "https://" and must be accessible from anywhere on the Internet (which is not the case with local environments).
  return_url: Url where the customer will be redirected after the payment page whether it succeeds or not. string optional
   cancel_url: Url where the customer will redirected after they click on “Cancel Payment”. string optional
notification_url string optional Url to which PayPlug will send notifications, when the payment succeeds, fails or is refunded.
payment_method string optional The Card ID of a saved card, or a Token generated by PayPlug.js. If provided, hosted_payment must be NULL.
force_3ds boolean optional If true 3-D Secure will be activated for the payment, else, PayPlug will decide whether it should be activated or not based on default configuration.
save_card boolean optional If true, card information will be saved, and a card ID will be returned once the payment has been done. You must provide a customer when this is set to true.
allow_save_card boolean optional Alternative to save_card. If true, the customer will be able to save its card by checking a box on the payment page. A card ID will be returned once the payment has been done. You must provide a customer when this is set to true.
metadata JSON object optional Custom metadata object.

Retrieve a payment

Example:

$ curl -X GET https://api.payplug.com/v1/payments/pay_5iHMDxy4ABR4YBVW4UscIn \
  -H "Authorization: Bearer sk_test_9898098098guGYUG9"
<?php
$payment = \Payplug\Payment::retrieve('pay_5iHMDxy4ABR4YBVW4UscIn');
payment = payplug.Payment.retrieve('pay_5iHMDxy4ABR4YBVW4UscIn')
var payment = Payment.Retrieve("pay_5iHMDxy4ABR4YBVW4UscIn");

Example response:

{
  "id": "pay_5iHMDxy4ABR4YBVW4UscIn",
  "object": "payment",
  "is_live": true,
  "amount": 3300,
  "amount_refunded": 0,
  "currency": "EUR",
  "created_at": 1434010787,
  "is_paid": true,
  "is_refunded": false,
  "is_3ds": false,
  "save_card": false,
  "card": {
    "last4": "1800",
    "country": "FR",
    "exp_month": 9,
    "exp_year": 2017,
    "brand": "Mastercard",
    "id": null
  },
  "customer": {
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "address1": null,
    "address2": null,
    "postcode": null,
    "city": null,
    "country": null
  },
  "hosted_payment": {
    "payment_url": "https://www.payplug.com/pay/5iHMDxy4ABR4YBVW4UscIn",
    "return_url": "https://example.net/success?id=42",
    "cancel_url": "https://example.net/cancel?id=42",
    "paid_at": 1434010827
  },
  "notification": {
    "url": "https://example.net/notifications?id=42",
    "response_code": 200
  },
  "failure": 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:

Key Description
payment_id ID of the payment to be retrieved.

Update a payment

Example :

$ curl -X PATCH https://api.payplug.com/v1/payments/pay_5iHMDxy4ABR4YBVW4UscIn \
  -H "Authorization: Bearer sk_test_9898098098guGYUG9" \
  -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
// Currently not available in Python library

Example response:

{
  "amount": 3300,
  "amount_refunded": 0,
  "card": {
    "brand": null,
    "country": null,
    "exp_month": null,
    "exp_year": null,
    "id": null,
    "last4": null
  },
  "created_at": 1449157475,
  "currency": "EUR",
  "customer": {
    "address1": null,
    "address2": null,
    "city": null,
    "country": null,
    "email": "john.watson@example.net",
    "first_name": "John",
    "last_name": "Watson",
    "postcode": null
  },
  "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://www.payplug.com/pay/test/5iHMDxy4ABR4YBVW4UscIn",
    "return_url": "https://example.net/success?id=42"
  },
  "id": "pay_5iHMDxy4ABR4YBVW4UscIn",
  "is_3ds": null,
  "is_live": false,
  "is_paid": false,
  "is_refunded": false,
  "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 informations you have defined.

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

Parameters:

Key Description
metadata JSON object optional Custom metadata object added to the request the object.

Abort a payment

Example:

$ curl -X PATCH https://api.payplug.com/v1/payments/pay_5iHMDxy4ABR4YBVW4UscIn \
  -H "Authorization: Bearer sk_test_9898098098guGYUG9" \
  -H "Content-Type: application/json" \
  -d '{"abort": 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()
var payment = Payment.Abort("pay_5iHMDxy4ABR4YBVW4UscIn");

Example response:

{
  "amount": 3300,
  "amount_refunded": 0,
  "card": {
    "brand": null,
    "country": null,
    "exp_month": null,
    "exp_year": null,
    "id": null,
    "last4": null
  },
  "created_at": 1449157475,
  "currency": "EUR",
  "customer": {
    "address1": null,
    "address2": null,
    "city": null,
    "country": null,
    "email": "john.watson@example.net",
    "first_name": "John",
    "last_name": "Watson",
    "postcode": null
  },
  "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://www.payplug.com/pay/test/5iHMDxy4ABR4YBVW4UscIn",
    "return_url": "https://example.net/success?id=42"
  },
  "id": "pay_5iHMDxy4ABR4YBVW4UscIn",
  "is_3ds": null,
  "is_live": false,
  "is_paid": false,
  "is_refunded": false,
  "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 a payment object if the ID provided is valid, and it will respond an error object otherwise.

URL arguments:

Key Description
payment_id ID of the payment to be aborted.

Parameters:

Key Description
abort boolean required This parameter must be true.

List all payments

Example:

$ curl -X GET https://api.payplug.com/v1/payments \
  -H "Authorization: Bearer sk_test_9898098098guGYUG9"
<?php
$payments = \Payplug\Payment::listPayments();
$payment = $payments[0];
payments = payplug.Payment.list()
payment = next(payments)
var payments = Payment.List();
var payment = payments["data"][0];

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 "Content-Type: application/json" \
  -d '{
    "amount": 3300,
    "currency": "EUR",
    "save_card": true,
    "customer":{
      "email": "john.watson@example.net",
      "first_name": "John",
      "last_name": "Watson"
    }, 
    "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,
  'customer'         => array(
    'email'          => 'john.watson@example.net',
    'first_name'     => 'John',
    'last_name'      => 'Watson'
  ),
  '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,
  'customer': {
    'email': 'john.watson@example.net',
    'first_name': 'John',
    'last_name': 'Watson',
  },
  '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)
var paymentData = new Dictionary<string, dynamic>
{
  {"amount", 3300},
  {"currency", "EUR"},
  {"customer", new Dictionary<string, object>
    {
      {"email", "john.watson@example.net"},
      {"first_name", "John"},
      {"last_name", "Watson"}
    }
  },
  {"hosted_payment", new Dictionary<string, object>
    {
      {"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", new Dictionary<string, object>
    {
      {"customer_id", "42"}
    }
  },
  {"save_card", true},
  {"force_3ds", true}
};
var payment = Payment.Create(paymentData);

Example object once the payment is completed:

{
  "id": "pay_5iHMDxy4ABR4YBVW4UscIn",
  "object": "payment",
  "is_live": true,
  "amount": 3300,
  "amount_refunded": 0,
  "currency": "EUR",
  "created_at": 1434010787,
  "is_paid": true,
  "is_refunded": false,
  "is_3ds": true,
  "save_card": true,
  "card": {
    "last4": "1800",
    "country": "FR",
    "exp_month": 9,
    "exp_year": 2017,
    "brand": "Mastercard",
    "id": "card_e7133426b8de947b37161dfba1897dd1"
  },
  "customer": {
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "address1": null,
    "address2": null,
    "postcode": null,
    "city": null,
    "country": null
  },
  "hosted_payment": {
    "payment_url": "https://www.payplug.com/pay/5iHMDxy4ABR4YBVW4UscIn",
    "return_url": "https://example.net/success?id=42",
    "cancel_url": "https://example.net/cancel?id=42",
    "paid_at": 1434010827
  },
  "notification": {
    "url": "https://example.net/notifications?id=42",
    "response_code": 200
  },
  "failure": null,
  "metadata": {
    "customer_id": 42
  }
}

Create a payment with the card ID:

$ curl -X POST https://api.payplug.com/v1/payments \
  -H "Authorization: Bearer sk_test_9898098098guGYUG9" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "EUR",
    "payment_method": "card_e7133426b8de947b37161dfba1897dd1",
    "customer": {
      "email": "john.watson@example.net",
      "first_name": "John",
      "last_name": "Watson"
    }
  }'
<?php
$payment = \Payplug\Payment::create(array(
  'amount'           => 1000,
  'currency'         => 'EUR',
  'payment_method'   => 'card_e7133426b8de947b37161dfba1897dd1',
  'customer'         => array(
    'email'          => 'john.watson@example.net',
    'first_name'     => 'John',
    'last_name'      => 'Watson'
  ),
  'notification_url' => 'https://example.net/notifications?id=42',
  'metadata'         => array(
    'customer_id'    => 42
));
payment_data = {
  'amount': 1000,
  'currency': 'EUR',
  'payment_method': 'card_e7133426b8de947b37161dfba1897dd1',
  'customer': {
    'email': 'john.watson@example.net',
    'first_name': 'John',
    'last_name': 'Watson',
  },
  'notification_url': 'https://example.net/notifications?id=42',
  'metadata': {
    'customer_id': 42,
  },
}
payment = payplug.Payment.create(**payment_data)
var paymentData = new Dictionary<string, dynamic>
{
  {"amount", 1000},
  {"currency", "EUR"},
  {"payment_method", "card_e7133426b8de947b37161dfba1897dd1"},
  {"customer", new Dictionary<string, object>
    {
      {"email", "john.watson@example.net"},
      {"first_name", "John"},
      {"last_name", "Watson"}
    }
  },
  {"notification_url", "https://example.net/notifications?id=42"},
  {"metadata", new Dictionary<string, object>
    {
      {"customer_id", "42"}
    }
  }
};
var payment = Payment.Create(paymentData);

Example response:

{
  "amount": 1000,
  "amount_refunded": 0,
  "card": {
    "brand": null,
    "country": null,
    "exp_month": null,
    "exp_year": null,
    "id": "card_e7133426b8de947b37161dfba1897dd1",
    "last4": null
  },
  "created_at": 1449159160,
  "currency": "EUR",
  "customer": {
    "address1": null,
    "address2": null,
    "city": null,
    "country": null,
    "email": "john.watson@example.net",
    "first_name": "John",
    "last_name": "Watson",
    "postcode": null
  },
  "failure": null,
  "hosted_payment": null,
  "id": "pay_5iHMDxy4ABR4YBVW4UscIn",
  "is_3ds": false,
  "is_live": false,
  "is_paid": true,
  "is_refunded": false,
  "metadata": null,
  "notification": {
    "response_code": null,
    "url": null
  },
  "object": "payment",
  "save_card": false
}

Save a card in order to create a payment later, using the same card, without using a payment page.

Saving a card is very simple, 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). The card ID will be functional for 15 months maximum.

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

With save_card key, the customer is forced to save the card to process the payment. On the payment page the box is checked by default and the customer will not be able to validate the payment if he tries to uncheck the box.

Alternatively with allow_save_card key, saving the card is optional to process the payment. On the payment page the customer will be able to choose to save or not the card by checking the box.

save_card and allow_save_card are not supposed to be used at the same time.

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:

Method  Endpoint  Usage
POST /v1/payments/{payment_id}/refunds Create a refund
GET /v1/payments/{payment_id}/refunds/{refund_id} Retrieve a refund
POST /v1/payments/{payment_id}/refunds List all refunds

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 $refund->amount;
// Print the refund creation time in an human readable way
echo date('d/m/Y H:i:s', $refund->created_at);
// Print the amount of the refund
Console.WriteLine(refund["amount"]);
// Print the refund creation time in an human readable way
Console.WriteLine(DateTimeOffset.FromUnixTimeSeconds(refund["created_at"]).DateTime);
{ "amount": 358,
  "created_at": 1434012358,
  "currency": "EUR",
  "id": "re_3NxGqPfSGMHQgLSZH0Mv3B",
  "is_live": true,
  "metadata": { 
    "customer_id": 42,
    "reason": "The delivery was delayed"
  },
  "object": "refund",
  "payment_id": "pay_5iHMDxy4ABR4YBVW4UscIn"
}

Object attributes:

Key Description
id string Refund ID
payment_id string ID of the payment refunded.
object string Default value is: refund.
is_live boolean true for a payment in LIVE mode, false in TEST mode.
amount positive integer Amount of the refund in cents and must be highier than 0.10€ (10 cents).
currency currency Currency code three-letter ISO 4217 in which the refund was made.
created_at timestamp Date of creation of the refund.
metadata JSON object Custom metadata object added to the request the object.

Create a refund

Example:

$ curl -X POST https://api.payplug.com/v1/payments/pay_5iHMDxy4ABR4YBVW4UscIn/refunds \
  -H "Authorization: Bearer sk_test_9898098098guGYUG9" \
  -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()
// Create a refund from a payment id
var paymentId = "pay_5iHMDxy4ABR4YBVW4UscIn";
var refundData = new Dictionary<string, dynamic>
{
  {"amount", 3300},
  {"metadata", new Dictionary<string, dynamic>
    {    
      {"customer_id", 42},
      {"reason", "The delivery was delayed"}
    }
  }
};
var refund = Refund.Create(paymentId, refundData);

// Or even simpler for a total refund
var refund = Refund.Create(paymentId);

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:

Key Description
amount positive integer optional Amount in cents, for instance use 308 for a 3.08€ refund. If not provided the payment will be fully refunded.
metadata JSON object optional Custom metadata object added to the request the object.

Retrieve a refund

Example:

$ curl -X GET https://api.payplug.com/v1/payments/pay_5iHMDxy4ABR4YBVW4UscIn/refunds/re_3NxGqPfSGMHQgLSZH0Mv3B \
  -H "Authorization: Bearer sk_live_9898098098guGYUG9" 
<?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)
// Retrieve a refund object from its id and its payment id
var paymentId = "pay_5iHMDxy4ABR4YBVW4UscIn";
var refundId = "re_3NxGqPfSGMHQgLSZH0Mv3B";
var refund = Refund.Retrieve(paymentId, refundId);

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:

Key Description
payment_id ID of the payment to be retrieved.
refund_id ID of the refund to be retrieved.

List all refunds

Example:

$ curl -x GET https://api.payplug.com/v1/payments/pay_5iHMDxy4ABR4YBVW4UscIn/refunds \
   -H "Authorization: Bearer sk_live_9898098098guGYUG9" 
<?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))
// Retrieve a list of refunds from the payment id.
var paymentId = "pay_5iHMDxy4ABR4YBVW4UscIn";
var refunds = Refund.List(paymentId);
var refund = refunds["data"][0];

// Iterate over each refund of a payment object.
var refunds = Refund.List("pay_5iHMDxy4ABR4YBVW4UscIn");
foreach (var refund in refunds["data"])
{
    Console.WriteLine(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:

Key Description
payment_id ID of the payment to be retrieved.