NAV Navbar
Logo
PHP Python cURL

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:

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

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:

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:

Key Description
id string The object resource unique identifier (e.g. a payment ID).
object string The object type (e.g. payment).
is_live boolean true for an object created in LIVE mode, false in TEST mode.

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:

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

Specific documentation for 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:

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 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:

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.
202 Accepted – The request has been received, but requires longer processing.
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.
409 Conflict – The request could not be executed due to a conflict with a previous one.
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 3D Secure authentication request has failed.
incorrect_number The card number is incorrect.
fraud_suspected Payment rejected because a fraud has been detected.
method_unsupported The payment method is not supported (e.g. e-carte bleue).
card_scheme_mismatch The card number does not match with the selected brand.
card_expiration_date_prior_to_last_installment_date The card expiration date is prior to the last installment date.
aborted Payment has been aborted with the Abort a payment feature.
timeout The customer has not tried to pay and left the payment page.

Installment plan failure codes

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

Types Description
failed_payment A payment has failed.
aborted Installment plan has been aborted with the Abort an installment plan feature.

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
5017 6700 0000 1800 MasterCard Success
3720 6839 7730 000 American Express Success
3787 0081 0990 001 American Express 3DS Success
4000 0000 0000 0051 Visa Failure code: card_declined
3759 5640 4454 001 American Express Failure code: card_declined
4000 0000 0000 0085 Visa Failure code: processing_error
3734 0644 9535 002 American Express 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
3762 4078 3094 012 American Express 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).

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:

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} Capture 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,
  "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:

Key Description
id string Payment ID.
object string 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.
authorization JSON object Information about the authorization in case of a deferred payment, null otherwise.
  authorized_amount: The amount that was authorized. positive integer
  authorized_at: Date at which the payment was authorized by the customer, null if the payment has not yet been authorized. timestamp
  expires_at: Date at which the authorization expires, null if the payment has not yet been authorized. timestamp
currency currency Currency code (three-letter ISO 4217) in which the payment was made.
installment_plan_id string ID of the installment plan related to this payment, if any.
integration string Must be set to ‘INTEGRATED_PAYMENT’ if you use IntegratedPayment.
is_paid boolean true if the payment has been paid, false if not.
paid_at timestamp Date at which the payment has been paid, null if the payment has not yet been paid.
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 mandatory.
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.
refundable_after timestamp Date after which the payment can be refunded, null if the payment has not yet been paid.
refundable_until timestamp Date until which the payment can be refunded, null if the payment has not yet been paid.
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, Maestro, Visa or CB. string
  id: Credit card ID, available when a payment has been created with save_card=true, or has been created with this id. string
billing JSON object Information about billing.
  title: Customer title, can be mr, mrs, miss, null string
  first_name: Customer first name. string
  last_name: Customer last name. string
  email: Customer email address. string
  mobile_phone_number: Customer mobile phone number (international format in the E.164 standard). string
  landline_phone_number: Customer landline phone number (international format in the E.164 standard). string
  address1: Customer address line 1 (Street address/PO Box/Company name). string
  address2: Customer address line 2 (Apartment/Suite/Unit/Building). string
  company_name: Customer company. string
  postcode: Customer Zip/Postal code. string
  city: Customer city. string
  state: Customer state. string
  country: Customer country code (two-letter ISO 3166). string
  language: Customer language code (two-letter ISO 639-1). string
shipping JSON object Information about shipping.
  title: Recipient title, can be mr, mrs, miss, null string
  first_name: Recipient first name. string
  last_name: Recipient last name. string
  email: Recipient email address. string
  mobile_phone_number: Mobile phone number (international format in the E.164 standard). string
  landline_phone_number: Landline phone number (international format in the E.164 standard). string
  address1: Shipping address line 1 (Street address/PO Box/Company name). string
  address2: Shipping address line 2 (Apartment/Suite/Unit/Building). string
  company_name: Customer company. string
  postcode: Shipping Zip/Postal code. string
  city: Shipping city. string
  state: Shipping state. string
  country: Shipping country code (two-letter ISO 3166). string
  language: Shipping language code (two-letter ISO 639-1). string
  delivery_type: Type of delivery (any of: BILLING VERIFIED NEW SHIP_TO_STORE DIGITAL_GOODS TRAVEL_OR_EVENT OTHER). See delivery type.
hosted_payment JSON object Information about the payment.
  payment_url: The payment URL you should redirect your customer to. string
  return_url: The URL the customer will be redirected to after the payment page whether it succeeds or not. string
  cancel_url: The URL the customer will redirected to after a click on ‘Cancel Payment’. string
  paid_at: Date at which the payment goes through. null if the payment has yet to be paid or has failed. timestamp deprecated
  sent_by: By what means the payment URL was sent to the customer, if any. string
notification JSON object Data related to notifications.
  url: The URL PayPlug will send notifications to. string
  response_code: Integer http response code received when calling the URL of your notification page. integer
failure JSON object or null 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
description string optional Description shown to the customer.
metadata JSON object Custom metadata object added when creating the payment.
payment_method JSON object *only for Oney and some other payment methods Data about the payment method, only available for Oney payments or other Payment Methods.
  type: the type of payment made, one of: oney_x3_with_fees, oney_x4_with_fees, oney_x3_without_fees, oney_x4_without_fees, american_express, bancontact, giropay, ideal, mybank, satispay, sofort. string
  is_pending: whether the payment is in a pending state for Oney. If this is true, it means that the payer has successfully filled out Oney’s payment form, but Oney is still analyzing the payer’s file. In this case, the payment is neither authorized nor paid yet, but in a pending state. If a notification_url is set, then the payment resource will be posted to it once Oney has made its decision. See Interpreting an Oney payment status. string

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:

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:

Key Description
amount positive integer Amount in cents, for instance use 4207 for a 42.07€ payment. Currently, the minimum and maximum amounts are 99 and 2,000,000 cents. Can be different for alternative Payment Methods
authorized_amount positive integer In order to create a deferred payment, use this field for the payment’s amount instead of amount.
auto_capture boolean In case of a deferred payment, automatically capture the payment after it has been authorized.
currency currency required Currency code (three-letter ISO 4217). For now, Euro is the only currency supported (value: EUR).
billing JSON object required Billing information – recommended fields are optional but help increase your chances of frictionless payments. The billing object is still required, even if empty.
  title: Customer title, can be mr, mrs, miss, null string optional
  first_name: Customer first name (maximum length: 100 characters). string recommended
  last_name: Customer last name (maximum length: 100 characters). string recommended
  email: Customer email address (maximum length: 255 characters). email recommended
  mobile_phone_number: Customer mobile phone number (international format in the E.164 standard). phone number recommended (required if hosted_payment.sent_by is SMS).
  landline_phone_number: Customer landline phone number (international format in the E.164 standard). phone number recommended.
  address1: Customer address line 1 (maximum length: 255 characters). string recommended
  address2: Customer address line 2 (maximum length: 255 characters). string optional
  company_name: Customer company. string recommended
  postcode: Customer Zip/Postal code (maximum length: 16 characters). string recommended
  city: Customer city (maximum length: 100 characters). string recommended
  state: Customer state (maximum length: 100 characters). string optional
  country: Customer country two-letter ISO 3166 code code recommended
  language: Customer language two-letter ISO 639-1 code code recommended. Supported languages: fr, en and it.
shipping JSON object required Shipping information – recommended fields are optional but help increase your chances of frictionless payments. The shipping object is still required, even if empty.
  title: Recipient title, can be mr, mrs, miss, null string optional
  first_name: Recipient first name (maximum length: 100 characters). string recommended
  last_name: Recipient last name (maximum length: 100 characters). string recommended
  email: Recipient email address (maximum length: 255 characters). email recommended
  mobile_phone_number: Recipient mobile phone number (international format in the E.164 standard). phone number recommended.
  landline_phone_number: Recipient landline phone number (international format in the E.164 standard). phone number recommended.
  address1: Shipping address line 1 (maximum length: 255 characters). string recommended
  address2: Shipping address line 2 (maximum length: 255 characters). string optional
  company_name: Customer company. string recommended
  postcode: Shipping Zip/Postal code (maximum length: 16 characters). string recommended
  city: Shipping city (maximum length: 100 characters). string recommended
  state: Shipping state (maximum length: 100 characters). string optional
  country: Shipping country two-letter ISO 3166 code code recommended
  language: Shipping language two-letter ISO 639-1 code code recommended. Supported languages: fr, en and it.
  delivery_type: Type of delivery (any of: BILLING VERIFIED NEW SHIP_TO_STORE DIGITAL_GOODS TRAVEL_OR_EVENT OTHER). optional. See delivery type.
