Operations
- Introduction
- Card information request
- Payment
- Authorization
- Capture
- Refund
- Credit and Credit Fund Transfer
- Void
- N-times payment
- Stop n-times
- Recurring payment
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 :
-
CARDCODE string(12-19)
A truncated version of the card number.
Example: 1111222233334444
-
CARDCOUNTRY string(2)
The country code (format ISO_3166-1_alpha-2).
Example: US
-
CARDFULLNAME string(1-255)
The holder’s full name (as described on the payment method). For 3-D Secure operations, the field CARDFULLNAME can only contain the following characters : [a-zA-Z1-9 -]
Example: JOHN SNOW
-
CARDNETWORK
VISA
,AMERICAN EXPRESS
,MASTERCARD
,BANCONTACT
,CB
,UNKNOWN
The cardholder’s bank card network.
Example:
-
CARDTYPE string
The payment method type.
Example: VISA
-
CARDVALIDITYDATE date(MM-YY)
Card expiry date. In case of Network Token Transaction, provide Network Token Expiration Date
Example: 12-17
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
anauthorization
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 anauthorization
. To do so, just add the optionalAMOUNT
parameter to yourcapture
request.
When not specified, 100% of theauthorization
amount is captured.AMOUNT
cannot be higher than the initialauthorization
amount.
info
An
authorization
can only be captured once.
warning
Some payment methods require you to
capture
anauthorization
within a limited timeframe. The expiration delay of an authorization depends on the payment method, its regulations andAUTHORIZATIONTYPE
.
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 configuredCAPTUREDATE
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 arefund
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:
-
AMOUNTS hash
A hash of keys / values where keys are dates and values are the amounts to process:
Dates have to be in format YYYY-MM-DD;
Amounts in the smallest money decimal (e.g. cents for euro);
See the dedicated section.Example: {#<Date: 2016-01-01 ((2457389j,0s,0n),+0s,2299161j)>=>50000, #<Date: 2016-02-01 ((2457420j,0s,0n),+0s,2299161j)>=>20000, #<Date: 2016-03-01 ((2457449j,0s,0n),+0s,2299161j)>=>10000}
For example, an AMOUNTS
for a 3 installments split:
- 200€ on 2024-10-07
- 100€ on 2024-11-07
- 100€ on 2024-12-08
AMOUNTS[2024-10-07]=20000&AMOUNTS[2024-11-07]=10000&AMOUNTS[2024-12-08]=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
andAMOUNTS
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.
-
ALIASMODE
oneclick
,subscription
Indicates the ALIAS usage mode:
oneclick
indicates a one click or an online transaction;
subscription
indicates an offline transaction.Example: oneclick
-
CREATEALIAS boolean
Ask for a payment method
ALIAS
creation. Caution: this parameter is mutually exclusive withDISPLAYCREATEALIAS
. See the dedicated section.Example: true
In the request’s direct response, as well as redirection and notification, you will retrieve the parameter ALIAS:
-
ALIAS string(1-40)
Identifier of a previously processed payment method.
Example: A1-fc5bafe3-8c12-4314-95c7-2e15ec3220e0
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
):
-
ALIAS string(1-40)
Identifier of a previously processed payment method.
Example: A1-fc5bafe3-8c12-4314-95c7-2e15ec3220e0
-
ALIASMODE
oneclick
,subscription
Indicates the ALIAS usage mode:
oneclick
indicates a one click or an online transaction;
subscription
indicates an offline transaction.Example: oneclick
-
INITIALSCHEMETRANSACTIONID string(1-55)
Card scheme transaction identifier (Mastercard Trace-ID or Visa Transaction ID). Submit the original scheme transaction ID of the initial recurring payment. If provided by the card scheme, the original scheme transaction ID will be returned in the transaction notification in “SCHEMETRANSACTIONID” field.
Example: 2MCGNM21OX0729
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:
-
DISPLAYCREATEALIAS boolean
Display a checkbox on the hosted form to ask the user to save his card data for future usage. Caution: this parameter is mutually exclusive with
CREATEALIAS
. See the dedicated section.Example: true
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.