Operations can be transactions received from clearing or internally generated operations ( e.g. fees, refund, chargeback...) that are posted on accounts.
Each Operation is identified by its unique operationId.
Several actions can be performed around account operations:
- list all operations posted on a given account and for a period of time by using the API to List operations for an account
- retrieve the detail of one operation
- post/reverse an operation on an account, such as balance adjustment, fee, a payment operation, a reimbursement operation, a Bonus operation, load/unload operation
List Operations For An Account
The API retrieves the list of operations for a given time period and a given account.
The main input fields are:
- The issuer ID
- The account for which information is requested: it can be provided by using the account reference or the issuer external account reference
- A given time period (start date / end date)
It is also possible
- to request the list of operations for all account hierarchy, for a certain PAN only by providing a PAN reference
- to include internal operations (failed and rejected operations) in the statements
- to exclude sub-operations generated during the payment (manual or automatic) / reimbursement apportionment on accounts)
Operations can be a scheme transaction or an operation generated internally.
In addition to the account and the period, it is possible to request the list of operations for all account hierarchy. The number of operations provided back can be indicated in the page and offset input field.
The API returns the most important operation attributes such as: the operation type, the amounts and the operation context.
For the full list of operation attributes, the "Retrieve operation" API should be used.
API links
Below an example where the list of operations is requested for:
- the issuer 1234
- the account 12343571015282598154
- the period: startTime=2022-12-05T09:35:00 &endTime=2022-12-06T00:00:00
In response, 2 operations are provided back:
- a transaction coming from the scheme
- and the corresponding transaction fee
GET /api/v2/issuers/1234/accounts/12343571015282598154/operations?offset=100&page=0&allAccountHierarchy=true&startTime=2022-12-05T09:37:00Z&endTime=2022-12-06T00:00:00Z
Response data
{
" ""data":" "[
" "{
" ""issuerId":" ""1234",
" ""operationIdentifier":" "{
" ""operationId":" ""1000000000354873"" "
},
" ""acquirerReferenceData":" ""74929322339221205103725",
" ""cardAcceptorCity":" ""SINAGAWAKU",
" ""cardAcceptorCountry":" ""392",
" ""cardAcceptorName":" ""RYOKAN-HOTEL IN JAPAN C-R",
" ""description":" ""RYOKAN-HOTEL IN JAPAN C-R SINAGAWAKU 392",
" ""externalOperationCode":" ""1035",
" ""maskedPan":" ""454617******1630",
" ""merchantCategoryCode":" ""7011",
" ""operationCode":" ""NORMAL_PURCHASE",
" ""operationKind":" ""TRN",
" ""postingDate":" ""2022-12-05T09:37:27.670+00:00",
" ""reconciliationAmount":" "{
" ""value": 5509,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""referenceAmount":" "{
" ""value": 5509,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""reversal":" false",
" ""transactionAmount":" "{
" ""value": 8335,
" ""exponent": 0,
" ""isoCode":" ""JPY"" "
},
" ""transactionDate":" ""2022-12-04T23:00:00.000+00:00",
" ""valueDate":" ""2022-12-04T23:00:00.000+00:00",
" ""cardIdentifier":" "{
" ""cardReference":" ""2000000000356059"" "
},
" ""externalOperationDate":" ""2022-12-05T09:37:27.644+00:00",
" ""externalOperationReference":" ""10000000000264127",
" ""externalOperationServicePoster":" ""ITP",
" ""pan":" ""4546172396081630",
" ""acquisitionMaterial":" ""POS",
" ""cardAcceptorIdCode":" ""2722713868",
" ""entryMode":" ""MAGSTRIPE",
" ""approvalCode":" ""103725",
" ""pointOfSaleEnvironment":" "" ",
" ""mailPhoneEcommerceAndPaymentIndicator":" "" "" "
},
" "{
" ""issuerId":" ""1234",
" ""operationIdentifier":" "{
" ""operationId":" ""1000000000354874"" "
},
" ""description":" ""1.99 Auslandseinsatzentgelt",
" ""externalOperationCode":" ""1287",
" ""feeType":" ""MARKUP_FEE",
" ""operationKind":" ""FEE",
" ""postingDate":" ""2022-12-05T09:37:27.670+00:00",
" ""referenceAmount":" "{
" ""value": 110,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""reversal":" false",
" ""transactionAmount":" "{
" ""value": 110,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""valueDate":" ""2022-12-04T23:00:00.000+00:00",
" ""externalOperationDate":" ""2022-12-05T09:37:27.721+00:00",
" ""externalOperationReference":" ""8561d87e285d4fc795778c644579c207",
" ""externalOperationServicePoster":" ""WLP-CAS"" "
}" "
]
}Retrieve Operation For An Account
The API retrieves the details of an operation for an account. It is also possible to request explicitly the operations linked to the current account by using the embedded field filled with parentOperation. A parent operation can be: the original operation when the requested operation is a reversal, relative fee operations linked to the current operation, refund/redebit operations for disputed transaction.
In response, exhaustive information is returned, including additional amounts if available (cash-back amount, DCC amount, gratuity amount, surcharge amount), exchange rate information.
API links
Below is an example where the requested operations is for:
- the issuer 1234
- the account 12343571015282598154
- the operation reference: 1000000000354873
In response, some additional fields are retrieved (e.g.,: exchange rate).
GET /api/v2/issuers/1234/accounts/12343571015282598154/operations/1000000000354873
Response data
{
" ""data":" "{
" ""issuerId":" ""1234",
" ""operationIdentifier":" "{
" ""operationId":" ""1000000000354873"" "
},
" ""acquirerReferenceData":" ""74929322339221205103725",
" ""cardAcceptorCity":" ""SINAGAWAKU",
" ""cardAcceptorCountry":" ""392",
" ""cardAcceptorName":" ""RYOKAN-HOTEL IN JAPAN C-R",
" ""description":" ""RYOKAN-HOTEL IN JAPAN C-R SINAGAWAKU 392",
" ""externalOperationCode":" ""1035",
" ""maskedPan":" ""454617******1630",
" ""merchantCategoryCode":" ""7011",
" ""operationCode":" ""NORMAL_PURCHASE",
" ""operationKind":" ""TRN",
" ""postingDate":" ""2022-12-05T09:37:27.670+00:00",
" ""reconciliationAmount":" "{
" ""value": 5509,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""referenceAmount":" "{
" ""value": 5509,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""reversal":" false",
" ""transactionAmount":" "{
" ""value": 8335,
" ""exponent": 0,
" ""isoCode":" ""JPY"" "
},
" ""transactionDate":" ""2022-12-04T23:00:00.000+00:00",
" ""valueDate":" ""2022-12-04T23:00:00.000+00:00",
" ""cardIdentifier":" "{
" ""cardReference":" ""2000000000356059"" "
},
" ""externalOperationDate":" ""2022-12-05T09:37:27.644+00:00",
" ""externalOperationReference":" ""10000000000264127",
" ""externalOperationServicePoster":" ""ITP",
" ""pan":" ""4546172396081630",
" ""acquisitionMaterial":" ""POS",
" ""cardAcceptorIdCode":" ""2722713868",
" ""entryMode":" ""MAGSTRIPE",
" ""approvalCode":" ""103725",
" ""pointOfSaleEnvironment":" "" ",
" ""mailPhoneEcommerceAndPaymentIndicator":" "" ",
" ""adjustment":" false",
" ""brand":" ""VISA",
" ""cardAcceptorZipCode":" ""00000",
" ""cardScheme":" ""VIS",
" ""cardTypeCode":" ""F",
" ""debit":" true",
" ""exchangeRate": 0.007087,
" ""operationDate":" ""2022-12-05T09:37:27.644+00:00",
" ""partialOperation":" false",
" ""status":" ""PROCESSED",
" ""validationMode":" ""UNKNOWN",
" ""postingAccountIdentifier":" "{
" ""accountReference":" ""12343571015282598154"" "
},
" ""productIdentifier":" "{
" ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC_SHARE",
" ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC_SHARE"" "
}" "
}
}Post A Fee Operation For An Account
There is a high degree of flexibility regarding fee management.
Fee management can be done fully by Worldline or split between Worldline and the issuer (typically, the bank can manage subscription fees while WL would keep handling transaction fees). The API is used to post a fee operation to an account.
The fee type is mandatory, and the value must be consistent with the list defined during product definition. This list is shared between WL and the issuer during the project phase.
As an input, the account identifier can be provided by using:
- the account reference generated by WL
- or the issuer external account reference
Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once. The response will be retrieved directly from our system.
API links
Below an example of request with the response for the:
- Account: 12349485785398617383
- Issuer: 1234
POST /api/v2/issuers/1234/accounts/12349485785398617383/post-fee-operation
Request data
{
" ""description":" ""Manual fee description",
" ""externalOperationReference":" ""1234F123456",
" ""externalOperationDate":" ""2023-01-02T14:20:34.715Z",
" ""externalOperationServicePoster":" ""ISSUER",
" ""feeType":" ""MANUAL_FEE",
" ""referenceAmount":" "{
" ""value": 1500,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""valueDate":" ""2023-01-02T00:00:00.000Z"
}Response data
{
"responseMetadata":" "{
" ""correlationId":" ""b91d2d16-9fe2-42fb-a4ab-cc3f74a6ba31",
" ""statusMessage":" ""Executed successfully",
" ""statusCode": 200,
" ""responseDateTime":" ""2023-01-02T15:25:44.444+0100",
" ""timeTakenMs": 343
},
" ""data":" "{
" ""operationIdentifier":" "{
" ""operationId":" ""1000000000376077"" "
}" "
}
}Reverse A Fee Operation For An Account
The API is used to reverse a fee operation on an account.
As an input, the account identifier can be provided by using:
- the account reference generated by WL
- or the issuer external account reference
The fee type is mandatory. It must be consistent with the product definition. The list of values is shared between WL and the issuer.
The fee reference to be reversed must be provided.
Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once. The response will be retrieved directly from our system.
API links
Below an example of request with the response for the:
- Account: 12349485785398617383
- Issuer: 1234
POST /api/v2/issuers/1234/accounts/12349485785398617383/reverse-fee-operation
Request data
{
"reversalReason":" ""REVERSAL_ON_DEMAND",
" ""description":" ""reversal description",
" ""externalMatchingOperationReference":" ""1234F123456",
" ""externalMatchingOperationDate":" ""2023-01-02T14:20:34.715Z",
" ""externalMatchingOperationServicePoster":" ""ISSUER",
" ""referenceAmount":" "{
" ""value":-1500,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""externalOperationReference":" ""1234R123456",
" ""externalOperationDate":" ""2023-01-02T14:56:16.402Z",
" ""externalOperationServicePoster":" ""ISSUER"
}Response data
{
"responseMetadata":" "{
" ""correlationId":" ""83cc5b32-681a-449e-8cac-21c0c40bf8bd",
" ""statusMessage":" ""Executed successfully",
" ""statusCode": 200,
" ""responseDateTime":" ""2023-01-02T16:01:31.184+0100",
" ""timeTakenMs": 196
},
" ""data":" "{
" ""operationIdentifier":" "{
" ""operationId":" ""1000000000376078"" "
}" "
}
}List Authorizations For A Given Account
This operation enables a list of authorizations associated with an account to be retrieved for a given period.
In response, for each authorization, the main properties of the authorization are provided such as the type of operation, the amount, the result code, the acceptance context.
API links
get Authorizations
Retrieve Authorization Detail For A Given Transaction Id
This operation enables the details of an authorization, identified by its transaction Id, to be retrieved.
API links
Retrieve Authorization detail by Authorization ID
Retrieve Authorization Detail For A Given Business Case Id
This operation enables the details of an authorization, identified by its business case Id, to be retrieved.
An authorization business case corresponds to a group of authorization messages; it can refer to one or several consecutive Authorizations (for example, a reservation in a hotel with a subsequent confirmation, or a purchase with a subsequent cancellation).
Each Authorization Business Case is identified by its unique businessCaseId.
The issuer can Retrieve an Authorization Business Case details using the GET /issuers/{issuerId}/accounts/{accountReference}/authorization-business-cases/{businessCaseId} API, by providing the issuerId of the Issuer, the accountReference identifying the Account and the businessCaseId identifying the Authorization Business Case.
API links
Retrieve Authorization detail by business case ID
List Business Cases For A Given Account
This operation enables the list of business Cases to be retrieved by providing in input the account reference (internal or external).
API links
Retrieve business cases
Post a Bonus Operation for an Account
The API is used to post manually a Bonus operation to an account.
A Bonus operation is used to reward or adjust a given account (in credit or in debit, e.g. in case of too high, too low or missing reward).
As an input it must be provided
- the account, identified either by its account reference generated by WL or its issuer external account reference, on which the bonus operation has to be posted
- the related Bonus program, defined for the issuer and the account
- the Bonus operation itself, uniquely identified by its external reference, date and service poster, its amount in currency (monetary) or loyalty point kind (non-monetary)
Note:
- for monetary bonus the provided currency must be the same than the posting account, for non monetary bonus the provided loyalty point unit must be allowed by the Bonus program
- it is possible to post credit and debit bonus operation
If the Bonus operation is related to an existing initial operation, this latter can be provided.
Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once. The response will be retrieved directly from our system.
As a result the Bonus operation is posted to the account. Monetary bonus has an immediate impact on the account balance.
API links
Reverse a Bonus Operation for an Account
The API is used to fully reverse a Bonus operation previously posted on an account.
As an input it must be provided
- the account, identified either by its account reference generated by WL or its issuer external account reference, on which the bonus operation was previously posted
- the Bonus operation to be reversed
- the information related to the reversal operation (reference, date, service poster)
Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once. The response will be retrieved directly from our system.
API links
Post an Interest Operation for an Account
The API is used to post manually an interest operation to an account.
As an input it must be provided
- the account, identified either by its account reference generated by WL or its issuer external account reference, on which the interest operation has to be posted
- the interest operation itself, uniquely identified by its external reference, date and service poster, its amount in currency (monetary)
Note:
- the provided currency must be the same than the posting account
- it is possible to post credit and debit interest operation
Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once. The response will be retrieved directly from our system.
As a result, the interest operation is posted to the account and has an impact on the account balance, immediately or not depending on the provided value date.
API links
Reverse an Interest Operation for an Account
The API is used to fully reverse an interest operation previously posted on an account.
As an input it must be provided
- the account, identified either by its account reference generated by WL or its issuer external account reference, on which the interest operation was previously posted
- the interest operation to be reversed
- the information related to the reversal operation (reference, date, service poster)
Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once. The response will be retrieved directly from our system.
API links
Retrieve operations by criteria (Global)
The API provides possibility to retrieve a list of operations for one or several accounts and for one or several contracts, based on certain criteria. The criteria used are the following:
- 1st Group:
- Issuer Company External Reference
- Posting Account Identifier
- Virtual Service Card External Reference
- Virtual Service Card Number
- 2nd Group:
- Transaction date range
- Posting date range
- 3rd Group:
- Reference amount range
- Approval Code
- Card Acceptor Name. this criteria accepts wildcards ('%' allows to achieve a search with only a partial input, 'Plat%', '%hill', 'Al%gang')
- Operation Kinds
The rules of using this API and criteria for searching, are the following:
- It will be mandatory to provide at least one of criteria from 1st Group. It is possible to provide two or three criteria at the same time. Virtual Service Card Number and Virtual Service Card External Reference can not be provided at the same time
- It will be mandatory to provide one criterion from 2nd Group. The two criteria can not be provided at the same time
- All Criteria in 3rd Group are optional
- Regarding Criteria that will include ranges, both minimum and maximum values should be provided
API links
Retrieve an operation by external references triplet
This API allows retrieving for an account a particular operation from its external references.
The main input fields are:
- The issuer ID
- The account reference or the issuer external account reference
- The external references of the operation for which the detail is requested: The triplet (externalOperationDate, externalOperationReference, externalOperationServicePoster) uniquely identifying the operation in our system must be provided.
The API response contains operation information.
API links