payment_context JSON object optional Payment context information, currently only required for Oney payments
  cart JSON object required Items in the payer’s cart
  brand: Item’s brand. string required
  expected_delivery_date: Expected delivery date in YYYY-MM-DD format. string required
  delivery_label: Delivery label. string required
  delivery_type: Delivery type (any of: storepickup, networkpickup, travelpickup, carrier, edelivery). string required
  merchant_item_id: ID uniquely identifying this item in the cart. string required
  name: Item’s name. string required
  price: Unit price of the item in cents. positive integer required
  quantity: Number of articles for the given item. positive integer required
  total_amount: Total amount for this item in cents. positive integer required
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: The URL the customer will be redirected to after the payment page whether it succeeds or not. string optional
  cancel_url: The URL the customer will redirected to after a click on ‘Cancel Payment’. string optional
  sent_by: To send a message to customer with payment URL, which will not expire. Supported values: EMAIL, SMS, and OTHER. The payment request is sent to the billing-related phone number and also works on international numbers. string optional
notification_url string optional The URL PayPlug will send notifications to.
payment_method string optional The Card ID of a saved card, or a specific payment method: oney_x3_with_fees, oney_x4_with_fees, oney_x3_without_fees, or oney_x4_without_fees for Oney payments, american_express, bancontact, giropay, ideal, mybank, satispay, sofort for other Payment Methods.
initiator string optional Indicates who initiated the payment (values: PAYER, MERCHANT). Only required if a Card ID is provided. Read more at Pay with a saved card.
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.
description string optional Description shown to the customer (maximum length: 80 characters).
metadata JSON object optional Custom metadata object.

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:

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:

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 '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:

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

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:

Key Description
payment_id ID of the payment to be captured.

Parameters:

Key Description
captured boolean required This parameter must be true.

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:

Key Description
payment_id ID of the payment to be aborted.

Parameters:

Key Description
aborted 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' \
  -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:

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

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

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:

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  -   
Oney has accepted a payment that was pending Shortly - A few days -  
Oney has refused a payment that was pending Shortly - A few days Last attempt error code Oney refused the customer’s file.

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
GET /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 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:

Key Description
id string Refund ID
payment_id string ID of the payment refunded.
object string 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 "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:

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" 
  -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:

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" \
   -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:

Key Description
payment_id ID of the payment to be retrieved.

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.

Cards & Subscriptions

Save a card

You can save a card as part of collecting a payment. To save a card, read save a card.

Delete a card

$ curl -X DELETE https://api.payplug.com/v1/cards/card_kFVrvXm2kYlZVmgk2sk1m9 \
  -H "Authorization: Bearer sk_test_9898098098guGYUG9" \
  -H "Content-Type: application/json" \
  -H "PayPlug-Version: 2019-08-06"
<?php
\Payplug\Card::delete('card_kFVrvXm2kYlZVmgk2sk1m9');

You can delete a card which was associated to a payment.

URL arguments:

Key Description
card_id Token of the payment card.

Subscriptions

To create a recurring payment, read our tutorial about Creating subscriptions.

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:

Method  Endpoint  Usage
POST /v1/installment_plans Create an installment plan
GET /v1/installment_plans/{installment_plan_id} Retrieve an installment plan
PATCH /v1/installment_plans/{installment_plan_id} Abort an installment plan

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
  }
}
<?php
// Get an attribute of the installment plan object:
// Print the installment plan is_fully_paid value
echo htmlentities($installment_plan->is_fully_paid);
// Print the $installment_plan id
echo htmlentities($installment_plan->id);
// Print the $installment_plan creation time in an human readable way
echo htmlentities(date('d/m/Y H:i:s', $installment_plan->created_at));

// Chain relations between objects:
// Print the first payment date
echo htmlentities($installment_plan->schedule[0]->date);
// Print the customer email
echo htmlentities($installment_plan->billing->email);

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

Object attributes:

Key Description
id string Installment plan ID.
object string Value is: installment_plan.
is_live boolean true for an installment_plan in LIVE mode, false in TEST mode.
is_active boolean true if the installment_plan is active, false otherwise.
currency currency Currency code (three-letter ISO 4217) in which the installment_plan was made.
created_at timestamp Creation date.
is_fully_paid boolean true if the installment_plan is fully paid (all installments are paid), false otherwise.
billing JSON object Information about billing.
  title: Customer title. string
  first_name: Customer first name. string
  last_name: Customer last name. string
  email: Customer email address. string
   mobile_phone_number: Customer mobile phone number (international format in the E.164 standard). phone number
   landline_phone_number: Customer landline phone number (international format in the E.164 standard). phone number
  address1: Customer address line 1 (Street address/PO Box/Company name). string
  address2: Customer address line 2 (Apartment/Suite/Unit/Building). string
  company_name: Customer company. string
  postcode: Customer Zip/Postal code. string
  city: Customer city. string
  state: Customer state. string
  country: Customer country code (two-letter ISO 3166). string
  language: Customer language code (two-letter ISO 639-1). string
shipping JSON object Information about shipping.
  title: Recipient title. string
  first_name: Recipient first name. string
  last_name: Recipient last name. string
  email: Recipient email address. string
   mobile_phone_number: Mobile phone number (international format in the E.164 standard). phone number
   landline_phone_number: Landline phone number (international format in the E.164 standard). phone number
  address1: Shipping address line 1 (Street address/PO Box/Company name). string
  address2: Shipping address line 2 (Apartment/Suite/Unit/Building). string
  company_name: Company name. string
  postcode: Shipping Zip/Postal code. string
  city: Shipping city. string
  state: Shipping state. string
  country: Shipping country code (two-letter ISO 3166). string
  language: Shipping language code (two-letter ISO 639-1). string
  delivery_type: Type of delivery (any of: BILLING VERIFIED NEW SHIP_TO_STORE DIGITAL_GOODS TRAVEL_OR_EVENT OTHER). See delivery type.
hosted_payment JSON object Data related to the first installment.
  payment_url: The payment URL you should redirect your customer to. string
  return_url: The URL the customer will be redirected to after the payment page whether it succeeds or not. string
  cancel_url: URL where the customer will be redirected after a click on “Cancel Payment”. string
notification JSON object Data related to notifications.
  url: The URL PayPlug will send notifications to. string
schedule Array of JSON object List of scheduled installments.
  date: Installment date. string
  amount: Amount of the payment in cents. integer
  payment_ids: List of payments ids. array
failure JSON object or null Information for unsuccessful installment plans.
  code: Installment plan failure code if the installment plan has failed. string
  message: Descriptive message explaining the reason of the installment plan failure. string
metadata JSON object Custom metadata object added when creating the installment plan.

Create an installment plan

Example:

$ curl -X POST https://api.payplug.com/v1/installment_plans \
  -H "Authorization: Bearer sk_test_9898098098guGYUG9" \
  -H "PayPlug-Version: 2019-08-06" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "schedule": [
      {"date": "TODAY", "amount": 1000},
      {"date": "2019-03-02", "amount": 2050},
      {"date": "2019-04-03", "amount": 1026}
    ],
    "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"
    }
  }'
<?php
$payment = \Payplug\InstallmentPlan::create(array(
  'currency'         => 'EUR',
  'schedule'         => array(
    array('date' => 'TODAY', 'amount' => 1000),
    array('date' => '2019-03-02', 'amount' => 2050),
    array('date' => '2019-04-02', 'amount' => 1026)
  ),
  '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
  )
));

Example response:

