Operations

• Introduction
• Card information request
• Payment
• Authorization
• Capture
  • Scheduled capture
• Refund
• Credit and Credit Fund Transfer
• Void
• N-times payment
• Stop n-times
• Recurring payment
  • Basic usage
  • Oneclick with CVV
  • Hosted-form option

Introduction

Each Payplug platform’s operation return a couple EXECCODE MESSAGE to describe the result of the operation.

In case of a valid request, a TRANSACTIONID is returned.

tips

Make sure to store in your system the TRANSACTIONID for later usage (refund, capture, support requests, matching … ).

warning

Keep in mind that it is not allowed to launch multiple editing transactions at the same moment (concurrent accesses), (such as refunds or captures…) on the same initial transaction. This would result in a refusal to process these operations and an EXECCODE = 2017

Please note that not all of the operations listed below are available on all payment methods and integration modes.

Card information request

To simply get information about the user’s card, you can proceed an authorization operation by setting the AMOUNT parameter to 0.

This operation makes it possible to check the card information (PAN, expiry, cryptogram) without any impact on the end user payment limits.

info

In case the amount of the request is zero, the AUTHORIZATIONTYPE parameter is useless and would be ignored.

info

Card information requests cannot be captured or voided.

tips

For card registration, please refer to the recurring payment section.

The transaction return will contain some useful information as :

Payment

The payment operation is the simplest action available on the Payplug platform.

It simply consists in requesting to debit a user of the amount you specify.

Authorization

This operation makes it possible to hold the transaction’s amount on the cardholder bank account, for later collection triggerable with a capture operation.

info

An authorization can only be captured once.

warning

Some payment methods require you to capture an authorization within a limited timeframe. The expiration delay of an authorization depends on the payment method and its regulations. The standard timeframe is 7 calendar days.

Capture

The capture operation requires a valid TRANSACTIONID from a previous, succeeded and still not captured transaction. A single authorization does not affect the user account until you decide to capture it. The authorization / capture workflow is well suited for delayed payment scenario.

warning

Some payment methods authorize a partial capture of an authorization. To do so, just add the optional AMOUNT parameter to your capture request.
When not specified, 100% of the authorization amount is captured.
AMOUNT cannot be higher than the initial authorization amount.

info

An authorization can only be captured once.

warning

Some payment methods require you to capture an authorization within a limited timeframe. The expiration delay of an authorization depends on the payment method, its regulations and AUTHORIZATIONTYPE.

reminder

• finalauthorization can be captured after 6 calendar days (limit = 23h59 UTC+1).
• preauthorization can be captured within 29 calendar days (limit = 23h59 UTC+1).
• If you exceed those deadlines, you can be subject to fines from the schemes.

Scheduled capture

A capture can be planned ahead by adding the parameter CAPTUREDATE to your initial authorization request.

info

A manual capture, (triggered by the merchant with a server to server request or via the Payplug Dashboard), cancels the configured CAPTUREDATE

info

The CAPTUREDATE parameter must at least refer to the next day.

info

The schedule is configured on the Paris-Madrid timezone.

Refund

A refund operation enables you to credit funds back to a end-user following a previous debit.

A refund transaction is always linked to a successsful payment or capture transaction which it requires the original TRANSACTIONID.

The amount of a refund transaction can be different from the original debit transaction but can not be higher.

You can refund several times a same debit transaction, but the sum of all the refund operations can’t be higher that the original debit amount.

A refund transaction has an impact on the user’s bank account since he will see the funds being credited on his bank statement.

warning

A refund can only be done on an operation being less than 2 years old and in some international cases even limited on operations being less than 1 year old (please contact the technical support for more details). If a refund is made after this delay, the risk of rejection is important

Credit and Credit Fund Transfer

A credit transaction is a special transaction type allowing to give money to the user.

This transaction type should be used in some very special cases (custom refund situations …).

info

credit transaction are not allowed to all customers by default. You have to contact your account manager to validate the usage conditions and to activate this feature.

If your activity is related to gambling, all your credit operations will be processed as Credit Fund Transfer operation (CFT).

The only technical difference with a standard credit transaction is that you have to provide a reference TRANSACTIONID of a succeeded and authenticated transaction (3DSECURE).

Void

This operation can be used to cancel the very last operation of any transaction. (Except the void operation itself, of course)

