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:

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

Notifications

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

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

Notifications content

Example:

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

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

Object attributes:

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:

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

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

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:

Card number, expiration, amount and CVC are set correctly
Error messages from the API are handled and displayed correctly
Sensitive information about the cards (number and CVC) are not stored on your server
All information and values related to payments sent to the API are valid and correctly formatted
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:

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

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

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

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

Oney payments are supported starting from version 2019-08-06 of our API. For more information on how to use a specific version of our API, see the Version section of this documentation.

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:

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

Retrieve a payment

Example:

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

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

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

Example response:

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

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

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

URL arguments:

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.

The capture will fail if the authorization has expired. Monitor the field authorization.expires_at to know when the payment expires. A payment expires 7 calendar days after its authorization.

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.

The first payment using save_card = true and allow_save_card = true will automatically activate the 3-D Secure.

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

Pay with a saved card

Create a payment with the card ID:

$ curl -X POST https://api.payplug.com/v1/payments \
  -H 'Authorization: Bearer sk_test_9898098098guGYUG9' \
  -H 'PayPlug-Version: 2019-08-06' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 1000,
    "currency": "EUR",
    "payment_method": "card_e7133426b8de947b37161dfba1897dd1",
    "initiator": "PAYER",
    "billing": {
      "title": "mr",
      "first_name": "John",
      "last_name": "Watson",
      "email": "john.watson@example.net",
      "address1": "221B Baker Street",
      "postcode": "NW16XE",
      "city": "London",
      "country": "GB",
      "language": "en"
    },
    "shipping": {
      "title": "mr",
      "first_name": "John",
      "last_name": "Watson",
      "email": "john.watson@example.net",
      "address1": "221B Baker Street",
      "postcode": "NW16XE",
      "city": "London",
      "country": "GB",
      "language": "en",
      "delivery_type": "BILLING"
    }
  }'

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

payment_data = {
  'amount': 1000,
  'currency': 'EUR',
  'payment_method': 'card_e7133426b8de947b37161dfba1897dd1',
  'initiator': 'PAYER',
  'billing': {
    'title': 'mr',
    'first_name': 'John',
    'last_name': 'Watson',
    'email': 'john.watson@example.net',
    'address1': '221B Baker Street',
    'postcode': 'NW16XE',
    'city': 'London',
    'country': 'GB',
    'language': 'en'
  },
  'shipping': {
    'title': 'mr',
    'first_name': 'John',
    'last_name': 'Watson',
    'email': 'john.watson@example.net',
    'address1': '221B Baker Street',
    'postcode': 'NW16XE',
    'city': 'London',
    'country': 'GB',
    'language': 'en',
    'delivery_type': 'BILLING'
  },
  'notification_url': 'https://example.net/notifications?id=42',
  'metadata': {
    'customer_id': 42,
  },
}
payment = payplug.Payment.create(**payment_data)

Example response:

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

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

In other words, you have to set initiator to:

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

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

billing.first_name
billing.last_name
billing.email

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

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

Payment notifications

Example:

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

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

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

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.

The amount_refunded attribute in the payment object indicates how much has been refunded.

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.

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

Implementations:

Product and Cart Page.
Checkout page.

Product and Cart Pages

Here are the steps we will follow.

Add the Apple Pay button.
How to retrieve the merchant validation:
1. Create a request.
2. Retrieve the merchant validation.
Validate biometrics (payment).
Update delivery information.
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 operation¹.
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

Review our Oney acceptance criteria (FR - IT) to verify your eligibility.
Signup for a PayPlug account if you don’t already have one and subscribe to a PayPlug offer that includes Oney (FR - IT).
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:

Pending Oney - Oney is reviewing the payment
Failure - Oney deems the payer untrustworthy and refuses the payer’s request
Authorized - Oney has accepted the payer’s request

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:

Installments “with fees” (oney_x3_with_fees, oney_x4_with_fees), for which fees are applied to the payer.
Installments “without fees” (oney_x3_without_fees, oney_x4_without_fees), for which the payer pays no additional fees. For such payments, fees are effectively reported to the merchant through their PayPlug bills. Check out your PayPlug offer to compare fees for Oney payments with or without fees.

The *_with_fees or *_without_fees terminology used by the API indicates whether the payer pays fees or not.

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:

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.
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.
Make sure that you fill in the parameters specific to Oney.
Redirect the payer to the payment_url of the payment resource.
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:
- Get the payment resource when the payer is redirected to your return_url (or cancel_url if the payer has abandoned the transaction).
- Get the payment resource once the notification has been posted to your notification_url
Once the payment has been authorized by Oney, you can capture it

When creating a payment, you can set the parameter auto_capture to True in order for a payment to be automatically captured as soon as it is authorized. This can come in handy for Oney payments which can switch from a pending state to an authorized state at any time. If you do enable auto-capture for a payment, then you will receive two notifications in a row about the payment: the first one because it has been authorized, and the second one because it has been paid.

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:

Authorized: Oney has accepted the payer’s file. In this case, both fields authorization and authorized_at can be found in the payment resource.
Failure: Oney has rejected the payer’s file. In this case, the field failure is not null in the payment resource.
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:

How the total amount of the payment will be split between each installment
When each payment will take place

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:

A down payment of 676.67€ - first third of the payment + the 10€ fee paid to Oney
A charge of 666.67€ one month later
And a final charge of 666.66€ two months later

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:

American Express
Bancontact
Giropay
iDeal
MyBank
Satispay
Sofort

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
}

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.
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.
Redirect the payer to the payment_url of the payment resource.
Once generated, you can check the payment status by implementing one (or both) of the following:
- Get the payment resource when the payer is redirected to your return_url (or cancel_url if the payer has abandoned the transaction).
- Get the payment resource once the notification has been posted to your notification_url

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:

Giropay
iDeal
MyBank
Satispay
Sofort

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:

Create an accounting report object with the parameters below. You will immediately receive an answer to confirm the success of the call and the beginning of the accounting report generation process.
You will be notified when the accounting report is completed (see the notification section) on the URL you provided when creating the object. To retrieve the accounting report, use the retrieve an accounting report endpoint. The retrieving call will be automatically sent if you used one of our libraries to create the accounting report.

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"`¹.
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 email¹.
First name string	The payer’s first_name¹.
Last name string	The payer’s last_name¹.
Metadata json	The metadata sent when creating this operation¹.
API ID json	The API payment or refund id¹.
Processing ID string	The operation ID, example: `"A3194719130"`.
Store string	The name of the point of sale².
Terminal ID string	The terminal identifier².

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.