{
  "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",
    "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"
  },
  "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-02-02",
      "amount": 1000,
      "payment_ids": ["pay_12VazeAbq5ttYietdC2QxR"]
    },
    {
      "date":"2019-03-02",
      "amount": 2050,
      "payment_ids": ["pay_22uazeAbq5ttYietdC2QxP"]
    },
    {
      "date":"2019-04-02",
      "amount": 1026,
      "payment_ids": []
    },
  ],
  "failure": null,
  "metadata": {
    "customer_id": 42
  }
}

Allow customers to spread out payments over 2, 3 or 4 installments.

Parameters:

currency currency Currency code (three-letter ISO 4217) in which the installment_plan was made.
schedule Array of JSON object List of scheduled installments.
  date: Installment date, set TODAY for the first payment. string
  amount: Amount of the payment in cents. integer
billing JSON object required Billing information – recommended fields are optional but help increase your chances of frictionless payments. The billing object is still required, even if empty.
  title: Customer title, can be mr, mrs, miss, null string optional
   first_name: Customer first name (maximum length: 100 characters). string recommended
  last_name: Customer last name (maximum length: 100 characters). string recommended
   email: Customer email address (maximum length: 255 characters). email recommended
   mobile_phone_number: Customer mobile phone number (international format in the E.164 standard). phone number recommended (required if hosted_payment.sent_by is SMS).
   landline_phone_number: Customer landline phone number (international format in the E.164 standard). phone number recommended.
  address1: Customer address line 1 (maximum length: 255 characters). string recommended
  address2: Customer address line 2 (maximum length: 255 characters). string optional
  postcode: Customer Zip/Postal code (maximum length: 16 characters). string recommended
  city: Customer city (maximum length: 100 characters). string recommended
  state: Customer state (maximum length: 100 characters). string optional
  country: Customer country two-letter ISO 3166 code code recommended
  language: Customer language two-letter ISO 639-1 code code recommended. Supported languages: fr, en and it.
shipping JSON object required Shipping information – recommended fields are optional but help increase your chances of frictionless payments. The shipping object is still required, even if empty.
  title: Recipient title, can be mr, mrs, miss, null string optional
   first_name: Recipient first name (maximum length: 100 characters). string recommended
  last_name: Recipient last name (maximum length: 100 characters). string recommended
   email: Recipient email address (maximum length: 255 characters). email recommended
   mobile_phone_number: Recipient mobile phone number (international format in the E.164 standard). phone number recommended.
   landline_phone_number: Recipient landline phone number (international format in the E.164 standard). phone number recommended.
  address1: Shipping address line 1 (maximum length: 255 characters). string recommended
  address2: Shipping address line 2 (maximum length: 255 characters). string optional
  postcode: Shipping Zip/Postal code (maximum length: 16 characters). string recommended
  city: Shipping city (maximum length: 100 characters). string recommended
  state: Shipping state (maximum length: 100 characters). string optional
  country: Shipping country two-letter ISO 3166 code code recommended
  language: Shipping language two-letter ISO 639-1 code code recommended. Supported languages: fr, en and it.
  delivery_type: Type of delivery (any of: BILLING VERIFIED NEW SHIP_TO_STORE DIGITAL_GOODS TRAVEL_OR_EVENT OTHER). optional. See delivery type.
hosted_payment JSON object Data related to the first installment.
  return_url: URL where the customer will be redirected after the payment page whether it succeeds or not (for the first installment only). string
  cancel_url: The URL the customer will redirected to after a click on “Cancel Payment”. string
notification_url string optional The URL PayPlug will send notifications to.
metadata JSON object optional Custom metadata object.

Retrieve an installment plan

Example:

$ curl -X GET https://api.payplug.com/v1/installment_plans/inst_2JhnPxy4ABR4YBVW4UscWx \
  -H "Authorization: Bearer sk_test_9898098098guGYUG9" \
  -H "PayPlug-Version: 2019-08-06"
<?php
$installmentPlan = \Payplug\InstallmentPlan::retrieve('inst_2JhnPxy4ABR4YBVW4UscWx');

Example response:

{
  "id": "inst_2JhnPxy4ABR4YBVW4UscWx",
  "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/2JhnPxy4ABR4YBVW4UscWx",
    "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-02-02",
      "amount": 1000,
      "payment_ids": ["pay_12VazeAbq5ttYietdC2QxR"]
    },
    {
      "date":"2019-03-02",
      "amount": 2050,
      "payment_ids": ["pay_22uazeAbq5ttYietdC2QxP"]
    },
    {
      "date":"2019-04-02",
      "amount": 1026,
      "payment_ids": []
    },
  ],
  "failure": null,
  "metadata": {
    "customer_id": 42
  }
}

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

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

URL arguments:

Key Description
installment_plan_id ID of the installment_plan to be retrieved.

Abort an installment plan

Example:

$ curl -X PATCH https://api.payplug.com/v1/installment_plans/inst_2JhnPxy4ABR4YBVW4UscWx \
  -H "Authorization: Bearer sk_test_9898098098guGYUG9" \
  -H "PayPlug-Version: 2019-08-06" \
  -H "Content-Type: application/json" \
  -d '{"aborted": true}'
<?php
// Abort from an installment plan ID
$installmentPlanId = 'inst_2JhnPxy4ABR4YBVW4UscWx';
$installmentPlan = \Payplug\InstallmentPlan::abort($installmentPlanId);

// Abort from an installment_plan object
$installmentPlanId = 'inst_2JhnPxy4ABR4YBVW4UscWx';
$installmentPlan = \Payplug\InstallmentPlan::retrieve($installmentPlanId);
$installmentPlan = $installment_plan->abort();

Example response:

{
  "id": "inst_2JhnPxy4ABR4YBVW4UscWx",
  "object": "installment_plan",
  "is_live": true,
  "is_active": false,
  "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/2JhnPxy4ABR4YBVW4UscWx",
    "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-02-02",
      "amount": 1000,
      "payment_ids": ["pay_12VazeAbq5ttYietdC2QxR"]
    },
    {
      "date":"2019-03-02",
      "amount": 2050,
      "payment_ids": ["pay_22uazeAbq5ttYietdC2QxP"]
    },
    {
      "date":"2019-04-02",
      "amount": 1026,
      "payment_ids": []
    },
  ],
  "failure": {
    "code": "aborted",
    "message": "You have aborted the transaction."
  },
  "metadata": {
    "customer_id": 42
  }
}

Abort an installment plan to prevent future installments to be created.

When an installment plan is aborted, its failure code will be set to aborted, and is_active will be set to false.

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

URL arguments:

Key Description
installment_plan_id ID of the installment_plan to be aborted.

Parameters:

Key Description
aborted boolean required This parameter must be true.

Installment plan notifications

Example:

{
  "id": "inst_1FTGSRWYHla7eDkfTo2Usd",
  "object": "installment_plan",
  "is_live": true
}

PayPlug will send you a notification (if you provided a notification_url at creation time) when an installment plan is aborted, or whenever an installment succeeds or fails.

The notification URL used for an installment plan will be used for notifications about all related payments and refunds.

Apple pay

Read these articles before embarking on the integration of Apple Pay.

  1. Ensure that your PayPlug account has the Apple Pay feature.
  2. The miscellaneous information here.
  3. Accepting payments with Apple Pay through PayPlug here.
  4. Upload the DOMAIN ASSOCIATION file.
  5. To verify that the document is in its correct place.

Implementations:

  1. Product and Cart Page.
  2. Checkout page.

Product and Cart Pages

Here are the steps we will follow.

  1. Add the Apple Pay button.
  2. How to retrieve the merchant validation:
    1. Create a request.
    2. Retrieve the merchant validation.
  3. Validate biometrics (payment).
  4. Update delivery information.
  5. Cancel a payment.

Add the Apple Pay button

client side

<apple-pay-button onclick="onApplePayButtonClicked()" buttonstyle="black" type="plain" locale="fr-FR"></apple-pay-button>