For example, once captured, an authorization cannot be voided, only the capture could be.

All transactions except authorizations can only be voided on the same day they are processed, that is to say before the funds are sent for compensation to the user’s bank.

An authorization can be voided for the duration of its lifetime as long as it has not been captured.

N-times payment

It is possible to easily split a payment in several installments. The Payplug platform will process the first installment immediately and in case of acceptation of the first installment, the platform will process the following installments at the given dates. All these installments will result in different transactions sharing the same ORDERID field as the one in the first installment.

To initiate a split payment, you have to replace the AMOUNT parameter by:

For example, an AMOUNTS for a 3 installments split:

• 200€ on 2024-10-28
• 100€ on 2024-11-28
• 100€ on 2024-12-29

AMOUNTS[2024-10-28]=20000&AMOUNTS[2024-11-28]=10000&AMOUNTS[2024-12-29]=10000

A n-times transaction must follow these conditions:

• The time-zone you must use for any n-times transaction is UTC.
• The first installment must be on the day of the request and will be executed immediately.
• The interval between the first and last installment must not exceed 90 days.
• The last installment must occur before the card’s expiry date.

info

• Only payment transactions can be split with n-times mode.
• If the first transaction is refused, the other scheduled transactions won’t be processed, the whole request is considered as refused
• Schedule dates should be supplied in UTC format.

tips

AMOUNT and AMOUNTS can not be used at the same time.

The first TRANSACTIONID of a n-times schedule will be the schedule reference: SCHEDULEID.

We can configure automatic retries for each installments. To enable and configure this feature, please contact your payment manager.

N-times schedule can be canceled by using the stopntimes operation.

Stop n-times

This operation is used to abort forthcoming installments of an n-times transaction, by providing its SCHEDULEID:

info

Please note that the past installments won’t be refunded with this operation, you must use classic refund operation to refund each installment.

Recurring payment

Basic usage

It is possible to implement tailor-made recurring payment workflows without storing any sensitive card data by simply using our aliasing features.

You have to add 2 parameters in your payment, authorization or credit initial request.

In the request’s direct response, as well as redirection and notification, you will retrieve the parameter ALIAS:

This parameter is a non-sensible reference for the used payment method in our platform. You have to store and keep this reference in your database for later use.

For each recurring transaction processed on the same ALIAS for the same user on the same payment method, you don’t need to provide the usual payment method details (ie: CARDCODE, CARDVALIDITYDATE, CARDCVV, CARDFULLNAME):

warning

In case of execcode 4018, fees could be applied for each new transaction attempt.

Example

Here is a server to server request example:

$> curl --request POST --url "https://secure-test.dalenys.com/front/service/rest/process" \
--data "method=payment" \
--data "params[IDENTIFIER]=Demo Shop" \
--data "params[OPERATIONTYPE]=payment" \
--data "params[ORDERID]=1234" \
--data "params[ALIAS]=A1-fc5bafe3-8c12-4314-95c7-2e15ec3220e0" \
--data "params[ALIASMODE]=oneclick" \
--data "params[AMOUNT]=1000" \
--data "params[CLIENTIDENT]=john.snow" \
--data "params[CLIENTEMAIL]=john.snow@example.com" \
--data "params[CLIENTUSERAGENT]=Mozilla/5.0 (Windows NT 6.1; WOW64; rv:47.0) Gecko/20100101 Firefox/47.0" \
--data "params[CLIENTIP]=10.1.1.1" \
--data "params[CARDFULLNAME]=JOHN SNOW" \
--data "params[DESCRIPTION]=Knows nothing" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \
--data "params[VERSION]=3.0" \

Oneclick with CVV

With ALIASMODE valued to oneclick you can optionally ask the user for the cryptogram and supply it in the recurring request (parameter CARDCVV). The cryptogram will be verified by the user’s bank to grant or deny the transaction.

The hosted-fields integration way of Oneclick transaction with CVV, allows you to implement a single CVV hosted-field.

security

Keep in mind that storing the cryptogram is forbidden.

Hosted-form option

In a hosted form integration, you can allow the user to choose to register to a recurring workflow or not by providing the parameter:

When this parameter is valued to true, the hosted form will display a check-box asking for granting Payplug the permission to store payment method data for easier later re-use.