Accept Transactions (v1.0.3)
This API enables you to Accept transactions for your Merchant customers.
Transactions are accepted via a host-to-host connection between the API user and Worldline FS API GateWay. The Worldline FS API GateWay is connected to the Worldline FS acceptance host, which in turn is connected to the Issuer network.
There is 1 POST Transaction request call and 1 POST Transaction request response field set.
How to use acceptance actions?
Each POST transaction request actionType is a partial on the full Transaction request field set. The POST Transaction request mandatory parameters depend on the actionType the user is requesting as explained in the specifications.
A valid POST transaction request must include:
- the unique actionId in UUID format;
- the minimum mandatory fields to perform a basic actionType (AUTH, CAPTURE etc.) for the service (e.g. Account Verification, Purchase, Refund);
- if applicable, include Additional data (e.g. Card-On-File, MCC specifics such as Additional Merchant data and Airline Addendum..).
A follow-up action such as a CAPTURE must also include the transactionId (lifecycle) returned by the Worldline FS host in the approved initial authorization (AUTH and PREAUTH actionType) request response. Exception is a technical reversal (e.g. timeout) as explained in actionType AUTH_REVERSAL where only the originalActionId is available.
The illustration below shows examples of a happy flow (resulting in a paid transaction) from the POST Transaction in Accept Transactions API through the various transactionStates in the GET Transactions API.
Flow actions and transactionStates in APIs
For Purchase and Refund services available actions are:
- AUTH
- AUTH_REVERSAL
- CAPTURE
- AUTH_AND_CAPTURE
- CAPTURE_SPLIT (partial capture)
Actions under development are:
- PREAUTH
- AUTH_REVERSAL_PARTIAL
- AUTH_INCREMENTAL
Actions on the roadmap are:
- AUTH_UPDATE
- PAYOUT (OCT)
actionType definitions
actionType | definition |
| AUTH | The Authorization (final) message reserves the cardholder amount with Issuer bank. |
| AUTH_REVERSAL | This is used to release the funds RESERVED on the cardholders’ account as a result of an APPROVED AUTHORIZATION. You must not use this follow-up action (operation) if you have already sent a CAPTURE on the transaction. |
| PREAUTH | A PREAUTH reservation at Issuer bank is made when the final purchase amount is not yet known. Example is the amount reserved at hotel check-in for 2 day stay, before mini-bar usage has been take into account. |
| AUTH_INCREMENTAL | Adjusts the pre-authorized amount up. An incremental is a pre-authorization exclusive follow-up action (operation) that can be sent if the final amount is higher than the previously pre-authorized amount. Later on when capturing the transaction you must specify the last correct amount. |
| AUTH_REVERSAL_PARTIAL | Adjusts the pre-authorized amount down. A partial reversal is a pre-authorization exclusive follow-up action (operation) that can be sent to reverse parts of the pre-authorized amount. |
| AUTH_AND_CAPTURE | This action type Triggers card Dual message actionTypes “AUTH” and “CAPTURE”. This action can be used for Service "Purchase" and Service “Refund”. For this action no cancellation is available. |
| AUTH_AND_CAPTURE_REVERSAL | This actionType triggers a technical reversal on an actionType AUTH_AND_CAPTURE for service "Purchase" or "Refund" e.g. in case of a time-out. Due to current limitations, this actionType always triggers in clearing a PRESENTMENT_REVERSAL. In case the PRESENTMENT and PRESENTMENT_REVERSAL are in the same clearing batch, they are not sent out to scheme. Alternately, idempotency can be used; this is on the API roadmap. |
| CAPTURE | In CNP a CAPTURE follow-up action (operation) needs to be sent in by the API user so that the Back Office can CLEAR the transaction. Note: In POS the HOST sends in the CAPTURE (Advice) after the terminal has sent in the COMPLETION action on a purchase so the Back Office can clear the transaction. There are time limits between the original action (operation) and the last capture that depends on whether the original action (operation) was an authorization or a pre-authorization: NOTE: VISA does not allow estimated amounts/incremental for all MCCs. Please consult the scheme rules for more information. |
| CAPTURE_SPLIT | A CAPTURE can be split into multiple partial CAPTURES e.g. in case the goods are delivered at multiple intervals in time. Each partial CAPTURE must contain the sequenceNumber. By the last partial CAPTURE it is mandated to send in the sequenceCount of the number of Partial Captures. |
Example transaction request actionType AUTH for Mastercard
{
"actionType": "AUTH",
"service": "Purchase",
"identification": {
"requestorId": "1157",
"actionId": "e9bd7129-7377-4d1a-9c91-5abdfeaba145",
"acquirerId": "315000001",
"cardAcceptorId": "90100110"
},
"financial": {
"requestAmount": {
"amount": "23.32",
"currency": "EUR"
}
},
"circumstance": {
"actionDateTime": "2022-07-28T13:06:12+02:00",
"channel": "ECommerce"
},
"acceptor": {
"merchantCategoryCode": "7999",
"name": "Home Festival",
"address": "Eendrachtslaan 315",
"postalCode": "3526LB",
"city": "Utrecht",
"state": "NL",
"countryCode": "NLD"
},
"card": {
"cardNumber": "5413330089600010",
"expiryDate": "2512"
},
"3DSecure": {
"result": "Full",
“dsTransactionId”: "4c754b56-c6c0-468b-bfc9-905ceab69618"
“version”: "V2"
“authenticationValue”: "lChDPlIS2WTc/PNfk0LoeYI/hYy="
“dsEci”: "02"
“subversion”: "2"
}
}
Disclaimer
The Open API specification is leading for integrations purposes. The Accept Transactions API documentation provides guidance on what is to be sent in for a particular transaction acceptance request (use case, action, brand, MCC, etc.).
The developer portal documentation does not provide a comprehensive set of rules and regulations on what request call body to send into the Accept Transactions API. To stay compliant and avoid data integrity issues, always consult the Card scheme processing rules. In addition, always consult your regulatory rules and regulations (for example consult the European Banking Authority websites for latest PSD II and SCA rules).