<script src="https://applepay.cdn-apple.com/jsapi/v1/apple-pay-sdk.js"></script>
function onApplePayButtonClicked() {

    if (!ApplePaySession) {
        return;
    }

    // Define ApplePayPaymentRequest
    const request = {
        "countryCode": "FR",
        "currencyCode": "EUR",
        "merchantCapabilities": [
            "supports3DS"
        ],
        "shippingMethods": [
            {
                "label": "Standard Shipping",
                "amount": "10.00",
                "detail": "Arrives in 5-7 days",
                "identifier": "standardShipping",
                "dateComponentsRange": {
                    "startDateComponents": {
                        "years": 2022,
                        "months": 9,
                        "days": 24,
                        "hours": 0
                    },
                    "endDateComponents": {
                        "years": 2024,
                        "months": 9,
                        "days": 26,
                        "hours": 0
                    }
                }
            }
            ...
        ],
        "shippingType": "shipping",
        "supportedNetworks": [
            "visa",
            "masterCard"
        ],
        "requiredBillingContactFields": [
            "postalAddress",
            "name"
        ],
        "requiredShippingContactFields": [
            "postalAddress",
            "name",
            "phone",
            "email"
        ],
        "total": {
            "label": "X",
            "amount": "10.00",
            "type": "final"
        },
        'applicationData': btoa(JSON.stringify({'apple_pay_domain': 'www.mywebsite.com'}))
    };

    // Create ApplePaySession
    const session = new ApplePaySession(14, request);

    session.onvalidatemerchant = async event => {
        // Call your own server to request a new merchant session.
        const merchantSession = await validateMerchant();
        session.completeMerchantValidation(merchantSession);
    };

    session.onshippingmethodselected = event => {};

    session.onpaymentauthorized = async (event) => {};

    session.oncancel = async () => {};

    session.begin();
}

You can customize your button directly on the Apple site here.
Now that we have the Apple structure for the Apple popup, we will need to have a valid merchant.

Retrieve the validation

client side

    const validateMerchant = async () => {
        const res = await fetch('/create-apple-payment', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                "amount" : 1000, // The amount should be in cents.
                "customer": {
                    "first_name": "Jake",
                    "last_name": "TheDog",
                    "email": "jake.thedog@payplug.com",
                }
            })
        })

        const data = await res.json()
        return data.payment_method.merchant_session
    };

server side

domain = json.dumps({"apple_pay_domain": "www.mywebsite.com"}, separators=(",", ":"))
application_data = base64.b64encode(domain.encode("UTF-8")).decode()

payment_data = {
    "amount": 1000,
    "currency": "EUR",
    "payment_method": "apple_pay",
    "billing": {
        "first_name": "Jake",
        "last_name": "Thedog",
        "email": "jake.thedog@gmail.com",
    },
    "shipping": {},
    "metadata": {
      "applepay_workflow": "cart"
    },
    "payment_context": {
        "apple_pay": {
              "domain_name": "www.mywebsite.com",
              "application_data": application_data,
          }
    }
}
payment = payplug.Payment.create(**payment_data)

Example response:

{
  "amount": 1000,
  "currency": "EUR",
  "is_paid": false,
  "paid_at": null,
  "hosted_payment": null,
  "notification": {
    "url": null,
    "response_code": null
  },
  "metadata": {
    "applepay_workflow": "cart"
  },
  "failure": null,
  "installment_plan_id": null,
  "authorization": null,
  "refundable_after": null,
  "refundable_until": null,
  "integration": null,
  "payment_method": {
    "type": "apple_pay",
    "merchant_session": {
      "..."
    }
  },
  "billing": {
    "title": null,
    "first_name": "John",
    "last_name": "Watson",
    "address1": null,
    "address2": null,
    "company_name": null,
    "postcode": null,
    "city": null,
    "state": null,
    "country": null,
    "email": "john.watson@example.net",
    "mobile_phone_number": null,
    "landline_phone_number": null,
    "language": "fr"
  },
  "shipping": {
    "title": null,
    "first_name": "John",
    "last_name": "Watson",
    "address1": null,
    "address2": null,
    "company_name": null,
    "postcode": null,
    "city": null,
    "state": null,
    "country": null,
    "email": "john.watson@example.net",
    "mobile_phone_number": null,
    "landline_phone_number": null,
    "language": "fr",
    "delivery_type": null
  }
}

We will prepare the request by retrieving the amount, customer, etc.

We will also add the apple_pay_domain part in the payment_context.
However, it should not be passed as simply as the previous parameters.

Key Description
amount int The amount in cents (euros).
currency string Currency code (three-letter ISO 4217) in which the payment was made.
payment_method string type: the type of payment made, one of: apple_pay. string
billing JSON object Information about billing.
  title: Recipient title, can be mr, mrs, miss, null string optional
  first_name: Recipient first name (maximum length: 100 characters). string recommended
  last_name: Recipient last name (maximum length: 100 characters). string recommended
  email: Recipient email address (maximum length: 255 characters). email recommended
  mobile_phone_number: Recipient mobile phone number (international format in the E.164 standard). phone number recommended.
  landline_phone_number: Recipient landline phone number (international format in the E.164 standard). phone number recommended.
  address1: Shipping address line 1 (maximum length: 255 characters). string recommended
  address2: Shipping address line 2 (maximum length: 255 characters). string optional
  company_name: Customer company. string
  postcode: Shipping Zip/Postal code (maximum length: 16 characters). string recommended
  city: Shipping city (maximum length: 100 characters). string recommended
  state: Shipping state (maximum length: 100 characters). string optional
  country: Shipping country two-letter ISO 3166 code code recommended
  language: Customer language code (two-letter ISO 639-1). string
shipping JSON object required Shipping information – recommended fields are optional but help increase your chances of frictionless payments. The shipping object is still required, even if empty.
  title: Recipient title, can be mr, mrs, miss, null string optional
  first_name: Recipient first name (maximum length: 100 characters). string recommended
  last_name: Recipient last name (maximum length: 100 characters). string recommended
  email: Recipient email address (maximum length: 255 characters). email recommended
  mobile_phone_number: Recipient mobile phone number (international format in the E.164 standard). phone number recommended.
  landline_phone_number: Recipient landline phone number (international format in the E.164 standard). phone number recommended.
  address1: Shipping address line 1 (maximum length: 255 characters). string recommended
  address2: Shipping address line 2 (maximum length: 255 characters). string optional
  postcode: Shipping Zip/Postal code (maximum length: 16 characters). string recommended
  city: Shipping city (maximum length: 100 characters). string recommended
  state: Shipping state (maximum length: 100 characters). string optional
  country: Shipping country two-letter ISO 3166 code code recommended
  language: Shipping language two-letter ISO 639-1 code code recommended. Supported languages: fr, en and it.
  delivery_type: Type of delivery (any of: BILLING VERIFIED NEW SHIP_TO_STORE DIGITAL_GOODS TRAVEL_OR_EVENT OTHER). optional. See delivery type.
Metadata json The metadata sent when creating this operation1.
payment_context JSON object apple_pay JSON object
  domain_name: string The name of your domain.
  application_data: base64 Your domain name in Base64.

The POST request at PayPlug will allow us to create the request and generate
the necessary information to proceed with the payment later.

Payment process

We will proceed with the payment authorization. We will use the onpaymentauthorized function in the Apple session, allowing us to capture this event.

After receiving the request, the biometrics will be displayed.
So, after biometric validation, we need to process the payment.
Apple provides session.onpaymentauthorized, allowing us to retrieve the token, billing, and shipping information via the Apple popup.

client side

session.onpaymentauthorized = async (event) => {
  const paymentToken = event.payment.token
  const billing = event.payment.billingContact
  const shipping = event.payment.shippingContact

  const res = await fetch(`/update-apple-payment/${paymentId}`, {
      method: 'PATCH',
      headers: {
          'Content-Type': 'application/json'
      },
      body: JSON.stringify({
          "billing" : billing,
          "shipping" : shipping,
          "amount" : amount,
          "payment_token": paymentToken,
      })
  })
}
Key Description
id string The object resource unique identifier (e.g. a payment ID).
apple_pay JSON object Information related to Apple Pay.
  amount int The amount in cents (euros).
  payment_token JSON object Token generated by Apple from the popup.
  billing JSON object Information about billing.
  shipping JSON object Information about shipping.

server side

