This API allows you to provide detailed transaction data to your merchant customers. The API enables you to retrieves comprehensive transaction data based on merchant payments, contract entity and on specific periods of time.
Accounts are used to process operations, manage a balance in a dedicated currency, control the credit risk, perform transaction charging, calculate interest (credit or debit), generate an invoice (statement), process payments.
Three types of account working modes are being supported; Pay Later, Pay Now, Pay Before.
The below diagram presents different use cases covered by the API in the account domain.
A customer is a person who has subscribed to services offered by the issuer
A customer can have multiple roles and can be:
Note that only relevant client information necessary for our processing, and customer communication on behalf of the issuer, is managed.
Several APIS are provided in order to manage the customer and their addresses as illustrated below:
Insurance attached to an account can be managed within our system.
Example of insurance can be Payment protection insurance.
Several insurance packages can be configured in order to describe the insurance fee calculation and the usage rules.
The list of authorized insurance events and their codes are also part of an insurance package.
As an example:
|
Event code |
Description/Comment |
|
RSV |
Payment protection insurance is active |
|
RAL |
Ensured event "UNEMPLOYMENT" |
|
RAU |
Ensured event "INCAPACITY FOR WORK" |
|
RTD |
Ensured event "DEATH" |
|
RSS |
Reversal of insurance |
|
RKK |
Insurance Cancellation by the customer |
|
RKB |
Insurance Cancellation by the bank |
|
RKA |
Insurance Cancellation by the bank, automatically (maximum age reached) |
The API allows the list of active insurance contracts for an account to be retrieved.
The main input fields requested by the API are:
In return, the list of insurance contracts is provided with the insured events and the latest occurring events for each contract.
The list of insurance events and their codes are a pre-defined and configured in the insurance package.
API links
The API allows an insurance contract for an account to be retrieved.
The main input fields requested by the API are:
In return, the insured events and the latest occurring events for the account and insurance package reference are returned.
In return, the insured events and the latest occurring events for the account and insurance package reference are returned.
The contracts with a closed status are not provided back.
The possible status of insurance contracts are:
The list of insurance events and their codes are a pre-defined and configured in the insurance package.
API links
The API allows an insurance contract for an account to be activated if the activation was not requested at the contract creation.
The main input fields requested by the API are:
Controls are performed in our system in order to check that:
API links
The API allows an insurance contract for an account to be closed.
The main input fields requested by the API are:
API links
The API is used to post some events to an insurance contract.
The complete list of event is defined in the product setup.
The actions linked to the event can be:
The main input fields requested by the API are:
API links
The API is used to generate a balance adjustment operation on an account.
The input account can be provided by using:
API links
Below an example of request and response for:
POST /api/v2/issuers/1234/accounts/12346393393948083995/post-balance-adjustment-operation
Request data
{
" ""balanceAdjustmentReason ":" ""DISPUTE_ADJUSTMENT",
" ""description":" ""Balance Adjustment",
" ""externalOperationReference":" ""12346393393948083995",
" ""externalOperationDate":" ""2023-01-02T11:10:14.365Z",
" ""externalOperationServicePoster":" ""ISSUER",
" ""externalOperationCode":" ""2145",
" ""referenceAmount":" "{
" ""value": 1500,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""valueDate":" ""2023-01-02T11:10:14.365Z"
}Response data
{
" ""responseMetadata":" "{
" ""correlationId":" ""abf49795-85f1-48c5-931e-6f65eb3162bf",
" ""statusMessage":" ""Executed successfully",
" ""statusCode": 200,
" ""responseDateTime":" ""2023-01-02T12:20:44.403+0100",
" ""timeTakenMs": 873
},
" ""data":" "{
" ""operationIdentifier":" "{
" ""operationId":" ""1000000000376072"" "
}" "
}
}The API allows a payment operation to an account to be generated and posted.
A payment operation is used to pay the due amount.
If the amount provided is greater than the due amount, the overpayment can be posted to another account if provided.
As an input, the account identifier can be provided by using:
API links
Below an example of request and response for:
POST /api/v2/issuers/1234/accounts/12348153189268935960/post-payment-operation
Request data
{
" ""description":" ""Manual Payment",
" ""externalOperationReference":" ""TESTAPI12345",
" ""externalOperationDate":" ""2023-02-03T14:06:08.669Z",
" ""externalOperationServicePoster":" ""BANK",
" ""externalOperationCode":" ""1051",
" ""referenceAmount":" "{
" ""value": -42445,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""valueDate":" ""2023-02-03T14:06:08.669Z",
" ""paymentChannel":" ""INCOMING_PAYMENT",
" ""sepa":" true"
}Response data
{
" ""responseMetadata":" "{
" ""correlationId":" ""94179741-e6f4-4ea6-aee5-03a3a297e7a3",
" ""statusMessage":" ""Executed successfully",
" ""statusCode": 200,
" ""responseDateTime":" ""2023-02-03T16:06:31.014+0100",
" ""timeTakenMs": 586
},
" ""data":" "{
" ""operationIdentifier":" "{
" ""operationId":" ""1000000000408222"" "
}" "
}
}The API allows a reimbursement operation to an account to be generated and posted.
A reimbursement operation can be used when the account is in a credit situation.
As an input, the account identifier can be provided by using:
API links
Below an example of reimbursement operation posted to the:
POST /api/v2/issuers/1234/accounts/12348743536456021829/post-reimbursement-operation
Request data
{
" ""description":" ""Manual Reimbursement",
" ""externalOperationReference":" ""12345698741aze",
" ""externalOperationDate":" ""2023-02-03T17:09:14.967Z",
" ""externalOperationServicePoster":" ""BANK",
" ""externalOperationCode":" ""5031",
" ""reimbursementType":" ""FULL",
" ""referenceAmount":" "{
" ""value": 15000,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
}
}Response data
{
" ""responseMetadata":" "{
" ""correlationId":" ""836bb783-1a19-40a5-80f3-ef42476ac639",
" ""statusMessage":" ""Executed successfully",
" ""statusCode": 200,
" ""responseDateTime":" ""2023-02-03T18:15:35.663+0100",
" ""timeTakenMs": 254
},
" ""data":" "{
" ""operationIdentifier":" "{
" ""operationId":" ""1000000000408228"" "
}" "
}
}The API is used to reverse a balance adjustment operation on an account.
As an input, the account identifier can be provided by using:
The balance adjustment operation to be reversed must be provided.
API links
Below an example of request and response for:
POST /api/v2/issuers/1234/accounts/12346393393948083995/reverse-balance-adjustment-operation
Request data
{
" ""reversalReason":" ""REVERSAL_ON_DEMAND",
" ""description":" ""DISPUTE_ADJUSTMENT REVERSAL",
" ""externalMatchingOperationReference":" ""12346393393948083995",
" ""externalMatchingOperationDate":" ""2023-01-02T11:10:14.365Z",
" ""externalMatchingOperationServicePoster":" ""ISSUER",
" ""referenceAmount":" "{
" ""value": 1500,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""externalOperationReference":" ""12346393393948083996",
" ""externalOperationDate":" ""2023-01-02T12:54:22.132Z",
" ""externalOperationServicePoster":" ""ISSUER"
}Response data
{
" ""responseMetadata":" "{
" ""correlationId":" ""64366132-671f-460c-8e0e-209807ee18ef",
" ""statusMessage":" ""Executed successfully",
" ""statusCode": 200,
" ""responseDateTime":" ""2023-01-02T14:00:34.166+0100",
" ""timeTakenMs": 398
},
" ""data":" "{
" ""operationIdentifier":" "{
" ""operationId":" ""1000000000376074"" "
}" "
}
}The API allows a payment reversal operation on an account.
A payment reversal can be requested when a direct debit returns unpaid.
As an input, the account identifier can be provided by using:
The payment reference to be reversed must be provided.
API links
Below an example of request and response for:
POST /api/v2/issuers/1234/accounts/12348153189268935960/reverse-payment-operation
Request data
{
" ""reversalReason":" ""REVERSAL_ON_DEMAND",
" ""description":" ""Manual payment reversal",
" ""externalMatchingOperationReference":" ""TESTAPI12345",
" ""externalMatchingOperationDate":" ""2023-02-03T14:06:08.669Z",
" ""externalMatchingOperationServicePoster":" ""BANK",
" ""externalOperationReference":" ""RVTESTAPI12345",
" ""externalOperationDate":" ""2023-02-03T17:23:46.730Z",
" ""externalOperationServicePoster":" ""BANK"
}Response data
{
" ""responseMetadata":" "{
" ""correlationId":" ""45911869-8968-4948-a570-48ef47ca9b32",
" ""statusMessage":" ""Executed successfully",
" ""statusCode": 200,
" ""responseDateTime":" ""2023-02-03T18:32:13.432+0100",
" ""timeTakenMs": 307
},
" ""data":" "{
" ""operationIdentifier":" "{
" ""operationId":" ""1000000000408230"" "
}" "
}
}The API allows an account to be loaded.
A load operation is used for prepaid cards to put money in an account.
The operation can have a control on the amount authorized and trigger a load operation fee, if it is configured.
As an input, the account identifier can be provided by using:
API links
Below an example of request and the response for:
POST /api/v2/issuers/1234/accounts/283729323911384/post-load-operation
Request data
{
" ""description":" ""load test",
" ""externalOperationReference":" ""5678",
" ""externalOperationDate":" ""2023-01-02T14:31:50.961Z",
" ""externalOperationServicePoster":" ""ISSUER",
" ""externalOperationCode":" ""9999",
" ""referenceAmount":" "{
" ""value": 5000,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""paymentChannel":" ""NO_CHANNEL_PROVIDED",
" ""sepa":" false"
}Response data
{
" ""responseMetadata":" "{
" ""correlationId":" ""03c5fd54-cb82-4036-bf83-e1a9a72d1903",
" ""statusMessage":" ""Executed successfully",
" ""statusCode": 200,
" ""responseDateTime":" ""2023-01-02T14:31:54.798+0100",
" ""timeTakenMs": 1865
},
" ""data":" "{
" ""operationIdentifier":" "{
" ""operationId":" ""1000000000376075"" "
}" "
}
}The API allows an account to be unloaded. An unload operation is used for prepaid cards to retrieve money from an account.
The operation can have a control on the amount authorized.
As an input, the account identifier can be provided by using:
API links
Below an example of request and the response for:
POST /api/v2/issuers/1234/accounts/283729323911384/post-unload-operation
Request data
{
" ""description":" ""unload test",
" ""externalOperationReference":" ""0078",
" ""externalOperationDate":" ""2023-01-02T14:34:50.961Z",
" ""externalOperationServicePoster":" ""ISSUER",
" ""externalOperationCode":" ""9994",
" ""referenceAmount":" "{
" ""value": 4000,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
}
}Response data
{
" ""responseMetadata":" "{
" ""correlationId":" ""4918e858-6d61-44af-930a-75caee13b2e5",
" ""statusMessage":" ""Executed successfully",
" ""statusCode": 200,
" ""responseDateTime":" ""2023-01-02T14:34:20.183+0100",
" ""timeTakenMs": 186
},
" ""data":" "{
" ""operationIdentifier":" "{
" ""operationId":" ""1000000000376076"" "
}" "
}
}The API allows the list of sepa and non sepa direct debit notes generated from an account to repay its due amount to be retrieved.
API links
Below an example of request for:
GET / api/v2/issuers/1234/accounts/12349485785398617383/direct-debits
Response data
{
" ""data":" "[
" "{
" ""issuerId":" ""1234",
" ""directDebitIdentifier":" "{
" ""endToEndId":" ""12341902C221228053245590"" "
},
" ""overPaymentAccountIdentifier":" "{
" ""accountReference":" ""12349485785398617383",
" ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-20220809091334"" "
},
" ""payingAccountIdentifier":" "{
" ""accountReference":" ""12349485785398617383",
" ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-20220809091334"" "
},
" ""amount":" "{
" ""value": 475,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""creationDate":" ""2022-12-28T04:32:45.000+00:00",
" ""extractType":" ""BATCH",
" ""status":" ""ACCEPTED",
" ""remittanceInfo":" ""ABCCARD - ABRECHNUNG VOM 20221228"" "
},
" "{
" ""issuerId":" ""1234",
" ""directDebitIdentifier":" "{
" ""endToEndId":" ""12344470C221227121217877"" "
},
" ""overPaymentAccountIdentifier":" "{
" ""accountReference":" ""12349485785398617383",
" ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-20220809091334"" "
},
" ""payingAccountIdentifier":" "{
" ""accountReference":" ""12349485785398617383",
" ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-20220809091334"" "
},
" ""amount":" "{
" ""value": 390,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""creationDate":" ""2022-12-27T11:12:17.000+00:00",
" ""extractType":" ""BATCH",
" ""status":" ""ACCEPTED",
" ""remittanceInfo": ABCCARD - ABRECHNUNG VOM 20221227"
},
{
""issuerId"": "1234",
""directDebitIdentifier"": {
""endToEndId"": "12344701C221227120342227"
},
""overPaymentAccountIdentifier"": {
""accountReference"": "12349485785398617383",
""issuerAccountExternalReference"": "ROOT_ACCOUNT-20220809091334"
},
""payingAccountIdentifier"": {
""accountReference"": "12349485785398617383",
""issuerAccountExternalReference"": "ROOT_ACCOUNT-20220809091334"
},
""amount"": {
""value"": 220,
""exponent"": 2,
""isoCode"": ""EUR""
},
""creationDate"": ""2022-12-27T11":"03":"42.000+00":00",
""extractType"": ""BATCH"",
""status"": ""ACCEPTED"",
""remittanceInfo"": "ABCCARD - ABRECHNUNG VOM 20221227"
},
{
""issuerId"": "1234",
""directDebitIdentifier"": {
""endToEndId"": "1234-12349485785398617383-C202212020958"
},
""overPaymentAccountIdentifier"": {
""accountReference"": "12349485785398617383",
""issuerAccountExternalReference"": "ROOT_ACCOUNT-20220809091334"
},
""payingAccountIdentifier"": {
""accountReference"": "12349485785398617383",
""issuerAccountExternalReference"": "ROOT_ACCOUNT-20220809091334"
},
""amount"": {
""value"": 3900,
""exponent"": 2,
""isoCode"": ""EUR""
},
""creationDate"": ""2022-12-02T08":"58":"40.000+00":00",
""extractType"": ""BATCH"",
""status"": ""PAID"",
""remittanceInfo"": "ABCCARD - ABRECHNUNG VOM 20221202"\"
}
]
}"This API enables a direct debit note to be requested by debiting a customer bank account (inhouse or external) to increase the open to buy of the card account (for a particular purchase).
As a result, the direct debit is generated and after n business days (issuer configuration), the card account is paid with the requested amount (the total amount due for this card account is paid first).
The API returns the unique Direct Debit EndToEnd Identifier generated by our system and the direct debit status.
This API enables an already created direct debit instruction to be retrieved by providing in input the Direct Debit E2E Identifier and the reject reason.
API links
Below an example of request for the:
GET /api/v2/issuers/1234/direct-debits/1234-12349485785398617383-C202212020958
Response data
" ""data":" "{
" ""issuerId":" ""1234",
" ""directDebitIdentifier":" "{
" ""endToEndId":" ""1234-12349485785398617383-C202212020958"" "
},
" ""overPaymentAccountIdentifier":" "{
" ""accountReference":" ""12349485785398617383",
" ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-20220809091334"" "
},
" ""payingAccountIdentifier":" "{
" ""accountReference":" ""12349485785398617383",
" ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-20220809091334"" "
},
" ""amount":" "{
" ""value": 3900,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""creationDate":" ""2022-12-02T08:58:40.000+00:00",
" ""extractType":" ""BATCH",
" ""status":" ""PAID",
" ""remittanceInfo":" "" ABCCARD - ABRECHNUNG VOM 20221202"" "
}
}This API enables a direct debit instruction to be cancelled by providing in input the Direct debit E2E Identifier.
The cancellation is possible for Direct debit not collected yet (sent to the bank).
API links
The API allows the list of credit transfers posted for an account to be retrieved.
This API applies to the credit cards domain.
A credit transfer can be posted to an account to pay the due amount (for eg, self-payer).
API links
Below an example of request for:
GET /api/v2/issuers/1234/accounts/658641608028488/credit-transfers
Response data
{
" ""data":" "[
" "{
" ""issuerId":" ""1234",
" ""creditTransferIdentifier":" "{
" ""endToEndId":" ""1234-658641608028488-F202204191155"" "
},
" ""accountIdentifier":" "{
" ""accountReference":" ""658641608028488"" "
},
" ""creationDate":" ""2022-04-19T09:55:23.000+00:00",
" ""amount":" "{
" ""value": 3997,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""iban":" ""DE30200411111207360447",
" ""bic":" ""SOLADEST600",
" ""sci":" ""DE39ATS00000000043",
" ""sepaIndicator":" true",
" ""octType":" ""K",
" ""remittanceInfo":" ""GUTSCHRIFT XXXXXXXXX",
" ""status":" ""CREATED",
" ""eventSource":" ""INTERNAL"" "
}" "
]
}This API enables an outgoing credit transfer instruction to be created by transferring funds towards a beneficiary bank account (inhouse/external) from a card account credit balance or open-to-buy.
The beneficiary bank account IBAN can be provided in input (the Direct Debit IBAN for the card account can be used otherwise if any).
As a result, the card account is immediately debit of the requested amount.
The API returns the unique Credit Transfer EndToEnd Identifier generated by our system and the Credit Transfer status.
API links
This API enables an already created credit transfer instruction to be retrieved by providing in input the credit transfer E2E Identifier.
API links
This API enables a credit transfer instruction to be cancelled by providing in input the credit transfer E2E Identifier.
API links
An account is in delinquency situation (the required minimum payment is overdue).
The API allows the delinquency situation of an account to be cancelled.
As an input, the account identifier is provided by using:
Optionally, the required overdue minimum payment can be cancelled.
As a result:
API links
At cycle closure date raw statement data is prepared and can be exported at statement issuing date.
Each statement contains:
The API is used to get the list of statements generated for an account and optionally a requested period.
It is also possible to get reprint information of a statement.
The input parameters are:
In response, the list of statement is provided with the financial information of each statement such as: previous cycle balance (start balance), end cycle balance, due amount, total of payments, ...
API links
Below an example of request for the account: 12343037952407582600
GET /api/v2/issuers/1234/accounts/12343037952407582600/statements?embed=reprintHistory
Response data
{
"data":" "[
" "{
" ""issuerId":" ""1234",
" ""accountIdentifier":" "{
" ""accountReference":" ""12343037952407582600"" "
},
" ""cycleClosureDate":" ""2022-11-29T23:00:00.000+00:00",
" ""creationDate":" ""2022-12-21T09:52:00.000+00:00",
" ""paymentDueDate":" ""2022-11-29T23:00:00.000+00:00",
" ""directDebitAmount":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""theoricDirectDebitAmount":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""cycleBalance":" "{
" ""value": -40946,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""previousCycleBalance":" "{
" ""value": -41031,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""totalOfPayment":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""previousCycleClosureDate":" ""2022-10-27T22:00:00.000+00:00",
" ""nextCycleClosureDate":" ""2022-12-29T23:00:00.000+00:00",
" ""amountDue":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""initialPastAmountDue":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""initialRemainingAmountDue":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
}" "
},
" "{
" ""issuerId":" ""1234",
" ""accountIdentifier":" "{
" ""accountReference":" ""12343037952407582600"" "
},
" ""cycleClosureDate":" ""2022-10-27T22:00:00.000+00:00",
" ""creationDate":" ""2022-10-28T14:50:04.000+00:00",
" ""paymentDueDate":" ""2022-10-27T22:00:00.000+00:00",
" ""theoricDirectDebitAmount":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""cycleBalance":" "{
" ""value": -41031,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""previousCycleBalance":" "{
" ""value": -41031,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""totalOfPayment":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""previousCycleClosureDate":" ""2022-09-29T22:00:00.000+00:00",
" ""nextCycleClosureDate":" ""2022-11-29T23:00:00.000+00:00",
" ""amountDue":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""initialPastAmountDue":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""initialRemainingAmountDue":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
}" "
},
" "{
" ""issuerId":" ""1234",
" ""accountIdentifier":" "{
" ""accountReference":" ""12343037952407582600"" "
},
" ""cycleClosureDate":" ""2022-09-29T22:00:00.000+00:00",
" ""paymentDueDate":" ""2022-09-29T22:00:00.000+00:00",
" ""theoricDirectDebitAmount":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""cycleBalance":" "{
" ""value": -41031,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""previousCycleBalance":" "{
" ""value": -41031,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""totalOfPayment":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""previousCycleClosureDate":" ""2022-08-29T22:00:00.000+00:00",
" ""nextCycleClosureDate":" ""2022-10-27T22:00:00.000+00:00",
" ""amountDue":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""initialPastAmountDue":" "{
" ""value": 5000,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""initialRemainingAmountDue":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
}" "
},
" "{
" ""issuerId":" ""1234",
" ""accountIdentifier":" "{
" ""accountReference":" ""12343037952407582600"" "
},
" ""cycleClosureDate":" ""2022-08-29T22:00:00.000+00:00",
" ""paymentDueDate":" ""2022-08-29T22:00:00.000+00:00",
" ""theoricDirectDebitAmount":" "{
" ""value": 5000,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""cycleBalance":" "{
" ""value": -41031,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""previousCycleBalance":" "{
" ""value": 55465,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""totalOfPayment":" "{
" ""value": 46500,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""previousCycleClosureDate":" ""2022-07-28T22:00:00.000+00:00",
" ""nextCycleClosureDate":" ""2022-09-29T22:00:00.000+00:00",
" ""amountDue":" "{
" ""value": 5000,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""initialPastAmountDue":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""initialRemainingAmountDue":" "{
" ""value": 5000,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
}" "
},
" "{
" ""issuerId":" ""1234",
" ""accountIdentifier":" "{
" ""accountReference":" ""12343037952407582600"" "
},
" ""cycleClosureDate":" ""2022-07-28T22:00:00.000+00:00",
" ""paymentDueDate":" ""2022-07-28T22:00:00.000+00:00",
" ""theoricDirectDebitAmount":" "{
" ""value": 27733,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""cycleBalance":" "{
" ""value": 55465,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""previousCycleBalance":" "{
" ""value": 60000,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""totalOfPayment":" "{
" ""value": 30000,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""previousCycleClosureDate":" ""2022-06-29T22:00:00.000+00:00",
" ""nextCycleClosureDate":" ""2022-08-29T22:00:00.000+00:00",
" ""amountDue":" "{
" ""value": 5000,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""initialPastAmountDue":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""initialRemainingAmountDue":" "{
" ""value": 5000,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
}" "
},
" "{
" ""issuerId":" ""1234",
" ""accountIdentifier":" "{
" ""accountReference":" ""12343037952407582600"" "
},
" ""cycleClosureDate":" ""2022-06-29T22:00:00.000+00:00",
" ""creationDate":" ""2022-07-08T16:10:18.000+00:00",
" ""paymentDueDate":" ""2022-06-29T22:00:00.000+00:00",
" ""directDebitAmount":" "{
" ""value": 30000,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""theoricDirectDebitAmount":" "{
" ""value": 30000,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""cycleBalance":" "{
" ""value": 60000,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""previousCycleBalance":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""totalOfPayment":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""nextCycleClosureDate":" ""2022-07-28T22:00:00.000+00:00",
" ""amountDue":" "{
" ""value": 5000,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""initialRemainingAmountDue":" "{
" ""value": 5000,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
}" "
}" "
]
}The API is used to get the financial information of the last statement generated for an account such as: previous cycle balance (start balance), end cycle balance, due amount, total of payments, ...
It is also possible to get reprint information of the statement.
The input parameters are:
API links
Below an example of request for the:
GET /1234/accounts/12343037952407582600/statements/last
Response data
{
"data":" "{
" ""issuerId":" ""1234",
" ""accountIdentifier":" "{
" ""accountReference":" ""12343037952407582600"" "
},
" ""cycleClosureDate":" ""2022-11-29T23:00:00.000+00:00",
" ""creationDate":" ""2022-12-21T09:52:00.000+00:00",
" ""paymentDueDate":" ""2022-11-29T23:00:00.000+00:00",
" ""directDebitAmount":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""theoricDirectDebitAmount":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""cycleBalance":" "{
" ""value": -40946,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""previousCycleBalance":" "{
" ""value": -41031,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""totalOfPayment":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""previousCycleClosureDate":" ""2022-10-27T22:00:00.000+00:00",
" ""nextCycleClosureDate":" ""2022-12-29T23:00:00.000+00:00",
" ""amountDue":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""initialPastAmountDue":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""initialRemainingAmountDue":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
}" "
}
}The API is used to get the list of operations of the last statement generated for an account.
The input account can be provided by using:
Below an example of request for the:
In the response, there is only one operation: a statement fee.
GET /api/v2/issuers/1234/accounts/12343037952407582600/statements/last/operations
Response data
{
" ""data":" "[
" "{
" ""issuerId":" ""1234",
" ""operationIdentifier":" "{
" ""operationId":" ""1000000000370386"" "
},
" ""description":" ""Portoersatz KK-Abrechnung",
" ""externalOperationCode":" ""2033",
" ""feeType":" ""STATEMENT_FEE",
" ""operationKind":" ""FEE",
" ""postingDate":" ""2022-12-21T09:48:36.489+00:00",
" ""referenceAmount":" "{
" ""value": 85,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""reversal":" false",
" ""subFeeType":" ""STATEMENT",
" ""transactionAmount":" "{
" ""value": 85,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""valueDate":" ""2022-11-29T23:00:00.000+00:00",
" ""externalOperationDate":" ""2022-12-21T09:48:36.473+00:00",
" ""externalOperationReference":" ""5f5395a439ea4915836ff4a874f52af3",
" ""externalOperationServicePoster":" ""WLP-CAS"" "
}" "
]
}The API is used to request the reprint of the last statement for an account.
The input account can be provided by using:
As a result, the statement data is extracted again and pushed to the output management module.
API links
Below an example of request for:
POST /api/v2/issuers/1234/accounts/12343037952407582600/statements/last/reprint
Response data
{
" ""responseMetadata":" "{
" ""correlationId":" ""df9b036c-d8d3-4445-bb3f-c80d8cd8fe12",
" ""statusMessage":" ""Executed successfully",
" ""statusCode": 200,
" ""responseDateTime":" ""2022-12-21T11:56:41.712+0100",
" ""timeTakenMs": 77
},
" ""data":" "{
" ""accountIdentifier":" "{
" ""accountReference":" ""12343037952407582600"" "
},
" ""requestedDate":" ""2022-12-21T10:56:41.681+00:00"" "
}
}The API is used to get the list of operations generated for an account since the last cycle closure date. Those operations will be part of the next statement.
The input account can be provided by using:
API links
Below is an example where the request retrieves the operations of the next statement for:
GET /api/v2/issuers/1234/accounts/12343037952407582600/statements/next/operations
Response data
{
" ""data":" "[
" "{
" ""issuerId":" ""1234",
" ""operationIdentifier":" "{
" ""operationId":" ""1000000000370512"" "
},
" ""acquirerReferenceData":" ""74198812354221219180000",
" ""cardAcceptorCity":" ""44131447816",
" ""cardAcceptorCountry":" ""276",
" ""cardAcceptorName":" ""WEB ANNONCE",
" ""description":" ""WEB ANNONCE 44131447816 276",
" ""externalOperationCode":" ""1035",
" ""maskedPan":" ""424201******0010",
" ""merchantCategoryCode":" ""5712",
" ""operationCode":" ""NORMAL_PURCHASE",
" ""operationKind":" ""TRN",
" ""postingDate":" ""2022-12-21T11:02:42.646+00:00",
" ""reconciliationAmount":" "{
" ""value": 74825,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""referenceAmount":" "{
" ""value": 74825,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""reversal":" false",
" ""transactionAmount":" "{
" ""value": 74825,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""transactionDate":" ""2022-12-18T23:00:00.000+00:00",
" ""valueDate":" ""2022-12-19T23:00:00.000+00:00",
" ""cardIdentifier":" "{
" ""cardReference":" ""2000000000248652"" "
},
" ""externalOperationDate":" ""2022-12-21T11:02:42.155+00:00",
" ""externalOperationReference":" ""10000000000273000",
" ""externalOperationServicePoster":" ""ITP",
" ""pan":" ""4242010796210010",
" ""acquisitionMaterial":" ""INTERNET",
" ""cardAcceptorIdCode":" ""208043134881626",
" ""entryMode":" ""UNKNOWN",
" ""approvalCode":" ""120239",
" ""pointOfSaleEnvironment":" "" ",
" ""mailPhoneEcommerceAndPaymentIndicator":" ""7"" "
}" "
]
}The API is used to get the financial information for an account statement such as: previous cycle balance (start balance), end cycle balance, due amount, total of payments, ...
The input account can be provided by using:
The statement involved by the request has to be provided by giving the cycle closure date.
API links
Below is an example where the request retrieves the financial information of the statement for:
GET /api/v2/issuers/1234/accounts/12343037952407582600/statements/2022-07-28T22:00:00Z
Response data
{
" ""responseMetadata":" "{
" ""correlationId":" ""6ca2edae-559d-400b-a224-8d28d5aa156d",
" ""statusMessage":" ""Executed successfully",
" ""statusCode": 200,
" ""responseDateTime":" ""2022-12-21T12:13:17.940+0100",
" ""timeTakenMs": 29
},
" ""data":" "{
" ""issuerId":" ""1234",
" ""accountIdentifier":" "{
" ""accountReference":" ""12343037952407582600"" "
},
" ""cycleClosureDate":" ""2022-07-28T22:00:00.000+00:00",
" ""paymentDueDate":" ""2022-07-28T22:00:00.000+00:00",
" ""theoricDirectDebitAmount":" "{
" ""value": 27733,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""cycleBalance":" "{
" ""value": 55465,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""previousCycleBalance":" "{
" ""value": 60000,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""totalOfPayment":" "{
" ""value": 30000,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""previousCycleClosureDate":" ""2022-06-29T22:00:00.000+00:00",
" ""nextCycleClosureDate":" ""2022-08-29T22:00:00.000+00:00",
" ""amountDue":" "{
" ""value": 5000,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""initialPastAmountDue":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""initialRemainingAmountDue":" "{
" ""value": 5000,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
}" "
}
}The API is used to get the list of operations posted to an account included in a statement.
The input account can be provided by using:
The statement involved by the request has to be provided by giving the cycle closure date.
API links
Below is an example where the request retrieves the operations of the statement for:
GET /api/v2/issuers/1234/accounts/12343037952407582600/statements/2022-07-28T22:00:00Z /operations
Response data
{
"data":[
{
"issuerId":"1234",
"operationIdentifier":{
"operationId":"1000000000268017"
},
"description":"Ausgleich Kreditkartenabrechnung",
"externalOperationCode":"1067",
"operationKind":"PAY",
"postingDate":"2022-07-18T13:13:03.749+00:00",
"referenceAmount":{
"value":-30000,
"exponent":2,
"isoCode":"EUR"
},
"reversal":false,
"transactionAmount":{
"value":-30000,
"exponent":2,
"isoCode":"EUR"
},
"valueDate":"2022-07-17T22:00:00.000+00:00",
"externalOperationDate":"2022-07-18T13:13:03.748+00:00",
"externalOperationReference":"b6a8551f1ee8498b98c0f6d22529a8d6",
"externalOperationServicePoster":"WLP-CAS"
},
{
"issuerId":"1234",
"operationIdentifier":{
"operationId":"1000000000268018"
},
"description":"Sub PAY operation (apportionment) - Ausgleich Kreditkartenabrechnung",
"operationKind":"SUBPAYOP",
"postingDate":"2022-07-18T13:13:03.759+00:00",
"referenceAmount":{
"value":-5000,
"exponent":2,
"isoCode":"EUR"
},
"reversal":false,
"transactionAmount":{
"value":-5000,
"exponent":2,
"isoCode":"EUR"
},
"valueDate":"2022-07-17T22:00:00.000+00:00",
"externalOperationDate":"2022-07-18T13:13:03.748+00:00",
"externalOperationReference":"0b4edad851194b7f9056cbfa8fd6a843",
"externalOperationServicePoster":"WLP-CAS"
},
{
"issuerId":"1234",
"operationIdentifier":{
"operationId":"1000000000280040"
},
"description":"Finanzierungsgebühren",
"externalOperationCode":"1201",
"operationKind":"INT",
"postingDate":"2022-08-17T11:26:36.553+00:00",
"referenceAmount":{
"value":465,
"exponent":2,
"isoCode":"EUR"
},
"reversal":false,
"transactionAmount":{
"value":465,
"exponent":2,
"isoCode":"EUR"
},
"valueDate":"2022-08-16T22:00:00.000+00:00",
"externalOperationDate":"2022-08-17T11:26:36.551+00:00",
"externalOperationReference":"01f6ab9128fb4d94a64d67c2071cd4d0",
"externalOperationServicePoster":"WLP-CAS"
}
]
}The API is used to request the reprint of a statement for an account.
The input account can be provided by using:
The statement involved by the request has to be provided by giving the cycle closure date. As a result, the statement data is extracted again and pushed to the output management module.
API links
Below an example of request for:
POST /api/v2/issuers/1234/accounts/12343037952407582600/statements/2022-10-28T00:00:00Z/reprint
Response data
{
" ""responseMetadata":" "{
" ""correlationId":" ""cc04a0d7-6dfc-4eb0-9e70-782ef93cb6d1",
" ""statusMessage":" ""Executed successfully",
" ""statusCode": 200,
" ""responseDateTime":" ""2022-12-21T12:52:44.616+0100",
" ""timeTakenMs": 127
},
" ""data":" "{
" ""accountIdentifier":" "{
" ""accountReference":" ""12343037952407582600"" "
},
" ""requestedDate":" ""2022-12-21T11:52:44.581+00:00"" "
}
}A Customer address can be of different types, such as postal address, email address or phone number.
The appropriate address type will be selected depending on the business usage, for example statement sending or card delivery.
Customer addresses can be created during the creation of the Contract or when additional Cards and Accounts are created.
A customer should have at least one main address (addressLabel: MAIN_POSTAL_ADDRESS)
Each Address is identified by a unique address Reference and optionally by a unique issuer Address External Reference per Issuer.
Through the API, Issuer can:
The API returns the current version of the customer's address identified with:
The address identifiers, address attributes, address usages and entity reference (application domain of the address) are displayed in the response.
API Links
Below an example for :
GET /api/v2/issuers/1234/customers/CUS10000375016/addresses
Response data:
{
"data": [
{
"issuerId": "1234",
"addressIdentifier": {
"addressReference": "ADDREF_MAIN_POSTAL_ADDRESS_1000000000417761",
"issuerAddressExternalReference": "ADDRESS-202301260053"
},
"addressLabel": "MAIN_POSTAL_ADDRESS",
"addressType": "POSTAL_MAIL",
"postalAddress": {
"line1": "HENRI MARCADAS",
"line2": "line2",
"line4": "BERLIN",
"line5": "DE",
"townName": "BERLIN",
"country": "DE"
},
"status": "ACTIVE",
"startDate": "2023-01-26T10:23:47.029+00:00"
}
]
}
The API creates an address for the customer, identified with his reference.
An address includes the following information:
For information, the main postal address is mandatory.
In return, the API provides the address Reference calculated by our system.
API Links
Below an example of create address request for the customer:
POST /api/v2/issuers/1234/customers/CUS10000375016/addresses
Request data:
{
"issuerAddressExternalReference":"string",
"addressLabel":"MAIN_POSTAL_ADDRESS",
"addressType":"POSTAL_MAIL",
"postalAddress":{
"line1":"MARCADAS Henri",
"line2":"line2",
"line3":"line3",
"line4":"line4",
"line5":"line5",
"buildingNumber":"15",
"boxNumber":"AZ",
"streetName":"street",
"postCode":"postcode",
"townName":"town",
"countrySubdivision":"region",
"country":"DE"
},
"addressUsages":[
{
"addressUsageName":"CONTRACT_LETTER",
"serviceCode":"CONTRACT_SERVICE"
}
],
"startDate":"2023-02-17T08:44:28.437Z"
}Response data:
{
"responseMetadata":{
"correlationId":"f1ed54c9-7682-4984-8c8d-1db4cda96a5e",
"statusMessage":"Executed successfully",
"statusCode":200,
"responseDateTime":"2023-02-17T09:52:40.896+0100",
"timeTakenMs":497
},
"data":{
"addressIdentifier":{
"addressReference":"ADDREF_SECOND_POSTAL_ADDRESS_1000000000440549",
"issuerAddressExternalReference":"string"
}
}
}
The API updates all the attributes of a customer's address identified with the reference of the customer and the reference of the address. All the attributes must be provided, even those that are unchanged. The identifiers remain unchanged.
API Links
Below an example of the update request for:
As the address reference ( ADDREF…. 1000000000440549) is inactive, the API creates a new address reference: ADDREF_SECOND_POSTAL_ADDRESS_1000000000440550
Note that if the input address reference was active, the API updates the address reference and doesn’t create another address reference (see the result in the chapter List addresses for a customer).
PUT /api/v2/issuers/1234/customers/CUS10000375016/addresses/ADDREF_SECOND_POSTAL_ADDRESS_1000000000440549
Request data:
{
"issuerAddressExternalReference":"string",
"addressLabel":"SECOND_POSTAL_ADDRESS",
"addressType":"POSTAL_MAIL",
"postalAddress":{
"line1":"MARCADAS Henri",
"line2":"line2",
"line3":"line3",
"line4":"line4",
"line5":"line5",
"buildingNumber":"15",
"boxNumber":"ABC box number",
"streetName":"street",
"postCode":"postcode",
"townName":"town",
"countrySubdivision":"region",
"country":"DE"
},
"addressUsages":[
{
"addressUsageName":"CONTRACT_LETTER",
"serviceCode":"CONTRACT_SERVICE"
}
]
}Response data:
{
"responseMetadata":{
"correlationId":"046eef54-bbd8-492e-b502-ec5c74d68775",
"statusMessage":"Executed successfully",
"statusCode":200,
"responseDateTime":"2023-02-17T10:17:56.639+0100",
"timeTakenMs":41
},
"data":{
"addressIdentifier":{
"addressReference":"ADDREF_SECOND_POSTAL_ADDRESS_1000000000440550"
}
}"a"
}The API allows activation on demand of an address by providing
The address identifiers, address attributes and address usages are displayed in the response.
API Links
The API is used to deactivate the address, identified with the customer reference and the address reference.
The status becomes 'INACTIVE'.
This action is forbidden in case of:
API Links
Below an example of deactivate address request for:
POST /api/v2/issuers/1234/customers/CUS10000375016/addresses/ADDREF_SECOND_POSTAL_ADDRESS_1000000000440549/deactivate
Response data:
{
"data":{
"addressIdentifier":{
"addressReference":"ADDREF_SECOND_POSTAL_ADDRESS_1000000000440549",
"issuerAddressExternalReference":"string"
},
"status":"INACTIVE"
}
}
The address usage describes for which business case the address will be used (e.g., statement sending, card delivery, ...) The complete authorized values list is shared during the product configuration between the issuer and WL. This API allows a usage determined by its name (e.g. STATEMENT_SENDING) to be linked to the entity reference of the address (e.g. card contract reference) and the service code (e.g. ACCOUNT_SERVICE)
To create an address usage, it is needed to provide:
API Links
To create an address usage, it is needed to provide:
Below an example of the update request for:
In this example, the address will be used for the dispute letters.
POST /api/v2/issuers/1234/customers/CUS10000375016/addresses/ADDREF_SECOND_POSTAL_ADDRESS_1000000000440550/address-usages
Request data:
{
"addressUsageName":"DISPUTE",
"serviceCode":"DISPUTE_SERVICE"
}Response data:
{
"responseMetadata":{
"correlationId":"a7cf57a9-5abe-462d-9b38-24c2bedc2bf0",
"statusMessage":"Executed successfully",
"statusCode":200,
"responseDateTime":"2023-02-17T12:05:59.187+0100",
"timeTakenMs":233
},
"data":{
"addressUsageName":"DISPUTE",
"serviceCode":"DISPUTE_SERVICE"
}
}
The API deletes the address usages linked to one address.
These address usages are filtered by the request params:
If the entityReference is empty and the API finds several addresseUsages (for the addressUsageName and serviceCode in request param), then the list of addressUsages will be deleted.
API Links
Below an example of delete address request for
DELETE /api/v2/issuers/1234/customers/CUS10000375016/addresses/ADDREF_SECOND_POSTAL_ADDRESS_1000000000440549/address-usages?serviceCode=CONTRACT_SERVICE&addressUsageName=CONTRACT_LETTER Response
Response data:
{
"responseMetadata":{
"correlationId":"e2ac07b1-861e-48cc-bc61-015f3e1801df",
"statusMessage":"Executed successfully",
"statusCode":200,
"responseDateTime":"2023-02-17T10:02:30.775+0100",
"timeTakenMs":39
},
"data":{
"addressUsages":[
{
"addressUsageName":"CONTRACT_LETTER",
"serviceCode":"CONTRACT_SERVICE"
}
]
}
}Each customer is identified by a unique “customerReference” generated internally and optionally by an external reference “issuerCustomerExternalReference” provided by the issuer - which must be unique per issuer.
The customer is created during the creation of the Contract or when additional Cards and Accounts are provided.
The "list customers" API enables to get a list of customers based on multiple criteria such as First name, Last name, Birth date,.. For the search, the API enables exact matches values (partialSearch field set to false) or not (partialSearch set to yes). In the latter case, the search criteria should be a subset of the corresponding value stored in our system ; as an example : if we set "JOH" as criteria search for name, then results JOHNNY or "LISE-JOHN" for name would match.
API Links
Find an example where the request retrieves the customers list for:
GET /api/v2/issuers/1234/customers?lastName=MATISSE&firstName=Jack&partialSearch=false&page=0&offset=100
Response data:
{
"data":[
{
"issuerId":"1234",
"customerIdentifier":{
"customerReference":"CUS10000388138",
"issuerCustomerExternalReference":"PERSON-2023020900010A"
},
"active":true,
"birthDate":"1975-10-22T00:00:00.000+00:00",
"birthPlace":"Stuttgart",
"commercialStatus":"Normal",
"courtesyTitle":"Herr",
"firstName":"Jack",
"lastName":"MATISSE",
"monthlySalary":"0",
"nationality":"DE",
"offlineRiskCategory":"Standard",
"onlineRiskCategory":"Standard",
"sex":"M"
}
]
}
The "retrieve customer" API allows the user to get customer information from the input parameters:
In addition to the person information, it is also possible to request the list of addresses of the customer.
API Links
GET /api/V2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}
GET /api/V2/issuers/{issuerId}/customers/{customerReference}
Find an example where the request retrieves the customer detail for:
GET /api/v2/issuers/1234/customers/CUS10000375046
Response data:
"data":{
"issuerId":"1234",
"customerIdentifier":{
"customerReference":"CUS10000375046",
"issuerCustomerExternalReference":"PERSON-2023012600010A"
},
"active":true,
"birthDate":"1960-10-22T00:00:00.000+00:00",
"birthPlace":"Stuttgart",
"commercialStatus":"Normal",
"courtesyTitle":"Herr",
"firstName":"Andre",
"lastName":"SWITCH",
"monthlySalary":"0",
"nationality":"DE",
"offlineRiskCategory":"Standard",
"onlineRiskCategory":"Standard",
"sex":"M"
}
This API enables all the contracts belonging to a given contract owner to be retrieved.
Information to be provided in input:
The API response contains a list of contracts with related information.
API Links
Find an example where the request retrieves all the contracts for:
In this example, the customer has 2 contracts.
GET /api/v2/issuers/1234/customers/CUS10000375046/contracts
Response data:
{
"data":[
{
"issuerId":"1234",
"contractIdentifier":{
"contractReference":"98e23901-8c38-4da9-ad22-a647d06e8be1",
"issuerContractExternalReference":"CONTRACT-2023012600010A"
},
"issuerBranchCode":"NO_BRANCH",
"cardReleaseOrder":"AUTOMATIC",
"numberOfFreeCardsPrimaryCardImpacted":false,
"signatureDate":"2023-01-26T14:36:01.000+00:00",
"status":"SIGNED",
"statusDate":"2023-01-26T14:36:01.000+00:00",
"contractOwnerIdentifier":{
"customerReference":"CUS10000375048",
"issuerCustomerExternalReference":"PERSON-2023012600012A"
},
"productIdentifier":{
"issuerProductExternalReference":"PDT_1234_DEBIT",
"productReference":"PDT_1234_DEBIT"
},
"rootAccountIdentifier":{
"accountReference":"12349095353652134625",
"issuerAccountExternalReference":"ROOT_ACCOUNT-2023012600010A"
}
},
{
"issuerId":"1234",
"contractIdentifier":{
"contractReference":"2cb82f2f-b3a0-425d-ab34-1df0a08511af",
"issuerContractExternalReference":"CONTRACT-202320900002A"
},
"issuerBranchCode":"NO_BRANCH",
"cardReleaseOrder":"AUTOMATIC",
"numberOfFreeCardsPrimaryCardImpacted":false,
"signatureDate":"2023-02-09T16:23:48.000+00:00",
"status":"SIGNED",
"statusDate":"2023-02-09T16:23:48.000+00:00",
"contractOwnerIdentifier":{
"customerReference":"CUS10000375046",
"issuerCustomerExternalReference":"PERSON-2023012600010A"
},
"productIdentifier":{
"issuerProductExternalReference":"PDT_1234_DEBIT",
"productReference":"PDT_1234_DEBIT"
},
"rootAccountIdentifier":{
"accountReference":"12345560829491606922",
"issuerAccountExternalReference":"ROOT_ACCOUNT-202320900002A"
}
}
]
}
This API enables all the card contracts associated with the cardholder to be retrieved.
Information to be provided in input:
The API response contains a list of card contracts with related information.
API Links
Find an example where the request retrieves all the card contracts for:
In this example, the customer has 2 card contracts.
GET /api/v2/issuers/1234/customers/CUS10000375046/card-contracts
Response data:
{
"data":[
{
"issuerId":"1234",
"cardContractIdentifier":{
"cardContractReference":"12342000000000410211",
"issuerCardContractExternalReference":"CARD_CONTRACT-2023012600010A"
},
"cardTemplateReference":"T_1234_CARD_DEBIT",
"cardTypeCode":"F",
"status":"ACTIVE",
"openingDate":"2023-01-26T14:36:01.983+00:00",
"activationDate":"2023-01-26T14:36:01.983+00:00",
"trustedAuthenticationReference":"123420230126153601853",
"newCardRenewalAllowed":true,
"newCardReplacementAllowed":true,
"issuerBranchCode":"NO_BRANCH",
"artwork":"ClassicCardConsors",
"forcedEmbossingName":"ANDRE SWITCH",
"schemeDeclarationOptOut":false,
"principalSupplementaryCardIndicator":"SUPPLEMENTARY",
"productCategory":"DEBIT",
"productCategoryLabel":"IMMEDIATE_DEBIT_DEBIT",
"productIdentifier":{
"issuerProductExternalReference":"PDT_1234_DEBIT",
"productReference":"PDT_1234_DEBIT"
},
"cardHolderIdentifier":{
"customerReference":"CUS10000375046",
"issuerCustomerExternalReference":"PERSON-2023012600010A"
},
"contractIdentifier":{
"issuerContractExternalReference":"CONTRACT-2023012600010A"
},
"cardProfileDescription":"P_1234_CARD_DEBIT",
"cardProfileReference":"P_1234_CARD_DEBIT",
"contractType":"CONSUMER"
},
{
"issuerId":"1234",
"cardContractIdentifier":{
"cardContractReference":"12342000000000427562",
"issuerCardContractExternalReference":"CARD_CONTRACT-202320900002A"
},
"cardTemplateReference":"T_1234_CARD_DEBIT",
"cardTypeCode":"F",
"status":"ACTIVE",
"openingDate":"2023-02-09T16:23:49.216+00:00",
"activationDate":"2023-02-09T16:23:49.216+00:00",
"trustedAuthenticationReference":"123420230209172349968",
"newCardRenewalAllowed":true,
"newCardReplacementAllowed":true,
"issuerBranchCode":"NO_BRANCH",
"artwork":"ClassicCardConsors",
"forcedEmbossingName":"MR ANDRE SWITCH",
"schemeDeclarationOptOut":false,
"principalSupplementaryCardIndicator":"PRINCIPAL",
"productCategory":"DEBIT",
"productCategoryLabel":"IMMEDIATE_DEBIT_DEBIT",
"productIdentifier":{
"issuerProductExternalReference":"PDT_1234_DEBIT",
"productReference":"PDT_1234_DEBIT"
},
"cardHolderIdentifier":{
"customerReference":"CUS10000375046",
"issuerCustomerExternalReference":"PERSON-2023012600010A"
},
"vipFlag":false,
"contractIdentifier":{
"issuerContractExternalReference":"CONTRACT-202320900002A"
},
"cardProfileDescription":"P_1234_CARD_DEBIT",
"cardProfileReference":"P_1234_CARD_DEBIT",
"contractType":"CONSUMER"
}
]
}
This API enables all the addresses associated with a given customer, identified by his customer reference, to be retrieved. Several address types are managed. Each address can be used for a specific usage (card delivery, statement delivery, contract letter,...). Address usage is associated to a service (card service, account service, dispute service, ..) configured in our system. The API can retrieve only the addresses linked to a specific usage: in this case, all the mandatory 'AddressUsage' attributes must be provided (e.g. serviceCode, AddressUsage). If the showHistory indicator is set to Y then the full history of the addresses and the future addresses are returned. If this indicator is empty (default behaviour) or equals to N, then only the last active addresses are returned. Address identifiers, Address attributes and Address usages are displayed in the response.
API Links
Below an example of request and response for:
The show history is requested in the response in order to have also the previous and the future addresses.
GET /api/v2/issuers/1234/customers/CUS10000375016/addresses?showHistory=true
Response data:
{
"data":[
{
"issuerId":"1234",
"addressIdentifier":{
"addressReference":"ADDREF_MAIN_POSTAL_ADDRESS_1000000000417761",
"issuerAddressExternalReference":"ADDRESS-202301260053"
},
"addressLabel":"MAIN_POSTAL_ADDRESS",
"addressType":"POSTAL_MAIL",
"postalAddress":{
"line1":"HENRI MARCADAS",
"line2":"line2",
"line4":"BERLIN",
"line5":"DE",
"townName":"BERLIN",
"country":"DE"
},
"status":"ACTIVE",
"startDate":"2023-01-26T10:23:47.029+00:00",
"endDate":"2023-03-01T08:44:28.437+00:00"
},
{
"issuerId":"1234",
"addressIdentifier":{
"addressReference":"ADDREF_SECOND_POSTAL_ADDRESS_1000000000440549",
"issuerAddressExternalReference":"string"
},
"addressLabel":"SECOND_POSTAL_ADDRESS",
"addressType":"POSTAL_MAIL",
"postalAddress":{
"line1":"HENRI MARCADAS",
"line2":"line2",
"line3":"street 15",
"line4":"postcode town",
"line5":"DE",
"buildingNumber":"15",
"boxNumber":"AZ",
"streetName":"street",
"postCode":"postcode",
"townName":"town",
"countrySubdivision":"region",
"country":"DE"
},
"status":"INACTIVE",
"startDate":"2023-02-17T08:52:40.593+00:00"
},
{
"issuerId":"1234",
"addressIdentifier":{
"addressReference":"ADDREF_SECOND_POSTAL_ADDRESS_1000000000440550"
},
"addressLabel":"SECOND_POSTAL_ADDRESS",
"addressType":"POSTAL_MAIL",
"postalAddress":{
"line1":"HENRI MARCADAS",
"line2":"line2",
"line3":"street 15",
"line4":"postcode town",
"line5":"DE",
"buildingNumber":"15",
"boxNumber":"ABC box number",
"streetName":"street",
"postCode":"postcode",
"townName":"town",
"countrySubdivision":"region",
"country":"DE"
},
"status":"ACTIVE",
"startDate":"2023-02-17T09:17:56.629+00:00",
"endDate":"2023-02-17T09:24:47.586+00:00"
},
{
"issuerId":"1234",
"addressIdentifier":{
"addressReference":"ADDREF_SECOND_POSTAL_ADDRESS_1000000000440550"
},
"addressLabel":"SECOND_POSTAL_ADDRESS",
"addressType":"POSTAL_MAIL",
"postalAddress":{
"line1":"HENRI MARCADAS",
"line2":"line2",
"line3":"street ref 1000000000440550 15",
"line4":"postcode town",
"line5":"DE",
"buildingNumber":"15",
"boxNumber":"ABC box number",
"streetName":"street ref 1000000000440550",
"postCode":"postcode",
"townName":"town",
"countrySubdivision":"region",
"country":"DE"
},
"status":"ACTIVE",
"startDate":"2023-02-17T09:24:47.586+00:00",
"endDate":"2023-02-17T09:41:16.159+00:00"
},
{
"issuerId":"1234",
"addressIdentifier":{
"addressReference":"ADDREF_SECOND_POSTAL_ADDRESS_1000000000440550"
},
"addressLabel":"SECOND_POSTAL_ADDRESS",
"addressType":"POSTAL_MAIL",
"postalAddress":{
"line1":"HENRI MARCADAS",
"line2":"line2",
"line3":"street ref 1000000000440550 15",
"line4":"history town",
"line5":"DE",
"buildingNumber":"15",
"boxNumber":"ABC box number",
"streetName":"street ref 1000000000440550",
"postCode":"history",
"townName":"town",
"countrySubdivision":"region",
"country":"DE"
},
"status":"ACTIVE",
"startDate":"2023-02-17T09:41:16.159+00:00"
},
{
"issuerId":"1234",
"addressIdentifier":{
"addressReference":"ADDREF_MAIN_POSTAL_ADDRESS_1000000000417761",
"issuerAddressExternalReference":"ADDRESS-202301260053"
},
"addressLabel":"MAIN_POSTAL_ADDRESS",
"addressType":"POSTAL_MAIL",
"postalAddress":{
"line1":"HENRI MARCADAS",
"line2":"line2",
"line3":"future street 15",
"line4":"postcode town",
"line5":"DE",
"buildingNumber":"15",
"boxNumber":"AZ",
"streetName":"future street",
"postCode":"postcode",
"townName":"town",
"countrySubdivision":"region",
"country":"DE"
},
"status":"ACTIVE",
"startDate":"2023-03-01T08:44:28.437+00:00"
}
]
}
This API enables all the accounts associated with the customer (cardholder) to be retrieved. In return, the interface provides the generic information (mainly master data) for managing the account. For credit cards, payment mode and the due amount calculation is provided back.
API Links
The "update customer" API allows the user to update the attributes of a customer.
To identify the customer, it is needed to provide:
The customer reference can be retrieved by using the "list customers" API.
All the attributes must be given in input even if they remain unchanged. For that, It can be needed to use the "retrieve customer" API to get all the current attributes.
API Links
The "update customer partially" API allows the user to update the attributes of a customer.
To identify the customer, it is needed to provide:
The customer reference can be retrieved by using the "list customers" API.
With this API, only attributes that need to be updated must be given in input.
API Links
PATCH /api/V2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}
PATCH /api/V2/issuers/{issuerId}/customers/{customerReference}
Find an example where the request updates:
For:
Issuer : 1234
PATCH /api/v2/issuers/1234/customers/CUS10000375046
Request data:
{
"secondFirstName":"John",
"sex":"M",
"birthDate":"1970-10-22T00:00:00.000Z",
"birthPlace":"Paris"
}Response data:
{
"responseMetadata":{
"correlationId":"a5542367-3384-4738-9710-7ee6111cd7c2",
"statusMessage":"Executed successfully",
"statusCode":200,
"responseDateTime":"2023-02-09T17:52:08.681+0100",
"timeTakenMs":42
},
"data":{
"customerIdentifier":{
"customerReference":"CUS10000375046",
"issuerCustomerExternalReference":"CUS10000375046"
}
}
}Worldline offers the issuer the possibility to capture the claim in several ways as illustrated below:
Dispute creation can be initiated by the WL dispute officer or directly triggered by API from the issuer application. Please find below a representation of the different use cases covered by our dispute API.
Worldline offers the possibility to perform several processes using a single call (create a dispute + additional actions such as posting) or perform unit processing per call. In order to follow-up the dispute process, API are available to get the dispute folder information based on its reference, or list the dispute folders for a given card.
The "Create a dispute" API allows an issuer to create a dispute folder in the system for a given operation.
This API enables the cardholder to initiate the dispute from his mobile application for example.
Several actions can be performed at the same time using this API:
The main input data are:
In response, the created dispute folder identifier is provided back systematically. Depending on the additional requests, the response may also include the posting, event creation and documents add response.
API Links
Below an example in which a dispute creation is requested for transaction ID 10000000000264015 with COUNTERFEIT_CARD reason code, and additionally a write-off operation posting, a “comment” event creation and a document provided at the same time. In response, the dispute folder reference is provided back.
POST /api/v2/issuers/1234/operations/10000000000264015/disputes
Request data:
{
"disputeReason":"COUNTERFEIT_CARD",
"declareFraudIndicator":true,
"issuerDisputeExternalReference":"{{$randomUUID}}",
"disputePostings":[
{
"postingAmount":{
"value":7625,
"exponent":2,
"isoCode":"EUR"
},
"message":"Write off",
"immediateReimbursement":true,
"postingTypeReference":"ISSUER_ACCOUNT"
}
],
"disputeEvents":[
{
"type":"Comment",
"message":"Cardholder phone call"
}
],
"disputeDocuments":[
{
"data":"JVBERi0xLjcKJeA9eHJlZgo0OTEwOQolJUVPRgo=",
"type":"application/pdf",
"label":"test file",
"fileName":"test1.pdf"
}
]
}Response data:
{
"responseMetadata":{
"correlationId":"821c3c28-d5e6-4d05-93be-12efac2c7cc3",
"statusMessage":"Executed successfully",
"statusCode":200,
"responseDateTime":"2022-12-05T10:37:08.282+0100",
"timeTakenMs":680
},
"data":{
"disputeFolderIdentifier":{
"disputeFolderReference":"D-V-1234-2339-42",
"issuerDisputeExternalReference":"45f014d5-bc8a-4074-a707-8e20f272a9a3"
},
"disputePostings":[
{
"postingAmount":{
"value":7625,
"exponent":2,
"isoCode":"EUR"
},
"postingTypeReference":"ISSUER_ACCOUNT",
"creationDate":"2022-12-05T09:37:07.885+00:00"
}
],
"disputeEvents":[
{
"type":"Comment",
"creationDate":"2022-12-05T09:37:07.893+00:00"
}
],
"disputeDocuments":[
{
"fileName":"test1.pdf",
"creationDate":"2022-12-05T09:37:07.908+00:00"
}
]
}
}
The "generate chargeback" API allows an issuer to trigger a chargeback message to the scheme (VISA/MCI), the chargeback is done in synchronous mode.
Main information needed in input is:
API Links
The example below illustrates how a VISA chargeback is created and the scheme case ID provided in response.
POST /api/v2/issuers/1234/disputes/D-V-1234-2306-13/generate-chargeback
Request data:
{
"chargebackType":"FULL",
"chargebackScenario":"VISECOMFRAUD",
"chargebackDocument":{
"data":"iVBORw0KGgoAAAANSUhEUgAAAb4AAADQCAYAAAB4BAR3AAAAAXNSR0IArs4c
6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAABiPSURBVHhe
7Z0tlGPHEUYXGhoGGg….YGGhoaBgYGLgxcFmgYGBgYGBhoaBhoaBhoGLh519K381arGelJ/X
66695z+uysRqOfft39VVVX9Xv3UURE3uaXX84/yAgofCIib/Gf/ /wO0qDSHbNpUNQAAAABJRU5ErkJggg==",
"type":"image/jpeg",
"label":"new photo",
"fileName":"doc.jpeg"
}
}Response data:
{
"responseMetadata":{
"correlationId":"61d97e73-4917-4a29-a949-a5ae1a3398cd",
"statusMessage":"Executed successfully",
"statusCode":200,
"responseDateTime":"2022-12-05T11:13:05.502+0100",
"timeTakenMs":572
},
"data":{
"creationDate":"2022-12-05T11:13:05.501+0100",
"schemeCaseId":"6064286006"
}
}
The API returns the dispute folder information that matches the dispute folder identifier provided in input.
This enables the dispute information to be retrieved:
The response can also be enriched (if specified as embedded fields in input) with additional data relative to the events added, the postings performed, the documents attached, and the messages sent or received from the scheme. This corresponds to the dispute cycle history.
API Links
GET /api/v2/issuers/{issuerId}/disputes/{disputeFolderReference}
GET /api/v2/issuers/{issuerId}/disputes/external-disputes/{issuerDisputeExternalReference}
An example below where events, messages and postings are specifically requested in the question.
GET /api/v2/issuers/1234/disputes/D-V-1234-2319-19?embed=events,postings,0messages
Response data:
{
"responseMetadata":{
"correlationId":"908fa9b9-99bc-4445-9d84-f1dd6b6b7283",
"statusMessage":"Executed successfully",
"statusCode":200,
"responseDateTime":"2022-12-05T10:55:17.648+0100",
"timeTakenMs":294
},
"data":{
"issuerId":"1234",
"disputeFolderIdentifier":{
"disputeFolderReference":"D-V-1234-2319-19",
"issuerDisputeExternalReference":"b7ead3d8-7fe1-41fd-890a-20ce9d3949f6"
},
"events":[
{
"type":"DISPUTE_INITIATE",
"message":"Dispute id : 13268",
"external":false,
"creationDate":"2022-11-15T18:06:04.097+00:00"
},
{
"type":"ASSOCIATE_TRANSACTION",
"message":"ATR Counter: 5, Purchase Inquiry ID: 3899975006, Credit Intent: true",
"creationDate":"2022-11-15T18:06:04.340+00:00"
},
{
"type":"LOCATE_TRANSACTION",
"message":"ROL transaction id : 3445758316",
"external":false,
"creationDate":"2022-11-15T18:06:01.433+00:00"
},
{
"type":"TRANSACTION_DETAILS",
"message":", RDR Eligible Indicator: false, Purchase Inquiry Eligible Indicator: true, Jurisdiction: DOM",
"external":false,
"creationDate":"2022-11-15T18:06:01.438+00:00"
},
{
"type":"CHARGEBACK_SUBMIT",
"message":"Chargeback scheme id : 13268",
"external":false,
"creationDate":"2022-11-15T18:06:04.399+00:00"
},
{
"type":"CREATE_CLAIM",
"message":"Scheme Case number : 1051342286",
"external":false,
"creationDate":"2022-11-15T18:06:03.336+00:00"
}
],
"postings":[
{
"postingAmount":{
"value":-21102,
"exponent":2,
"isoCode":"EUR"
},
"message":"First Presentment processed",
"immediateReimbursement":false,
"postingTypeReference":"Processing View",
"operationReference":"TPFPPT",
"creationDate":"2022-11-15T18:04:57.283+00:00"
}
],
"messages":[
{
"type":"FIRSTCHARGEBACK",
"status":"PENDING_SCHEME",
"creationDate":"2022-11-15T18:06:01.192+00:00",
"amount":{
},
"reasonCode":"13",
"reasonCodeDescription":"Consumer Dispute",
"reverseFlag":false,
"schemeCaseId":"1051342286"
},
{
"type":"ORIGINAL",
"status":"PROCESSED",
"creationDate":"2022-11-15T18:04:57.167+00:00",
"amount":{
"value":21102,
"exponent":2,
"isoCode":"EUR"
},
"reverseFlag":false,
"schemeCaseId":"1051342286"
}
],
"acquirerReferenceData":"74689342319113928021101",
"transactionType":"CASH_WITHDRAWAL",
"transactionTime":"2022-11-14T23:00:00.000+00:00",
"transactionAmount":{
"value":21101,
"exponent":2,
"isoCode":"BRL"
},
"reconciliationAmount":{
"value":21102,
"exponent":2,
"isoCode":"EUR"
},
"billingAmount":{
"value":21102,
"exponent":2,
"isoCode":"EUR"
},
"billingFees":{
"value":420,
"exponent":2,
"isoCode":"EUR"
},
"outstandingBalance":{
"value":21522,
"exponent":2,
"isoCode":"EUR"
},
"issuerAccountingBalance":{
"value":0,
"exponent":2,
"isoCode":"EUR"
},
"statusCode":"OPEN",
"reason":"COUNTERFEIT_CARD",
"creationDate":"2022-11-15T18:04:57.169+00:00",
"cardAcceptorName":"M.NAME-ATM",
"cardAcceptorCity":"RIO",
"cardAcceptorCountry":"BRAZIL",
"cardAcceptorIdCode":"CARD1002319 ID",
"cardAcceptorZipCode":"17520",
"userInCharge":"ADM - admin",
"cardIdentifier":{
"cardReference":"2000000000252082",
"issuerCardExternalReference":"b314e6df-c92d-4a36-83df-15f5d70e608f"
},
"lastMessageType":"FIRSTCHARGEBACK",
"lastMessageDate":"2022-11-15T18:06:01.192+00:00",
"lastMessageStatus":"PENDING_SCHEME"
}
}
The API returns the dispute folder information if the transaction identified by an operation Identifier is disputed.
If it is the case, this enables the content of the dispute to be retrieved:
The response can also be enriched (if specified as embedded fields in input) with additional data relative to the events added, the postings performed, the documents attached, and the messages sent or received from the scheme. This corresponds to the dispute cycle history.
If the transaction is not disputed, the response code 404 is provided back with a status message indicating that no Dispute Folder has been found.
API Links
The API returns the list of dispute folders for a given card, identified by his card identifier.
For each dispute folder provided, the content of the dispute is retrieved:
For each dispute folder, the response can also be enriched (if specified as embedded fields in input) with additional data relative to the events added, the postings performed, the documents attached, and the messages sent or received from the scheme. This corresponds to the dispute cycle history.
API Links
The issuer can provide a posting operation to be performed on the created dispute folder.
The posting operation can be for example:
"Create a posting" API allows an issuer to add postings for a given dispute folder.
Main data in input is the dispute folder identifier and the parameters of the posting operation.
API Links
The issuer can provide an event to be added to the created dispute folder. This manual event will be added to events generated internally by our system. For example, the issuer can add an event to indicate that there is a communication from/to the cardholder.
"Create an event" API allows an issuer to add an event for a given dispute folder. Main data in input is the dispute folder identifier and the parameters of the event add operation.
API Links
This API allows the issuer to attach a document to a dispute folder identified by his dispute folder identifier. Supported document types are JPEG, TIFF and PDF.
The issuer must provide the data of the document in Base64 encoding format.
API Links