$ curl -X PATCH https://api.payplug.com/v1/payments/pay_XXX \
  -H 'Authorization: Bearer sk_test_9898098098guGYUG9' \
  -H 'PayPlug-Version: 2019-08-06' \
  -H 'Content-Type: application/json' \
  -d '{
  "apple_pay": {
      "amount": 1000,
      "payment_token": "...",
      "billing": {
        "first_name": "Jake",
        "last_name": "TheDog",
        "address1": "54 rue des buissons",
        "postcode": 75001,
        "city": "Paris",
        "country": "FR",
        "language": "fr",
        "email": "jake.thedog@gmail.com"
      },
      "shipping": {
        "first_name": "Jake",
        "last_name": "TheDog",
        "address1": "54 rue des buissons",
        "postcode": 75001,
        "city": "Paris",
        "country": "FR",
        "email": "jake.thedog@gmail.com",
        "mobile_phone_number": "+3360000000",
        "language": "fr"
      }
  }

Example response:

{
  "id": "pay_4j...",
  "is_live": true,
  "amount": 1000,
  "currency": "EUR",
  "is_paid": true,
  "paid_at": 1701351541,
  "hosted_payment": null,
  "notification": {
    "url": null,
    "response_code": null
  },
  "metadata": {
    "applepay_workflow": "cart"
  },
  "failure": null,
  "refundable_after": 1701351541,
  "refundable_until": 1716903541,
  "integration": null,
  "payment_method": {
    "type": "apple_pay",
  },
  "billing": {
    "title": null,
    "first_name": "Jake",
    "last_name": "Thedog",
    "address1": "110 Avenue de France",
    "address2": null,
    "company_name": null,
    "postcode": "75013",
    "city": "Paris",
    "state": null,
    "country": "FR",
    "email": "jake.thedog@gmail.com",
    "mobile_phone_number": null,
    "landline_phone_number": null,
    "language": "fr"
  },
  "shipping": {
    "title": null,
    "first_name": "Jake",
    "last_name": "Thedog",
    "address1": "110 Avenue de France",
    "address2": null,
    "company_name": null,
    "postcode": "75013",
    "city": "Paris",
    "state": null,
    "country": "FR",
    "email": "jake.thedog@gmail.com",
    "mobile_phone_number": "+336000000",
    "landline_phone_number": null,
    "language": "fr",
    "delivery_type": null
  }
}

Apple Pay retrieval

As seen in the previous example, we can check if the payment has been successfully completed.
In the response to the PATCH request, we have the is_paid information.

client side

    session.onpaymentauthorized = async (event) => {
        const paymentToken = event.payment.token
        const billing = event.payment.billingContact
        const shipping = event.payment.shippingContact

        const res = await fetch(`/update-apple-payment/${paymentId}`, {
            method: 'PATCH',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                "environment" : document.getElementById("environment").value,
                "secret_key" : document.getElementById("secret-key").value,
                "billing" : billing,
                "shipping" : shipping,
                "amount" : eurToCents(amount),
                "payment_token": paymentToken,
            })
        })

        let apple_pay_Session_status = ApplePaySession.STATUS_SUCCESS;
        const data = await res.json()
        if (data.is_paid !== true) {
            apple_pay_Session_status = ApplePaySession.STATUS_FAILURE;
        }

        const result = {
            "status": apple_pay_Session_status
        };

        session.completePayment(result);
    };

Delivery information update

You can find the Apple Pay documentation for updating delivery here.

    session.onshippingmethodselected = event => {
        ...
        const updated = {
            "newTotal": {
                "label": "Demo (Card is not charged)",
                "amount": amount,
                "type": "final"
            },
        }
        session.completeShippingMethodSelection(updated);
    };

Cancel payment

Apple also provides various events, such as canceling the payment. Here is how to integrate it with PayPlug.

client side

session.oncancel = async () => {
  await fetch(`/update-apple-payment/${paymentId}`, {
      method: 'PATCH',
      headers: {
          'Content-Type': 'application/json'
      },
      body: JSON.stringify({
          "aborted" : true,
      })
  })
};

server side

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

Oney

  1. Review our Oney acceptance criteria (FR - IT) to verify your eligibility.
  2. Signup for a PayPlug account if you don’t already have one and subscribe to a PayPlug offer that includes Oney (FR - IT).
  3. Reach out to your account manager or our Customer Success team who will assist you from your PayPlug account activation to the integration of our Oney endpoint to your shop.

Oney payments are split payments where the merchant is guaranteed to receive the total amount of the transaction at the time the first transaction occurs. For such payments, the payer is redirected to an Oney payment form where he will file a request for a split payment and agree to Oney’s terms and conditions. Oney will then review the payer’s request before agreeing to it. The transaction can thus take either of these three statuses:

More details about the statuses are available in Interpreting an Oney payment status.

As soon as the transaction’s status changes to Authorized, Oney makes the total amount of the transaction available for the merchant to capture. The payer will then be charged by Oney according to the schedule and amounts he has agreed to.

As of now, we support payments in 3 or 4 installments. We support either:

In any case, you can preview the steps of an installment and calculate the fee the payer will pay (if any) using our Oney Payment Simulation API.

Create an Oney payment

Create an Oney 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": 50000,
    "auto_capture": true,
    "currency": "EUR",
    "payment_method": "oney_x3_with_fees",
    "billing": {
      "title": "mr",
      "first_name": "John",
      "last_name": "Watson",
      "email": "john.watson@example.net",
      "address1": "1 rue de la Boetie",
      "postcode": "75008",
      "city": "Paris",
      "country": "FR",
      "mobile_phone_number": "+33612345678",
      "language": "fr"
    },
    "shipping": {
      "title": "mr",
      "first_name": "John",
      "last_name": "Watson",
      "email": "john.watson@example.net",
      "address1": "1 rue de la Boetie",
      "postcode": "75008",
      "city": "Paris",
      "country": "FR",
      "language": "fr",
      "mobile_phone_number": "+33612345678",
      "delivery_type": "BILLING",
      "company_name": "SuperCorp"
    },
    "payment_context": {
      "cart": [
        {
            "delivery_label": "Micropple store",
            "delivery_type": "storepickup",
            "brand": "Micropple",
            "merchant_item_id": "REF-123456",
            "name": "Laser printer",
            "expected_delivery_date": "2030-06-20",
            "total_amount": 22000,
            "price": 11000,
            "quantity": 2
        }
      ]
    },
    "notification_url": "https://example.net/notifications?id=42",
    "hosted_payment": {
      "return_url": "https://example.net/return?id=42"
    }
  }'
<?php
$payment = \Payplug\Payment::create(array(
  'authorized_amount' => 50000,
  'auto_capture'      => true,
  'currency'          => 'EUR',
  'payment_method'    => 'oney_x3_with_fees',
  'billing'           => array(
      'title'               => 'mr',
      'first_name'          => 'John',
      'last_name'           => 'Watson',
      'email'               => 'john.watson@example.net',
      'address1'            => '1 rue de la Boetie',
      'postcode'            => '75008',
      'city'                => 'Paris',
      'country'             => 'FR',
      'mobile_phone_number' => '+33612345678',
      'language'            => 'fr'
  ),
  'shipping'          => array(
      'title'               => 'mr',
      'first_name'          => 'John',
      'last_name'           => 'Watson',
      'email'               => 'john.watson@example.net',
      'address1'            => '1 rue de la Boetie',
      'postcode'            => '75008',
      'city'                => 'Paris',
      'country'             => 'FR',
      'language'            => 'fr',
      'mobile_phone_number' => '+33612345678',
      'delivery_type'       => 'BILLING',
      'company_name'        => 'SuperCorp'
  ),
  'payment_context'   => array(
      'cart' => array(
        0 => array(
         'delivery_label'         => 'Micropple store',
         'delivery_type'          => 'storepickup',
         'brand'                  => 'Micropple',
         'merchant_item_id'       => 'REF-123456',
         'name'                   => 'Laser printer',
         'expected_delivery_date' => '2030-06-20',
         'total_amount'           => 22000,
         'price'                  => 11000,
         'quantity'               => 2
        )
      )
  ),
  'notification_url' => 'https://example.net/notifications?id=42',
  'hosted_payment'   => array(
    'return_url' => 'https://example.net/return?id=42'
  )
));
payment_data = {
  "authorized_amount": 50000,
  "auto_capture": True,
  "currency": "EUR",
  "payment_method": "oney_x3_with_fees",
  "billing": {
    "title": "mr",
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "address1": "1 rue de la Boetie",
    "postcode": "75008",
    "city": "Paris",
    "country": "FR",
    "mobile_phone_number": "+33612345678",
    "language": "fr"
  },
  "shipping": {
    "title": "mr",
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "address1": "1 rue de la Boetie",
    "postcode": "75008",
    "city": "Paris",
    "country": "FR",
    "language": "fr",
    "mobile_phone_number": "+33612345678",
    "delivery_type": "BILLING",
    "company_name": "SuperCorp"
  },
  "payment_context": {
    "cart": [
      {
          "delivery_label": "Micropple store",
          "delivery_type": "storepickup",
          "brand": "Micropple",
          "merchant_item_id": "REF-123456",
          "name": "Laser printer",
          "expected_delivery_date": "2030-06-20",
          "total_amount": 22000,
          "price": 11000,
          "quantity": 2
      }
    ]
  },
  "notification_url": "https://example.net/notifications?id=42",
  "hosted_payment": {
    "return_url": "https://example.net/return?id=42"
  }
}
payment = payplug.Payment.create(**payment_data)

Example response:

{
  "billing": {
      "address1": "1 rue de la Boetie",
      "last_name": "Watson",
      "city": "Paris",
      "address2": null,
      "email": "john.watson@example.net",
      "state": null,
      "landline_phone_number": null,
      "first_name": "John",
      "title": "mr",
      "company_name": null,
      "language": "fr",
      "postcode": "75008",
      "country": "FR",
      "mobile_phone_number": "+33612345678"
  },
  "is_3ds": null,
  "shipping": {
      "address1": "1 rue de la Boetie",
      "last_name": "Watson",
      "city": "Paris",
      "address2": null,
      "email": "john.watson@example.net",
      "state": null,
      "landline_phone_number": null,
      "first_name": "John",
      "title": "mr",
      "company_name": "SuperCorp",
      "language": "fr",
      "postcode": "75008",
      "country": "FR",
      "delivery_type": "BILLING",
      "mobile_phone_number": "+33612345678"
  },
  "is_live": true,
  "notification": {
      "url": "https://example.net/notifications?id=42",
      "response_code": null
  },
  "hosted_payment": {
      "cancel_url": null,
      "payment_url": "https://secure.payplug.com/pay/4W43bXst15Yd55RE9ZszX2",
      "sent_by": null,
      "paid_at": null,
      "return_url": "https://example.net/return?id=42"
  },
  "is_refunded": false,
  "amount": 50000,
  "save_card": false,
  "currency": "EUR",
  "object": "payment",
  "card": {
      "exp_year": null,
      "last4": null,
      "metadata": null,
      "id": null,
      "country": null,
      "brand": null,
      "exp_month": null
  },
  "payment_method": {
      "is_pending": false,
      "type": "oney_x3_with_fees"
  },
  "id": "pay_4W43bXst15Yd55RE9ZszX2",
  "description": null,
  "paid_at": null,
  "metadata": null,
  "is_paid": false,
  "authorization": {
      "authorized_at": null,
      "authorized_amount": 50000,
      "expires_at": null
  },
  "installment_plan_id": null,
  "created_at": 1574951751,
  "amount_refunded": 0,
  "failure": null
}

Here is how you should create an Oney payment:

  1. Ensure that you are using a version of the API dating from 2019-08-06 onwards. See the Version section of this documentation for more information on that.
  2. Create a payment by following the section Create a payment. Pass one of the oney_* payment methods to the payment_method field, and use the field authorized_amount to define the full amount of the transaction.
  3. Make sure that you fill in the parameters specific to Oney.
  4. Redirect the payer to the payment_url of the payment resource.
  5. In order to follow the status of the payment once the payer has filled out Oney’s payment form, implement one (or both) of the following:
  6. Once the payment has been authorized by Oney, you can capture it

Interpreting an Oney payment status

After the payer has filed a split payment request to Oney using the payment form and you’ve retrieved the corresponding payment resource, the payment can be in one of three states:

  1. Authorized: Oney has accepted the payer’s file. In this case, both fields authorization and authorized_at can be found in the payment resource.
  2. Failure: Oney has rejected the payer’s file. In this case, the field failure is not null in the payment resource.
  3. Oney pending: Oney is reviewing the payer’s file, the field payment_method is set in the resource with the sub-field type reflecting the payment_method you used to create the payment and the sub-field pending set to true. A notification will be sent to your notification_url when the payment state switches from Oney pending to one of the other states.

Oney payment simulation

The API allows you to run simulations of split payments with Oney. The simulation will let you know:

This is useful for example when displaying a schedule and the details of the fees to your customer.

Method  Endpoint  Usage
POST /v1/oney_payment_simulations Simulate an Oney payment

The payment simulation object

Example:

{
  "x3_with_fees": {
    "down_payment_amount": 67667,
    "nominal_annual_percentage_rate": 6.04,
    "effective_annual_percentage_rate": 6.21,
    "installments": [
      {
        "date": "2019-12-29T01:00:00.000Z",
        "amount": 66667
      },
      {
        "date": "2020-01-29T01:00:00.000Z",
        "amount": 66666
      }
    ],
    "total_cost": 1000
  },
  "x4_without_fees": {
    "installments": [
      {
        "date": "2019-12-29T01:00:00.000Z",
        "amount": 50000
      },
      {
        "date": "2020-01-29T01:00:00.000Z",
        "amount": 50000
      },
      {
        "date": "2020-02-29T01:00:00.000Z",
        "amount": 50000
      }
    ],
    "total_cost": 0,
    "nominal_annual_percentage_rate": 0.0,
    "effective_annual_percentage_rate": 0.0,
    "down_payment_amount": 50000
  }
}

Object attributes:

Key Description
x3_with_fees JSON object Simulation for a payment in 3 installments with fees.
x4_with_fees JSON object Simulation for a payment in 4 installments with fees.
x3_without_fees JSON object Simulation for a payment in 3 installments without fees.
x4_without_fees JSON object Simulation for a payment in 4 installments without fees.
[Object specification] Any of the above key has the following object:
  down_payment_amount: Amount of the first installment, paid immediatly by the payer, in cents. integer
  nominal_annual_percentage_rate: Annual percentage rate, without accounting for inflation. float
  effective_annual_percentage_rate: Annual percentage rate, including inflation. float
  installments: list of further installments. JSON list
  date: Date at which the amount of this installment will be charged (in ISO 8601 format). datetime
  amount: Amount that will be charged for this installment, in cents. integer
  total_cost: Cost of the plan, in cents. This fee is included in the sum of the amounts of the payments.

The payment simulation endpoint will tell you that, for example, a payment of 2000.00€ split in 3 installments with fees will cost 10€ to the payer and will be paid as follows:

Create a simulation

Create a simulation:

$ curl -X POST \
  https://api.payplug.com/v1/oney_payment_simulations \
  -H 'Authorization: Bearer sk_live_BlablahDpMM95Zabcde234' \
  -H 'PayPlug-Version: 2019-08-06' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 200000,
    "country": "FR",
    "operations": ["x3_with_fees", "x4_with_fees", "x3_without_fees", "x4_without_fees"]
  }'
<?php
$simulations = \Payplug\OneySimulation::getSimulations(array(
  'amount' => 200000,
  'country' => 'FR',
  'operations' => ['x3_with_fees', 'x4_with_fees', 'x3_without_fees', 'x4_without_fees']
));
data = {
  'amount': 200000,
  'country': 'FR',
  'operations': ['x3_with_fees', 'x4_with_fees', 'x3_without_fees', 'x4_without_fees']
}
simulations = payplug.OneyPaymentSimulation.get_simulation(**data)

Example response:

{
  "x3_with_fees": {
    "installments": [
      {
        "date": "2021-07-17T00:00:00.000Z",
        "amount": 66667
      },
      {
        "date": "2021-08-17T00:00:00.000Z",
        "amount": 66666
      }
    ],
    "total_cost": 1000,
    "nominal_annual_percentage_rate": 6.04,
    "effective_annual_percentage_rate": 6.21,
    "down_payment_amount": 67667
  },
  "x4_with_fees": {
    "installments": [
      {
        "date": "2021-07-17T00:00:00.000Z",
        "amount": 50000
      },
      {
        "date": "2021-08-17T00:00:00.000Z",
        "amount": 50000
      },
      {
        "date": "2021-09-17T00:00:00.000Z",
        "amount": 50000
      }
    ],
    "total_cost": 2000,
    "nominal_annual_percentage_rate": 8.09,
    "effective_annual_percentage_rate": 8.4,
    "down_payment_amount": 52000
  },
  "x3_without_fees": {
    "installments": [
      {
        "date": "2021-07-08T00:00:00.000Z",
        "amount": 66666
      },
      {
        "date": "2021-08-08T00:00:00.000Z",
        "amount": 66666
      }
    ],
    "total_cost": 0,
    "nominal_annual_percentage_rate": 0,
    "effective_annual_percentage_rate": 0,
    "down_payment_amount": 66668
  },
  "x4_without_fees": {
    "installments": [
      {
        "date": "2021-07-08T00:00:00.000Z",
        "amount": 50000
      },
      {
        "date": "2021-08-08T00:00:00.000Z",
        "amount": 50000
      },
      {
        "date": "2021-09-08T00:00:00.000Z",
        "amount": 50000
      }
    ],
    "total_cost": 0,
    "nominal_annual_percentage_rate": 0,
    "effective_annual_percentage_rate": 0,
    "down_payment_amount": 50000
  }
}

A simulation depends on 2 variables: the total amount of the payment, and the country of the payer. You can ask for simulations on one or multiple of our available payment methods: x3_with_fees, x4_with_fees, x3_without_fees, x4_without_fees.

Parameters:

Key Description
amount positive integer Amount of the payment to be split, in cents.
country string Country code of the payer, in the ISO 3166-1 alpha-2 standard. Supported countries are France and Italy (respectively FR and IT) as well as France’s oversees departments and regions (GP, MQ, GF, RE, YT).
operations JSON list List of operations to perform a simulation for. Available operations are x3_with_fees, x4_with_fees, x3_without_fees, x4_without_fees. The simulation object returned will have one root field for each of the requested operations (x3 and x4), each of which will in turn contain a payment simulation object giving you the result of the simulation for the operation.

Payment Methods

Payplug API offers some other payment methods to help you accept payments from more people and more countries.
Currently, the following payment methods are accepted:

Some payment methods are not supported in every country due to certain restrictions coming from the payment method itself.
Your customers must be residents of specific countries to be able to use them.
Some payment methods can also have amount limits, which depend on the payment method provider.
We encourage you to only offer these payment methods if the constraints of amount and country are respected.

Payment method Authorized countries Amount limits (€)
American Express worldwide 0.99 to 20,000
Bancontact worldwide 0.99 to 20,000
Giropay DE 1 to 10,000
iDeal NL 0.99 to 20,000
MyBank IT 0.99 to 20,000
Satispay AT, BE, CY, DE, EE, ES, FI, FR, GR, HR, HU, IE, IT, LT, LU, LV, MT, NL, PT, SI, SK 0.99 to 20,000
Sofort AT, BE, DE, ES, NL 1 to 5,000

Create a payment

Example :

$ curl -X POST https://api.payplug.com/v1/payments \
  -H 'Authorization: Bearer sk_live_xxxxxx' \
  -H 'PayPlug-Version: 2019-08-06' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 50000,
    "currency": "EUR",
    "payment_method": "bancontact",
    "billing": {
      "title": "mr",
      "first_name": "John",
      "last_name": "Watson",
      "email": "john.watson@example.net",
      "address1": "1 rue de la Boetie",
      "postcode": "75008",
      "city": "Paris",
      "country": "FR",
      "mobile_phone_number": "+33612345678",
      "language": "fr"
    },
    "shipping": {
      "title": "mr",
      "first_name": "John",
      "last_name": "Watson",
      "email": "john.watson@example.net",
      "address1": "1 rue de la Boetie",
      "postcode": "75008",
      "city": "Paris",
      "country": "FR",
      "language": "fr",
      "mobile_phone_number": "+33612345678",
      "delivery_type": "BILLING",
      "company_name": "SuperCorp"
    },
    "notification_url": "https://example.net/notifications?id=42",
    "hosted_payment": {
      "return_url": "https://example.net/return?id=42"
    }
  }'
<?php
$payment = \Payplug\Payment::create(array(
  'amount' => 50000,
  'currency'          => 'EUR',
  'payment_method'    => 'bancontact',
  'billing'           => array(
      'title'               => 'mr',
      'first_name'          => 'John',
      'last_name'           => 'Watson',
      'email'               => 'john.watson@example.net',
      'address1'            => '1 rue de la Boetie',
      'postcode'            => '75008',
      'city'                => 'Paris',
      'country'             => 'FR',
      'mobile_phone_number' => '+33612345678',
      'language'            => 'fr'
  ),
  'shipping'          => array(
      'title'               => 'mr',
      'first_name'          => 'John',
      'last_name'           => 'Watson',
      'email'               => 'john.watson@example.net',
      'address1'            => '1 rue de la Boetie',
      'postcode'            => '75008',
      'city'                => 'Paris',
      'country'             => 'FR',
      'language'            => 'fr',
      'mobile_phone_number' => '+33612345678',
      'delivery_type'       => 'BILLING',
      'company_name'        => 'SuperCorp'
  ),
  'notification_url' => 'https://example.net/notifications?id=42',
  'hosted_payment'   => array(
    'return_url' => 'https://example.net/return?id=42'
  )
));
payment_data = {
  "amount": 50000,
  "currency": "EUR",
  "payment_method": "bancontact",
  "billing": {
    "title": "mr",
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "address1": "1 rue de la Boetie",
    "postcode": "75008",
    "city": "Paris",
    "country": "FR",
    "mobile_phone_number": "+33612345678",
    "language": "fr"
  },
  "shipping": {
    "title": "mr",
    "first_name": "John",
    "last_name": "Watson",
    "email": "john.watson@example.net",
    "address1": "1 rue de la Boetie",
    "postcode": "75008",
    "city": "Paris",
    "country": "FR",
    "language": "fr",
    "mobile_phone_number": "+33612345678",
    "delivery_type": "BILLING",
    "company_name": "SuperCorp"
  },
  "notification_url": "https://example.net/notifications?id=42",
  "hosted_payment": {
    "return_url": "https://example.net/return?id=42"
  }
}
payment = payplug.Payment.create(**payment_data)

Example response:

{
  "billing": {
      "address1": "1 rue de la Boetie",
      "last_name": "Watson",
      "city": "Paris",
      "address2": null,
      "email": "john.watson@example.net",
      "state": null,
      "landline_phone_number": null,
      "first_name": "John",
      "title": "mr",
      "company_name": null,
      "language": "fr",
      "postcode": "75008",
      "country": "FR",
      "mobile_phone_number": "+33612345678"
  },
  "is_3ds": null,
  "shipping": {
      "address1": "1 rue de la Boetie",
      "last_name": "Watson",
      "city": "Paris",
      "address2": null,
      "email": "john.watson@example.net",
      "state": null,
      "landline_phone_number": null,
      "first_name": "John",
      "title": "mr",
      "company_name": "SuperCorp",
      "language": "fr",
      "postcode": "75008",
      "country": "FR",
      "delivery_type": "BILLING",
      "mobile_phone_number": "+33612345678"
  },
  "is_live": true,
  "notification": {
      "url": "https://example.net/notifications?id=42",
      "response_code": null
  },
  "hosted_payment": {
      "cancel_url": null,
      "payment_url": "https://secure.payplug.com/pay/4W43bXst15Yd55RE9ZszX2",
      "sent_by": null,
      "paid_at": null,
      "return_url": "https://example.net/return?id=42"
  },
  "is_refunded": false,
  "amount": 50000,
  "save_card": false,
  "currency": "EUR",
  "object": "payment",
  "card": {
      "exp_year": null,
      "last4": null,
      "metadata": null,
      "id": null,
      "country": null,
      "brand": null,
      "exp_month": null
  },
  "id": "pay_4W43bXst15Yd55RE9ZszX2",
  "description": null,
  "paid_at": null,
  "metadata": null,
  "is_paid": false,
  "authorization": {
      "authorized_at": null,
      "amount": 50000,
      "expires_at": null
  },
  "installment_plan_id": null,
  "created_at": 1574951751,
  "amount_refunded": 0,
  "failure": null
}
  1. Ensure that you are using a version of the API dating from 2019-08-06 onwards. See the Version section of the API documentation for more information.
  2. Create a payment by following the steps listed in the Create a payment section. Pass the <apm_name> payment method to the payment_method field.
  3. Redirect the payer to the payment_url of the payment resource.
  4. Once generated, you can check the payment status by implementing one (or both) of the following:

The <apm_name> can take the value of american_express, bancontact, giropay, ideal, mybank, satispay, sofort.

Guidelines

American Express guidelines

If you need some collateral materials for your website, check the American Express Ressources digitales.

Bancontact guidelines

If you need some collateral materials for your website, check the Bancontact Guidelines.

Giropay guidelines

If you need some collateral materials for your website, check the Giropay Guidelines.

iDeal guidelines

If you need some collateral materials for your website, check the iDeal Guidelines.

MyBank guidelines

If you need some collateral materials for your website, check the MyBank Guidelines.

Satispay guidelines

If you need some collateral materials for your website, check the Satispay Guidelines.

Sofort guidelines

If you need some collateral materials for your website, check the Sofort Guidelines.

Limitations

Save Card

The save card feature is not available for Alternative Payment Methods for now.

Refund

It’s not possible to refund payments for payment methods based on SCT (SEPA Credit Transfert). This limitation concerns:

Accounting reports

Use the /accounting_reports endpoint to create or retrieve an accounting report.

Accounting reports endpoint reference:

Method  Endpoint  Usage
POST /v1/accounting_reports Create an accounting report
GET /v1/accounting_reports/{accounting_report_id} Retrieve an accounting report

This report contains all the accounting operations affecting your balance for a given date range (i.e. payments, refunds, chargebacks, invoices, and transfers to your bank account).

The accounting report object

Object attributes:

Key Description
id string The accounting report’s unique identifier.
object string Value is: accounting_report.
is_live boolean true for an accounting report in LIVE mode, false in TEST mode.
temporary_url string The URL to download your accounting report file from once it’s available.
file_available_until timestamp End date of your accounting report file’s availability. Note that files are available for 24 hours after their creation.
start_date date (ISO 8601) Your report’s start date. The report will cover all operations from the beginning of that day (UTC).
end_date date (ISO 8601) Your report’s end date. The report will cover all operations until the end of that day (UTC).
notification_url string optional The URL PayPlug will send a notification to.

Create an accounting report

The accounting report creation and download is an asynchronous, two-step process:

Parameters:

Create an accounting report:

$ curl -X POST https://api.payplug.com/v1/accounting_reports \
  -H 'Authorization: Bearer sk_test_9898098098guGYUG9' \
  -H 'PayPlug-Version: 2019-08-06' \
  -H 'Content-Type: application/json' \
  -d '{
  "start_date": "2019-11-08",
  "end_date": "2020-04-15",
  "notification_url": "https://example.net/notifications?id=42"
     }'
<?php
$data = array(
    'start_date' => '2019-11-08',
    'end_date' => '2020-04-15',
    'notification_url' => 'https://example.net/notifications?id=42'
  );
$report = \Payplug\AccountingReport::create($data);
$report_id = $report->id;
data = {
    "start_date": "2019-11-08",
    "end_date": "2020-04-15",
    "notification_url": "https://example.net/notifications?id=42"
}
report = payplug.AccountingReport.create(**data)
report_id = report.id

Example response:

{
  "object": "accounting_report",
  "id": "ar_6zrx929ldfIzqnX6KktHzZ",
  "is_live": true,
  "temporary_url": null,
  "file_available_until": null,
  "start_date": "2019-11-08",
  "end_date": "2020-04-15",
  "notification_url": "https://example.net/notifications?id=42"
}
Key Description
start_date date (ISO 8601) required Your report’s start date. The report will cover all operations from the beginning of that day (UTC).
end_date date (ISO 8601) required Your report’s end date. The report will cover all operations until the end of that day (UTC).
notification_url string optional The URL PayPlug will send a notification to.

Retrieve an accounting report

Retrieve an accounting report:

$ curl -X GET https://api.payplug.com/v1/accounting_reports/ar_6zrx929ldfIzqnX6KktHzZ \
  -H 'Authorization: Bearer sk_test_9898098098guGYUG9' \
  -H 'PayPlug-Version: 2019-08-06'
<?php
$report = \Payplug\AccountingReport::retrieve('ar_1GKEACvltTVXT5muBd3AQv');
report = payplug.AccountingReport.retrieve('ar_1GKEACvltTVXT5muBd3AQv')

Example response:

{
  "object": "accounting_report",
  "id": "ar_6zrx929ldfIzqnX6KktHzZ",
  "is_live": true,
  "temporary_url": "some_url_to_get_the_file.com",
  "file_available_until": 156787686,
  "start_date": "2019-11-08",
  "end_date": "2020-04-15",
  "notification_url": "https://example.net/notifications?id=42"
}

Retrieve an accounting report you previously created, using its unique identifier.

The request will return an accounting report object if the ID provided is valid, and an error object otherwise.

You will be notified once the accounting report has been generated and is ready to be retrieved.

If you are using one of our libraries and the notification management system to handle notifications, the retrieving call will be automatically handled when the notification management system receives the notification and you won’t have to send the GET request to download the report.

URL arguments:

Key Description
accounting_report_id ID of the accounting report to be retrieved.

The accounting report file

The accounting report file itself comes as a CSV file with headers, utf-8 encoded, with a “,” separator, and contains the fields described below.

File content:

Key Description
ID integer The operation ID, example: 1325565.
Transaction Date datetime Date of the operation in UTC, formatted as “YYYY-MM-DD HH:MM:SS”.
Processing Date datetime Processing date in UTC, formatted as “YYYY-MM-DD HH:MM:SS”.
Channel string The payment channel. Can be "Online", "Point of Sale" or "Oney"1.
Type string  The operation type. Can be one of "Payment", "Refund", "Transfer", "Invoice", "Reconciliation".
Description string A description of the operation.
Amount (€) float Operation amount, in cents.
Variable fee excl. VAT (%) float Variable fee percentage per transaction.
Fixed fee excl. VAT (€) float Fixed fee per transaction, cents.
Total fees excl. VAT (€) float Addition of variable and fixed commission, cents.
Gross balance (€) float Your balance after this operation, in cents.
Email string The payer’s email1.
First name string The payer’s first_name1.
Last name string The payer’s last_name1.
Metadata json The metadata sent when creating this operation1.
API ID json The API payment or refund id1.
Processing ID string The operation ID, example: "A3194719130".
Store string The name of the point of sale2.
Terminal ID string The terminal identifier2.

1: Value is null if the operation is not a payment or a refund.
2: Field is only present if your account is set up for POS payments. If present, its value is null if the operation is not a POS payment.

Accounting report notifications

Notification management example:

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

  if ($resource instanceof \Payplug\Resource\AccountingReport
    && $resource->temporary_url
    ) {
    // Get the accounting report file from
    // $resource->temporary_url and process it.
  }
}
catch (\Payplug\Exception\PayplugException $exception) {
  // Handle errors
  }
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 == 'accounting_report' and resource.temporary_url:
    # Get the accounting report file from
    # resource.temporary_url and process it.

Object example:

{
  "object": "accounting_report",
  "id": "ar_6zrx929ldfIzqnX6KktHzZ",
  "is_live": true
}

As mentioned earlier, accounting report generation is asynchronous. PayPlug will send you a notification (if you provided a notification_url at creation time) when the generation is completed.

If you are using one of our libraries and the notification management system, the retrieving call will be automatically handled when the notification management system receives the notification and you won’t have to send the GET request to download the report.

Object attributes:

Key Description
id string The accounting report’s unique identifier.
object string Value is: accounting_report.
is_live boolean true for an accounting report in LIVE mode, false in TEST mode.