Balance and Payment

Balance And Payment

Post A Balance Adjustment Operation For An Account

API Reference

The API is used to generate a balance adjustment operation on an account.

The input account can be provided by using:

  • the account reference
  • 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

POST /api/V2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/post-balance-adjustment-operation

POST /api/V2/issuers/{issuerId}/accounts/{accountReference}/post-balance-adjustment-operation

Below an example of request and response for:

  • the account 12346393393948083995
  • the issuer 1234

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""        "
              }"    "
           }
        }

Post A Payment Operation For An Account

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:

  • 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

POST /api/V2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/post-payment-operation

POST /api/V2/issuers/{issuerId}/accounts/{accountReference}/post-payment-operation

Below an example of request and response for:

  • Account: 12348153189268935960
  • issuer: 1234

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""        "
              }"    "
           }
        }

Post A Reimbursement Operation To An Account

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:

  • 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

POST /api/V2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/post-reimbursement-operation

POST /api/V2/issuers/{issuerId}/accounts/{accountReference}/post-reimbursement-operation

Below an example of reimbursement operation posted to the:

  • account: 12348743536456021829
  • issuer: 1234

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""        "
              }"    "
           }
        }

Reverse A Balance Adjustment Operation For An Account

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 account reference generated by WL
  • or the issuer external account reference

The balance adjustment operation 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

POST /api/V2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/reverse-balance-adjustment-operation

POST /api/V2/issuers/{issuerId}/accounts/{accountReference}/reverse-balance-adjustment-operation

Below an example of request and response for:

  • the account 12346393393948083995
  • the issuer 1234

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""        "
              }"    "
           }
        }

Reverse A Payment Operation For An Account

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 account reference generated by WL
  • or the issuer external account reference

The payment 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

POST /api/V2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/reverse-payment-operation

POST /api/V3/issuers/{issuerId}/accounts/{accountReference}/reverse-payment-operation

Below an example of request and response for:

  • account: 12348153189268935960
  • issuer: 1234

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""        "
              }"    "
           }
        }

Load An Account

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:

  • 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

POST /api/V2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/post-load-operation

POST /api/V2/issuers/{issuerId}/accounts/{accountReference}/post-load-operation

Below an example of request and the response for:

  • issuer: 1234
  • Account: 283729323911384

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""        "
              }"    "
           }
        }

Unload An Account

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:

  • 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

POST /api/V2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/post-unload-operation

POST /api/V2/issuers/{issuerId}/accounts/{accountReference}/post-unload-operation

Below an example of request and the response for:

  • Account: 283729323911384
  • issuer: 1234

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""        "
              }"    "
           }
        }

List Direct Debits For An Account

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.

This API applies to the credit cards domain.

The input parameters are:

  • The issuer ID
  • The involved account: it can be provided by using the account reference or the issuer external account reference
  • Optionally the search period (start date / end date)

It is also possible to filter the payment operations (on demand, cyclic or on transaction).

API links

GET /api/V2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/direct-debits

GET /api/V2/issuers/{issuerId}/accounts/{accountReference}/direct-debits

Below an example of request for:

  • Account: 12349485785398617383
  • Issuer: 1234

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"\" 
                                } 
                            ] 
                        }"

Create A Direct Debit Instruction

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.

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 /api/v2/issuers/{issuerId}/direct-debits

Retrieve Direct Debit

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

GET /api/v2/issuers/{issuerId}/direct-debits/{endToEndId

Below an example of request for the:

  • Issuer : 1234
  • End to end Id: 1234-12349485785398617383-C202212020958

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""    "
        }
        }

Cancel A Direct Debit

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

POST /api/v2/issuers/{issuerId}/direct-debits/{endToEndId}/cancel

List Credit Transfers For An Account

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).

The input parameters are:

  • The issuer ID
  • The involved account: it can be provided by using the account reference or the issuer external account reference
  • Optionally the search period (start date / end date)

It is also possible to filter the reimbursement operations (on demand, cyclic, daily, on transaction or on contract termination).

API links

GET /api/V2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/credit-transfers

GET/ api/V2/issuers/{issuerId}/accounts/{accountReference}/credit-transfers

Below an example of request for:

  • Issuer 1234
  • Account reference: 658641608028488

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""        "
                      }"    "
                   ]
                }

Create A Credit Transfer Instruction

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 must 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 debited of the requested amount.

The API returns the unique Credit Transfer EndToEnd Identifier generated by our system and the Credit Transfer status.

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 /api/v2/issuers/{issuerId}/credit-transfers

Retrieve A Credit Transfer

This API enables an already created credit transfer instruction to be retrieved by providing in input the credit transfer E2E Identifier.

API links

GET /api/v2/issuers/{issuerId}/credit-transfers/{endToEndId}

Cancel A Credit Transfer

This API enables a credit transfer instruction to be cancelled by providing in input the credit transfer E2E Identifier.

API links

POST /api/v2/issuers/{issuerId}/credit-transfers/{endToEndId}/cancel

Cancel Account Delinquency

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:

  • the account reference generated by WL
  • or the issuer external account reference

Optionally, the required overdue minimum payment can be cancelled.

As a result:

  • the account is no more in delinquency situation
  • the amount due (required overdue minimum payment) is cancelled if this has been requested.

API links

POST /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/cancel-delinquency

POST /api/v2/issuers/{issuerId}/accounts/{accountReference}/cancel-delinquency

Reset The Balance Of An Account

The API resets the balance of an account by generating:

  • a credit operation (for a debit balance)
  • a debit operation (for a credit balance)

As an input, the account identifier can be provided by using:

  • the account reference generated by WL
  • or the issuer external account reference

This is relevant only for credit cards.

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 /api/V2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/reset-balance

POST /api/V2/issuers/{issuerId}/accounts/{accountReference}/reset-balance

Enable "on this page" menu on doc section
On

Statement Management

Statement Management

At cycle closure date raw statement data is prepared and can be exported at statement issuing date.

  • Either per contract, if all cards within this contract are repaid by the same payer
  • Or per card account, if each card is repaid by its cardholder

Each statement contains:

  • Cycle information
  • Minimum Payment amount
  • Payment due date
  • Direct debit amount (except if customer is self-payer)
  • List of distinct operations (scheme financial transactions, fees, debit interest, insurance fee, credit instalment repayments, etc) – grouped per card account (if several ones)

List Statements For An Account

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:

  • the involved account: it can be provided by using the account reference or the issuer external account reference
  • the search period (start date date/ end date)
  • the embed field "reprint-history" if needed

The API returns:

  • in the consumer cards context, the list of statements of the paying account
  • in the commercial cards context, the list of statements of the employee account whether it is paid by another account or not.

API links

GET /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/statements

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/statements

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""            "
                 }"        "
              }"    "
           ]
        }

Retrieve Last Statement For An Account

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:

  • the involved account: it can be provided by using the account reference or the issuer external account reference
  • the embed field "reprint-history" if needed

The API returns:

  • in the consumer cards context, the list of statements of the paying account
  • in the commercial cards context, the list of statements of the employee account whether it is paid by another account or not.

API links

GET /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/statements/last

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/statements/last

Below an example of request for the:

  • account: 12343037952407582600
  • Issuer: 1234

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""        "
              }"    "
           }
        }

List Operations For The Last Statement Of An Account

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:

  • the account reference
  • or the issuer external account reference

API links

GET /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/statements/last/operations

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/statements/last/operations

Below an example of request for the:

  • account: 12343037952407582600
  • Issuer: 1234

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""        "
      }"    "
   ]
}

Reprint Last Statement For An Account

The API is used to request the reprint of the last statement for an account.

The input account can be provided by using:

  • the account reference
  • or the issuer external account reference

As a result, the statement data is extracted again and pushed to the output management module.

API links

POST /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/statements/last/reprint

POST /api/v2/issuers/{issuerId}/accounts/{accountReference}/statements/last/reprint

Below an example of request for:

  • the account 12343037952407582600
  • the issuer 1234

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""    "
   }
}

List Operations For Next Account Statement

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:

  • the account reference
  • or the issuer external account reference

API links

GET /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/statements/next/operations

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/statements/next/operations

Below is an example where the request retrieves the operations of the next statement for:

  • Account reference : 12343037952407582600
  • Issuer : 1234

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""        "
      }"    "
   ]
}

Retrieve Statement With A Given Cyclic Closure Date

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 account reference
  • or the issuer external account reference

The statement involved by the request has to be provided by giving the cycle closure date.

The API returns:

  • in the consumer cards context, the list of statements of the paying account
  • in the commercial cards context, the list of statements of the employee account whether it is paid by another account or not.

API links

GET /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/statements/{cycleClosureDate}

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/statements/{cycleClosureDate}

Below is an example where the request retrieves the financial information of the statement for:

  • Account reference : 12343037952407582600
  • Issuer : 1234
  • Cycle closure date: 2022-07-28T22:00:00Z

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""        "
              }"    "
           }
        }

List Operations From A Statement With A Given Cyclic Closure Date

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 account reference
  • or the issuer external account reference

The statement involved by the request has to be provided by giving the cycle closure date.

API links

GET /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/statements/{cycleClosureDate}/operations

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/statements/{cycleClosureDate}/operations

Below is an example where the request retrieves the operations of the statement for:

  • Account reference : 12343037952407582600
  • Issuer : 1234
  • Cycle closure date: 2022-07-28T22:00:00Z

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"
      }
   ]
}

Reprint A Statement Identified By Its Cyclic Closure Date

The API is used to request the reprint of a statement for an account.

The input account can be provided by using:

  • the account reference
  • or the issuer external account reference

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

POST /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/statements/{cycleClosureDate}/reprint

POST /api/v2/issuers/{issuerId}/accounts/{accountReference}/statements/{cycleClosureDate}/reprint

Below an example of request for:

  • the issuer: 1234
  • the account: 12343037952407582600
  • the cycle closure date: 2022-10-28T00:00:00Z

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""    "
   }
}

Retrieve Next Statement For An Account

The API is used to get the financial information based on the last statement generated for an account such as: current cycle balance, cycle closure date, payment due date, next cycle closure date (end cycle balance, due amount, total of payments are not yet known).

The input parameters are:

  • The issuer Id
  • the involved account: it can be provided by using the account reference or the issuer external account reference

The API returns:

  • in the consumer cards context, the list of statements of the paying account
  • in the commercial cards context, the list of statements of the employee account whether it is paid by another account or not.

API links

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/statements/last

GET /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/statements/last

Enable "on this page" menu on doc section
On

Customer Address Management

Customer Address Management

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:

  • Create additional addresses for a customer
  • Retrieve customer address
  • Update address
  • Deactivate address
  • Activate address
  • Add an address usage
  • Remove an address usage
  • Invalidate an address
  • Create address and add-on subscription for a customer

Retrieve customer address

 

The API returns the current version of the customer's address identified with:

  • the reference of the customer,
  • the reference of the address.

This address is either a permanent address or a temporary address (if this one is active at the time of request).

The address identifiers, address attributes, address usages and entity reference (application domain of the address) are displayed in the response.

 

API Links

GET /api/V2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addresses/external-addresses/{issuerAddressExternalReference}

GET /api/V2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addresses/{addressReference}

GET /api/V2/issuers/{issuerId}/customers/{customerReference}/addresses/external-addresses/{issuerAddressExternalReference}

GET /api/v2/issuers/{issuerId}/customers/{customerReference}/addresses/{addressReference}

 

Below an example for :

  • Customer: CUS10000375016
  • Issuer: 1234

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"
                            }
                            ]
                            }

Create address for a customer

 

The API allows to create either a permanent address or a temporary address for the customer, identified with his reference.

An address includes the following information:

  • the issuer address external reference
  • the label (eg MAIN_POSTAL_ADDRESS),
  • the type (mail address, phone number, email) and the corresponding data
  • the address usages
  • the start date (optional, by default the current date is used)
  • the end date (conditional, is mandatory when creating a temporary address)

If the label of the address is already used for the customer, a new version will be created and active once the start date is reached.

When creating a temporary address, If a temporary address already exists with an overlap on the activity period then only the newly created address will be kept and the old one will be removed.

The temporary address is active between its start date and end date.

One or several address usages can be added to the address (in order to retrieve this address). An address usage is used for specific business process/service. When adding a usage to an address, the usage is immediately active and if it is already assigned to another address, it is removed from this latter.

For information, the main postal address is mandatory.

In return, the API provides the address Reference calculated by our system.

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 /api/V2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addresses

POST /api/V2/issuers/{issuerId}/customers/{customerReference}/addresses

Below an example of create address request for the customer:

  • Customer: CUS10000375016
  • Issuer: 1234

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"
                      }
                   }
                }

Update Address

The API allows to update the permanent address of a customer, identified with the reference of the customer and the reference of the address.

All the attributes must be provided even those unchanged, except the line 1 to 5 of the postal address if a specific issuer algorithm is configured.

If the address was invalid, the address becomes valid.

One or several address usages can be added to the address. An address usage is used for specific business process/service. When adding a usage to an address, the usage is immediately active and if it is already assigned to another address, it is removed from this latter.

All the usages already linked to the address cannot be removed via this API.

API Links

PUT /api/V2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addresses/external-addresses/{issuerAddressExternalReference}

PUT /api/V2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addresses/{addressReference}

PUT /api/v2/issuers/{issuerId}/customers/{customerReference}/addresses/{addressReference}

PUT /api/v2/issuers/{issuerId}/customers/{customerReference}/addresses/{issuerAddressExternalReference}

 

Below an example of the update request for:

  • The issuer: 1234
  • The customer: CUS10000375016
  • The address reference: ADDREF_SECOND_POSTAL_ADDRESS_1000000000440549

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"
                }

Deactivate Address

 

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:

  • the address is the MAIN_POSTAL_ADDRESS
  • an usage is linked to the address.

API Links

POST /api/V2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addresses/{addressReference}/deactivate

POST /api/V2/issuers/{issuerId}/customers/{customerReference}/addresses/external-addresses/{issuerAddressExternalReference}/deactivate

POST /api/v2/issuers/{issuerId}/customers/{customerReference}/addresses/{addressReference}/deactivate

POST /api/v2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addresses/{issuerAddressExternalReference}/deactivate

 

Below an example of deactivate address request for:

  • the issuer: 1234
  • the customer: CUS10000375016
  • the address reference: ADDREF_SECOND_POSTAL_ADDRESS_1000000000440549

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"
   }
}

Add an address usage

 

The address usage describes in which business case the address will be used (eg statement sending, cad 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:

  • Issuer ID
  • Customer reference or the issuer customer reference
  • Address reference or the issuer address reference

API Links

POST /api/V2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addresses/{addressReference}/address-usages

To create an address usage, it is needed to provide:

POST /api/V2/issuers/{issuerIdcreateAddressUsageByCustomerIssuerExtRef}/customers/{customerReference}/addresses/external-addresses/{issuerAddressExternalReference}/address-usages

POST /api/v2/issuers/{issuerId}/customers/{customerReference}/addresses/{addressReference}/address-usages

POST /api/v2/issuers/{issuerId}/customers/{customerReference}/addresses/{issuerAddressExternalReference}/address-usages

 

Below an example of the update request for:

  • The issuer: 1234
  • The customer: CUS10000375016
  • The address reference: ADDREF_SECOND_POSTAL_ADDRESS_1000000000440550

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"
           }
        }

Remove an address usage

 

The API deletes the address usages linked to one address.

These address usages are filtered by the request params:

  • addressUsageName (for definition see the ressource addressUsage), mandatory
  • entityReference (for definition see the ressource addressUsage), optional
  • serviceCode (for definition see the ressource addressUsage), mandatory

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

DELETE /api/V2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addresses/{addressReference}/address-usages

DELETE /api/V2/issuers/{issuerId}/customers/{customerReference}/addresses/external-addresses/{issuerAddressExternalReference}/address-usages

DELETE /api/v2/issuers/{issuerId}/customers/{customerReference}/addresses/{addressReference}/address-usages

DELETE /api/v2/issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/addresses/{issuerAddressExternalReference}/address-usages

 

Below an example of delete address request for

  • the issuer: 1234
  • the customer: CUS10000375016
  • the address reference: ADDREF_SECOND_POSTAL_ADDRESS_1000000000440549

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"
         }
      ]
   }
}

Invalidate an address

 

The API is used to invalidate the address identified with the customer reference (external or internal) and the address reference (external or internal).

The invalidation is applied only on the permanent address.

The address must be a postal address. If the user tries to invalidate another kind of address (PHONE/E_MAIL), an error is returned.

The attribute 'invalid' becomes 'true'.

API Links

POST /api/v2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addresses/external-addresses/{issuerAddressExternalReference}/invalidate

POST /api/v2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addresses/{addressReference}/invalidate

POST /api/v2/issuers/{issuerId}/customers/{customerReference}/addresses/external-addresses/{issuerAddressExternalReference}/invalidate

POST /api/v2/issuers/{issuerId}/customers/{customerReference}/addresses/{addressReference}/invalidate

 

Create address and add-on subscription for a customer

 

The API allows to create either a permanent address or a temporary address for the customer, identified with his reference, and to subscribe to an additional service (e.g. new letter, travel insurance) for a contract during all contract life cycle.

An address includes the following information:

  • the issuer address external reference
  • the label (e.g. MAIN_POSTAL_ADDRESS),
  • the type (mail address, phone number, email) and the corresponding data
  • the address usages
  • the start date (optional, by default, the current date is used)
  • the end date (conditional, only used when defining a temporary address)

When creating a temporary address, If a temporary address already exists with an overlap on the activity period then only the newly created address will be kept and the old one will be removed.

For information, the main postal address is mandatory.

A subscription to an additional service includes the following information:

  • The identifier of the entity for which the add-on subscription is requested: Either the card contract by providing the card contract reference or the issuer external card contract reference, OR the account by providing the account reference or the issuer external account reference
  • The corresponding reference of the additional service
  • The service type reference defined at product level

The list of allowed additional services are defined on the product (e.g. PORTAL_ACCESS, ALERT, NOTIFICATION).

Depending on the service type, the issuer can add additional parameters to the add-on service.

As a result:

  • The new add-on subscription for the contract is available and can be unsubscribed during all contract life cycle
  • A fee can be generated and posted to the cardholder account if required for the product.

In return, the API provides the address reference calculated by the system.

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 /api/V2/issuers/{issuerId}/customers/{customerReference}/addressesAndSubsciptions

POST /api/V2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addressesAndSubsciptions

 

Delete an address for a customer

 

The API allows a future permanent address or a temporary address (active or future) to be deleted.

The main input fields requested by the API are:

  • The issuer ID
  • The customer for which the address deletion is requested : It can be provided by using the customer reference or the issuer customer external reference
  • The address of the customer for which the deletion is requested : It can be provided by using the address reference or the issuer address external reference
  • The version reference of the address to be deleted

As result, the version of the customer address is deleted. If the address was an active temporary address, its end date is updated (set to the current date).

In response, the interface provides:

  • the address identifier (address reference or the issuer address external reference)
  • the deleted version reference of the address

API Links

DELETE /api/v2/issuers/{issuerId}/customers/{customerReference}/addresses/{addressReference}/address-versions/{addressVersionReference}

DELETE /api/v2/issuers/{issuerId}/customers/{customerReference}/external-addresses/{issuerAddressExternalReference}/address-versions/{addressVersionReference}

DELETE /api/v2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addresses/{addressReference}/address-versions/{addressVersionReference}

DELETE /api/v2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/external-addresses/{issuerAddressExternalReference}/address-versions/{addressVersionReference}

 

Retrieve the list of versions of a customer address

 

The API allows the versions of a customer address to be retrieved.

The main input fields requested by the API are:

  • The issuer ID
  • The customer : It can be provided by using the customer reference or the issuer customer external reference
  • The address of the customer for which the versions list is requested : It can be provided by using the address reference or the issuer address external reference

In response, the interface returns address data with the address version reference.

API Links

GET /api/v2/issuers/{issuerId}/customers/{customerReference}/addresses/{addressReference}/address-versions

GET /api/v2/issuers/{issuerId}/customers/{customerReference}/external-addresses/{issuerAddressExternalReference}/address-versions

GET /api/v2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addresses/{addressReference}/address-versions

GET /api/v2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/external-addresses/{issuerAddressExternalReference}/address-versions

 

Enable "on this page" menu on doc section
On

Customer Information Management

Customer Information Management

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.    

List customers

 

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

GET /api/V2/issuers/{issuerId}/customers

 

Find an example where the request retrieves the customers list for:

  • Issuer : 1234
  • Customer name : MATISSE
  • First name: Jack

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"
      }
   ]
}

Retrieve customer information

 

The "retrieve customer" API allows the user to get customer information from the input parameters:

  • Issuer ID
  • Customer reference or the issuer customer reference

In addition to the person information, it is also possible to request the list of addresses of the customer and the address usages by using the embedded fields.

 

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:

  • Customer reference : CUS10000375046
  • Issuer : 1234

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"
        }

List contracts for a customer

This API allows to retrieve all contracts associated with a specific customer, regardless of their role in the contract (e.g., contract owner, card holder, account owner).

Information to be provided in input:

  • Issuer ID
  • The customer for which information is requested : It can be provided by using the customer reference or the issuer customer external reference.

The customer must exist for the provided issuer.

The API returns all contracts linked to the given customer for the provided issuer and sub-issuers if any, limited to the list of issuers allowed for the user.

API Links

GET /api/V2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/contracts

GET /api/V2/issuers/{issuerId}/customers/{customerReference}/contracts

 

Find an example where the request retrieves all the contracts for:

  • Customer reference : CUS10000375046
  • Issuer : 1234

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"
                                 }
                              }
                           ]
                        }

List card contracts for a cardholder

 

This API enables all the card contracts associated with the cardholder to be retrieved.

Information to be provided in input:

  • Issuer ID
  • Customer reference

The customer must exist for the provided issuer.

The API returns all card contracts linked to the given cardholder for the provided issuer and sub-issuers if any, limited to the list of issuers allowed for the user.

 

API Links

GET /api/V2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/card-contracts

GET /api/V2/issuers/{issuerId}/customers/{customerReference}/card-contracts

 

Find an example where the request retrieves all the card contracts for:

  • Customer reference : CUS10000375046
  • Issuer : 1234

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"
              }
           ]
        }

List addresses for a customer

 

This API enables all the addresses associated with a given customer, identified by his customer reference, to be retrieved. This address could be either a permanent address or a temporary address.

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 behavior) 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

GET /api/V2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addresses

GET /api/V2/issuers/{issuerId}/customers/{customerReference}/addresses

 

Below an example of request and response for:

  • The issuer : 1234
  • The customer: CUS10000375016

The show history is requested in the response in order to have also the previous and the future addresses.

  • Main postal address (reference: ADDREF_MAIN_POSTAL_ADDRESS_1000000000417761) with the current address and the future address
  • Inactive second postal address (reference: ADDREF_SECOND_POSTAL_ADDRESS_1000000000440549
  • Active second postal address (reference: ADDREF_SECOND_POSTAL_ADDRESS_1000000000440550) with 3 changes

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"
                              }
                           ]
                        }

List accounts for an account owner

 

This API enables all the accounts associated with the customer (cardholder) to be retrieved.

The customer must exist for the provided issuer.

The API returns all accounts linked to the given account owner for the provided issuer and sub-issuers if any, limited to the list of issuers allowed for the user.

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

GET /api/V2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/accounts

GET /api/V2/issuers/{issuerId}/customers/{customerReference}/accounts

Update customer

 

The "update customer" API allows the user to update the attributes of a customer.

To identify the customer, it is needed to provide:

  • The issuer ID
  • The customer reference (internal or external) for which updates are required

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

PUT /api/V2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}

PUT /api/V2/issuers/{issuerId}/customers/{customerReference}

Update customer partially

 

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 issuer ID
  • The customer reference (internal or external) for which updates are required

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.

In case the property Contact (list) is provided in input then it will replace the existing list.

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:

  • The second first name
  • The sex
  • The birth date
  • The birth place

For:

  • Customer reference : CUS10000375046

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"
              }
           }
        }

Create a contact for a customer

 

The API creates a contact person belonging to the customer (person) by providing information such as first name, name, department to which he is attached.

To create a contact, it is needed to provide:

  • The issuer ID
  • The customer reference or the issuer customer 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

POST /api/V2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/contacts

POST /api/V2/issuers/{issuerId}/customers/{customerReference}/contacts

Update a contact for a customer

 

The API allows information of a contact of the customer (person) to be modified.

To update a contact, it is needed to provide:

  • The issuer ID
  • The customer reference or the issuer customer reference
  • The contact reference

All attributes must be provided (even if some of them have not been modified) else the value of missing attributes will be empty.

 

API Links

PUT /api/V2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/contacts/{contactReference}

PUT /api/V2/issuers/{issuerId}/customers/{customerReference}/contacts/{contactReference}

Remove a contact for a customer

 

The API allows a contact of the customer (person) to be deleted.

To remove a contact, it is needed to provide:

  • The issuer ID
  • The customer reference or the issuer customer reference
  • The contact reference

 

API Links

DELETE /api/V2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/contacts/{contactReference}

DELETE /api/V2/issuers/{issuerId}/customers/{customerReference}/contacts/{contactReference}

Create a customer as a person

 

The API allows a new customer (as person) to be created if all the mandatory fields are provided.

The main input fields are:

  • The issuer ID
  • The first name of the customer
  • The last name of the customer
  • The default address of the customer : The Main postal address has to be provided because used as default address by all business processes if no address usage is defined.

The API returns the customer reference (as person) generated by our system.

The response can also be enriched (if specified as embedded fields in input) with additional data such as customer (as person) information, address identifiers linked to the customer, addresses of the customer, contacts of the customer.

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

DELETE /api/V2/issuers/{issuerId}/customers

Retrieve list of historic updates of a customer

 

The API allows the customer update history of a customer to be retrieved.

The main input fields requested by the API are:

  • The issuer ID
  • The customer for which information is requested : It can be provided by using the customer reference or the issuer customer external reference.

A start date and an end date can be provided in order to limit the search of the history.

In response, the interface provides a list of changes with the effective date of the update.

 

API Links

GET/api/V2/issuers/{issuerId}/customers/{customerReference}/customer-history

GET/api/V2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/customer-history

Enable "on this page" menu on doc section
On

Disputes

Disputes

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.

 

Dispute

 

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.

    

Create a dispute and optionally posting, event or external document add (Deprecated)

 

This API is deprecated and is replaced by the API Create a dispute from a transaction.

The "Create a dispute" API allows an issuer to create a dispute folder in the system for a given operation.

This API enables the issuer to initiate the dispute from its application.

Several actions can be performed at the same time using this API:

  • Dispute only
  • Dispute + refund/redebit (full or partial)
  • Dispute + write-off (full or partial)
  • Dispute + fraud declaration
  • Dispute + event creation
  • Dispute + attach documents 
  • Dispute + combination of above options

Main data in input are :

  • the external operation reference which can be retrieved using a search operation in the system, for example using the API retrieves list of operations for an account
  • in option, several fields in the case additional actions have to be done besides the dispute folder creation (e.g. operation(s) posting, event(s) creation, add document(s))

In response, the created dispute folder identifier is provided back systematically; then depending on the additional requests, the response includes also the posting, event creation and documents add response.

 

API Links

POST /api/v2/issuers/{issuerId}/operations/{externalOperationReference}/disputes

 

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"
                                         }
                                      ]
                                   }
                                }

Generate a chargeback

 

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:

  • The dispute folder identifier
  • The type of chargeback (partial or total for most of the cases)
  • The chargeback scenario name used for VISA that supports the automated process (E-commerce fraud, duplicate Processing, Non-Receipt of Cash) or the chargeback reason code for MasterCard that can be found in MCI MPE file.

In response, the scheme case identifier is provided back.

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 /api/v2/issuers/{issuerId}/disputes/{disputeFolderReference}/generate-chargeback

POST /api/v2/issuers/{issuerId}/disputes/external-disputes/{issuerDisputeExternalReference}/generate-chargeback

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"
                   }
                }

Retrieve dispute information for a given dispute folder

 

The API returns the dispute folder information that matches the dispute folder identifier provided in input.

This enables the dispute information to be retrieved:

  • General dispute folder information including the dispute reason, the status
  • Cardholder information including the card status and billing amount
  • The issuer accounting balance
  • The transaction details including the reconciliation amount, the transaction type and merchant information

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"
           }
        }

Retrieve dispute information for a given operation

 

The API returns the dispute folder information if the transaction identified by an operation Identifier is disputed.

If it is the case, this enables to see the content of the dispute information:

  • General dispute folder information including the dispute reason, the status
  • Cardholder information including the card status and billing amount
  • The issuer accounting balance
  • The transaction details including the reconciliation amount, the transaction type and merchant information

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

GET /api/v2/issuers/{issuerId}/operations/{operationId}/dispute

List dispute folders for a given card

 

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:

  • General dispute folder information including the dispute reason, the status
  • Cardholder information including the card status and billing amount
  • The issuer accounting balance
  • The transaction details including the reconciliation amount, the transaction type and merchant information

 

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

GET /api/v2/issuers/{issuerId}/cards/{cardReference}/disputes

GET /api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/disputes

Create a posting

 

The issuer can provide a posting operation to be performed on the created dispute folder.

The posting operation can be for example:

  • perform a refund towards the cardholder account
  • perform a write-off towards an issuer account (Profit and Loss, Fraud,..)

"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.

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 /api/v2/issuers/{issuerId}/disputes/{disputeFolderReference}/postings

POST /api/v2/issuers/{issuerId}/disputes/external-disputes/{issuerDisputeExternalReference}/postings

Create an event

 

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.

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 /api/v2/issuers/{issuerId}/disputes/{disputeFolderReference}/events

POST /api/v2/issuers/{issuerId}/disputes/external-disputes/{issuerDisputeExternalReference}/events

Add external document to a dispute folder

 

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.

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 /api/v2/issuers/{issuerId}/disputes/{disputeFolderReference}/documents

POST /api/v2/issuers/{issuerId}/disputes/external-disputes/{issuerDisputeExternalReference}/documents

Create a super folder

 

This API allows the creation of a super folder from a list of dispute folders.

The main input fields are:

  • The issuer ID
  • The list of dispute folder identifiers to be attached to the super folder : The dispute folder references must exist in our system and be associated to the same PAN.

The issuer can provide the name of the super folder to be created.

As a result, the super folder is created with its own reference calculated by our system.

The API response returns:

  • The super folder reference
  • The name of the super folder if provided in the request

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 /api/v2/issuers/{issuerId}/super-folders

Enable "on this page" menu on doc section
On

Permanent And Temporary Credit Limit

Permanent And Temporary Credit Limit

For each credit account, a credit limit is defined. When the account is created the credit limit value is set with the default value inherited from the product configuration; it can be also set during the creation of a contract.

Each permanent credit limit can be updated during the contract and credit card account lifecycle, within the range allowed by the Issuer.

Once updated, the new credit limit value is immediately available for next authorizations.

Issuers can also use temporary credit limit management for a credit card account.

The temporary credit limit can be added to an existing credit card account:

  • for a given period
  • the temporary credit limit value can be higher or lower than the permanent one but is limited by an exceptional amount, which is allowed by the Issuer per product

Once added the temporary credit limit is immediately available for next authorizations.

In our solution each Temporary Credit Limit is identified by a unique temporaryCreditLimitReference.

A set of API is provided in order to:

  • Retrieve current credit limit for an account
  • Update account credit limit
  • Retrieve the list of temporary credit limits for a given account
  • Create temporary credit limit
  • Delete temporary credit limit

Retrieve Account Credit Limit

The API allows the permanent credit limit for a given account to be retrieved.

API links

GET /api/V2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/credit-limit

GET /api/V2/issuers/{issuerId}/accounts/{accountReference}/credit-limit

Below an example of request for the:

  • Account: 12348153189268935960
  • Issuer: 1234

GET /api/v2/issuers/1234/accounts/12348153189268935960/credit-limit

Response data

{
   "   ""data":" "{
      "        ""creditLimitAmount":" "{
         "            ""value": 100000,
         "            ""exponent": 2,
         "            ""isoCode":" ""EUR""        "
      }"    "
   }
}

Update Account Credit Limit

The API allows the permanent credit limit for a given account to be updated.

API links

PUT /api/V2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/credit-limit

PUT /api/V2/issuers/{issuerId}/accounts/{accountReference}/credit-limit

Below an example of request for the:

  • Account: 12348153189268935960
  • Issuer: 1234

PUT /api/v2/issuers/1234/accounts/12348153189268935960/credit-limit

Request data

{
   "  ""creditLimitAmount":" "{
      "    ""value": 500000,
      "    ""exponent": 2,
      "    ""isoCode":" ""EUR""  "
   }
}

Response data

{
   " ""responseMetadata":" "{
      "        ""correlationId":" ""75119fff-0da4-4ffd-841b-7bf1744ecdf4",
      "        ""statusMessage":" ""Executed successfully",
      "        ""statusCode": 200,
      "        ""responseDateTime":" ""2023-02-03T16:22:57.481+0100",
      "        ""timeTakenMs": 132 
    
   },
   "    ""data":" "{
      "        ""creditLimitAmount":" "{
         "            ""value": 500000,
         "            ""exponent": 2,
         "            ""isoCode":" ""EUR""        "
      }"    "
   }
}

Retrieve Temporary Credit Limits For An Account

The API allows the temporary credit limits for a given account to be retrieved.

It is possible to request either only the active temporary credit limit or the history of temporary limits for the account.

API links

GET /api/V2//issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/temporary-credit-limits

GET /api/V2/issuers/{issuerId}/accounts/{accountReference}/temporary-credit-limits

Below an example of request for the:

  • Account: 12348153189268935960
  • Issuer: 1234

GET /api/v2/issuers/1234/accounts/12348153189268935960/temporary-credit-limits?all=false

Response data

{
   " ""data":" "[
      "        "{
         "            ""temporaryCreditLimitIdentifier":" "{
            "                ""temporaryCreditLimitReference":" ""94d757e5-7bca-4394-95e9-e8d9e00e7cd5""            "
         },
         "            ""activationStartTime":" ""2023-02-03T00:00:00.000+00:00",
         "            ""activationEndTime":" ""2023-04-01T00:00:00.000+00:00",
         "            ""temporaryCreditLimitAmount":" "{
            "                ""value": 750000,
            "                ""exponent": 2,
            "                ""isoCode":" ""EUR""            "
         }"        "
      }"    "
   ]
}

Create A Temporary Credit Limit For An Account

The API allows temporary credit limits for a given account to be created.

In response, a temporary credit limit reference is provided.

Once added, the temporary credit limit is immediately available for next authorizations.

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 /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/temporary-credit-limits

POST /api/v2/issuers/{issuerId}/accounts/{accountReference}/temporary-credit-limits

Below an example of request for the:

  • Account: 12348153189268935960
  • Issuer: 1234

POST /api/v2/issuers/1234/accounts/12348153189268935960/temporary-credit-limits

Request data

{
           " ""temporaryCreditLimitAmount":" "{
              "    ""value": 750000,
              "    ""exponent": 2,
              "    ""isoCode":" ""EUR""  "
           },
           "  ""activationStartTime":" ""2023-02-03T00:00:00.000Z",
           "  ""activationEndTime":" ""2023-04-01T00:00:00.000Z"
        }

Response data

{
           " ""responseMetadata":" "{
              "        ""correlationId":" ""fe5eaec9-c707-4ee8-aac3-fb36804b44df",
              "        ""statusMessage":" ""Executed successfully",
              "        ""statusCode": 200,
              "        ""responseDateTime":" ""2023-02-03T16:34:11.810+0100",
              "        ""timeTakenMs": 149 
            
           },
           "    ""data":" "{
              "        ""temporaryCreditLimitIdentifier":" "{
                 "            ""temporaryCreditLimitReference":" ""94d757e5-7bca-4394-95e9-e8d9e00e7cd5""        "
              },
              "        ""temporaryCreditLimitAmount":" "{
                 "            ""value": 750000,
                 "            ""exponent": 2,
                 "            ""isoCode":" ""EUR""        "
              },
              "        ""activationStartTime":" ""2023-02-03T00:00:00.000+00:00",
              "        ""activationEndTime":" ""2023-04-01T00:00:00.000+00:00""    "
           }
        }

Delete A Temporary Credit Limit For An Account

An existing temporary credit limit (active or scheduled) can be disabled at any moment.

The API allows a temporary credit limit for a given account to be deleted by providing the temporary credit limit reference.

API links

DELETE /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/temporary-credit-limits/{temporaryCreditLimitReference}

DELETE /api/v2/issuers/{issuerId}/accounts/{accountReference}/temporary-credit-limits/{temporaryCreditLimitReference}

Below an example of request and response for:

  • the account 12346393393948083995
  • the issuer 1234
  • the temporary credit limit reference: 94d757e5-7bca-4394-95e9-e8d9e00e7cd5

DELETE /api/1234/accounts/12348153189268935960/temporary-credit-limits/94d757e5-7bca-4394-95e9-e8d9e00e7cd5

Response data

{
           "    ""responseMetadata":" "{
              "        ""correlationId":" ""e064d310-8c97-40fb-8331-02443e986945",
              "        ""statusMessage":" ""Executed successfully",
              "        ""statusCode": 200,
              "        ""responseDateTime":" ""2023-02-03T16:48:04.819+0100",
              "        ""timeTakenMs": 131 
            
           },
           "    ""data":" "{
              "        ""temporaryCreditLimitIdentifier":" "{
                 "            ""temporaryCreditLimitReference":" ""94d757e5-7bca-4394-95e9-e8d9e00e7cd5""        "
              }"    "
           }
        }
Enable "on this page" menu on doc section
On

Card Controls-Velocity Limits

Velocity Limits

Velocity Limits

Velocity Limits define conditions to limit the cumulated amount and/or the number of transactions in a period.  
When an Account is created, the default Velocity Limits as defined at the specific Product level are applied: 
the product initial setup defines the applicable conditions and whether they are, by default, checked or not.  
Each applicable Velocity Limit is identified by a specific "velocityLimitReference". 

Standard Velocity Limits can be configured to limit authorizations in following use cases (checking criteria): 
    w  cash (ATM, branch, POS); [NB incl. cash withdrawal, cash advance, cashback] 
    w  contactless (NFC); 
    w  e-Commerce; 
    w  POS.  

Standard Velocity Limits have specific time periods for accumulating amounts and/or counting transactions; 
the standard types of time periods can be a day, a week, a month or a time window (rolling/sliding, jumping); 
depending on the period type, the period start can be an hour of the day, any weekday, a day in the month.  

Each Standard Velocity Limit are set with 3 thresholds and 3 corresponding flags to enable/disable checking: 
a minimum and a maximum for the cumulated amount, a maximum for the number of transactions in period. 

A Velocity Limit can be further combined with a country or a region (additional criteria to apply the check). 

The "VelocityLimit" objects include the following properties: 
    w  "velocityLimitReference", descriptive identification string; 
        (NB it is embedded in the "velocityLimitIdentifier" object) 
        (used as parameter in the path of the operations related to the limit) 
    w  "name", a (brief but hopefully meaningful) textual description for the limit; 
    §  "amount", cumulated authorization amount in period [debits: positive, credits: negative]; and 
    §  "count", the current number of transactions in period; NB values at operation execution time; 

    w  "minimumAmountCheck", indicating whether the cumulated authorization "amount" in period is 
        [to be] checked against the below "minimumAmount" threshold (so the limit applies) or not (²); 
    w  "minimumAmountCheckOrigin", indicating from which level the above flag has been taken (°); 
    w  "minimumAmount", minimum threshold for the "amount" check (²), if "minimumAmountCheck" is true; 
    w  "minimumAmountOrigin", level from which the "minimumAmount" has been taken (°), if any present; 
    w  "maximumAmountCheck", indicating whether the cumulated authorization "amount" in period is 
        [to be] checked against the below "maximumAmount" threshold (so the limit applies) or not (²); 
    w  "maximumAmountCheckOrigin", indicating from which level the above flag has been taken (°); 
    w  "maximumAmount", maximum threshold for the "amount" check (²), if "maximumAmountCheck" is true; 
    w  "maximumAmountOrigin", level from which the "maximumAmount" has been taken (°), if any present; 
    w  "maximumCountCheck", indicating whether the "count" number of transactions in period is 
        [to be] checked against the below "maximumCount" threshold (so the limit applies) or not (²); 
    w  "maximumCountCheckOrigin", indicating from which level the above flag has been taken (°); 
    w  "maximumCount", maximum threshold for the "count" check (²), if "maximumCountCheck" is true; 
    w  "maximumCountOrigin", level from which the "maximumCount" has been taken (°), if any present; 

    w  "velocityLimitOverrideReference", identification of an applicable override, if any (²); 
    w  "velocityLimitOverrideStartdate", time to start applying the override, if any applicable (²); 
    w  "velocityLimitOverrideEnddate", time to stop applying the override, if any applicable (²). 
NB (°) possible origin values as defined by enumeration: “Default”, “Exception”, “Override”, “Other” (²).  
NB (²) value as effective at operation execution time, esp. possibly changed via velocity limit override. 

Operations on Velocity Limits: 
("tags":["Account - Velocity Limit"]) 
    w  List the Velocity Limits (for an account), 
    w  Retrieve a Velocity Limit (by reference). 

Velocity Limit Overrides

Velocity Limits can be changed by creating or updating Velocity Limit Overrides. 
A Velocity Limit Override is identified by its "velocityLimitOverrideReference". 

A Velocity Limit Override can be set to apply from a given (start) moment and/or until a given (end) moment.  
A Velocity Limit Override can be set to change 2 thresholds and the 2 corresponding flags for their checking: 
the maximum for the cumulated amount in period and the maximum for the number of transactions in period. 

The "VelocityLimitOverride" objects include the following properties: 
    w  "velocityLimitOverrideReference", its identification string; 
        (embedded in the "velocityLimitOverrideIdentifier" object) 
        generated by Worldline at the Velocity Limit Override creation; 
        (used as parameter in the path of the operations related to the override) 
    w  "velocityLimitReference", overridden velocity limit identification; 
        (embedded in the "defaultVelocityLimitReference" object) 
        (used as parameter in the path of the operations related to its override[s]) 
    w  "deleted", indicating whether the override has been deleted or is still present; 
        remark: all of the properties hereafter are absent if the override is "deleted"; 

        remark: each of the following properties is optional; 
    w  "activationStartTime", the (first) point in time to start applying the override; 
        optional (if not provided, no delay to start: the override applies immediately) 
        must be before "activationEndTime" if any (can be present without an end time)
    w  "activationEndTime", the (last) point in time to stop applying the override; 
        optional (if not provided, no stop scheduled: the override applies endlessly) 
        must be after "activationStartTime" if any (can be present without a start time)

    w  "minimumAmountCheck", indicating whether the "minimumAmount" is to be checked; 
    w  "minimumAmount", minimum threshold to check, if "minimumAmountCheck" is true; 
    w  "maximumAmountCheck", indicating whether the "maximumAmount" is to be checked (°); 
    w  "maximumAmount", maximum threshold to check (°), if "maximumAmountCheck" is true; 
    w  "maximumCountCheck", indicating whether the "maximumCount" is to be checked (°); 
    w  "maximumCount", maximum threshold to check (°), if "maximumCountCheck" is true; 

    w  "priority", used to apply overrides in ascending order of "priority" (from lowest to highest) 
        in the case of different overrides - on a same velocity limit - whose effective timespans overlap; 
        must be different for all co-occurring overrides (not if they are never effective simultaneously)  
        (if not provided, will be set to 0).  

NB (°) it overrides the default configured for the corresponding property of the referenced Velocity Limit.  
           if it is set to “null”, the default value as configured on higher levels for the Velocity Limit is effective.  

Operations on Velocity Limit Overrides: 
("tags":["Account - Velocity Limit"]) 
    w  List the Velocity Limit Overrides (for a limit), 
    w  Create a Velocity Limit Override (for a limit), 
    w  Retrieve a Velocity Limit Override (by reference), 
    w  Update a Velocity Limit Override (by reference), 
    w  Delete a Velocity Limit Override (by reference). 

List the Velocity Limits

Operation to get the list of Velocity Limits on an Account. 

A (success) response will provide an array of "VelocityLimit" objects.  
The main properties replied (if success), per Velocity Limit, are: 
(NB values currently in effect at the time the operation is performed.)  
    w  "velocityLimitReference" and "name", 
    §  "amount" and "count" (current values of the accumulator and counter); 
    w  "minimumAmountCheck" and "minimumAmountCheckOrigin", 
    w  "minimumAmount" and "minimumAmountOrigin" if "minimumAmountCheck" is true; 
    w  "maximumAmountCheck" and "maximumAmountCheckOrigin", 
    w   "maximumAmount" and "maximumAmountOrigin" if "maximumAmountCheck" is true; 
    w  "maximumCountCheck" and "maximumCountCheckOrigin", 
    w  "maximumCount" and "maximumCountOrigin" if "maximumCountCheck" is true; 
    w  "velocityLimitOverrideReference" (if any applicable, and then -possibly- following dates); 
    w  "velocityLimitOverrideStartdate" and/or "velocityLimitOverrideEnddate" (if applicable).  

 API Links

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/velocity-limits

GET /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/velocity-limits

 Example
the replied Velocity Limit relating to the e-Commerce is in effect, regarding the maximum cumulated amount, 
identified by the "velocityLimitReference": “VELOCITY_LIMIT_ECOM”, with its "maximumAmountCheck": true. 

GET /api/v2/issuers/98003/accounts/468762732120914/velocity-limits
                --header 'WL-Correlation-ID: 72fe1881-2c05-48bb-a7f8-3231c6ad3342' \
                        {   "issuerId": "98003",
                            "velocityLimitIdentifier": {
                                "velocityLimitReference": "VELOCITY_LIMIT_ECOM"},
                            "name": "E-commerce"
                           "minimumAmountCheck": false, "minimumAmountCheckOrigin": "Default",
                           "maximumAmountCheck": true,  "maximumAmountCheckOrigin": "Default",
                            "maximumAmount": {"value": 250000, "exponent": 2, "isoCode": "EUR"},
                           "maximumAmountOrigin": "Default",
                           "maximumCountCheck": false,  "maximumCountCheckOrigin": "Default",}
                /* and other existing velocity limits */

Retrieve a Velocity Limit

Operation to fetch an existing Velocity Limit, identified by its "velocityLimitReference". 

A (success) response will provide properties as for a "VelocityLimit" object (cf. “List the Velocity Limits”). 

API Links

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/velocity-limits/{velocityLimitReference}

GET /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/velocity-limits/{velocityLimitReference}

List the Velocity Limit Overrides

Operation to get the list of overrides on a Velocity Limit, identified by its "velocityLimitReference".  
NB It includes the "deleted" overrides (if any). 

A (success) response will provide an array of "VelocityLimitOverride" objects.  
The main properties replied (if success), per Velocity Limit Override, are: 
    w  "velocityLimitOverrideReference", 
    w  "velocityLimitReference", 
    w  "deleted" (no other properties hereafter if "deleted" is true); 
    w  "activationStartTime" (if any) and/or "activationEndTime" (if any); 
    w  "minimumAmountCheck", and "minimumAmount" if "minimumAmountCheck" is true; 
    w  "maximumAmountCheck", and "maximumAmount" if "maximumAmountCheck" is true; 
    w  "maximumCountCheck", and "maximumCount" if "maximumCountCheck" is true; 
    w  "priority". 

API links

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/velocity-limits/{velocityLimitReference}/velocity-limit-overrides

GET /apiv2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/velocity-limits/{velocityLimitReference}/velocity-limit-overrides

Create a Velocity Limit Override

Operation to override a Velocity Limit, identified by its "velocityLimitReference". 

The following properties can be provided: 
    w  "activationStartTime" (optional); 
    w  "activationEndTime" (optional); 
    w  "maximumAmountCheck" (optional); 
    w  "maximumAmount" if "maximumAmountCheck" is true; 
    w  "maximumCountCheck" (optional);
    w  "maximumCount" if "maximumCountCheck" is true; 
    w  "priority" (optional). 

A (success) response will return the generated: 
    w  "velocityLimitOverrideReference". 

API links

POST /api/v2/issuers/{issuerId}/accounts/{accountReference}/velocity-limits/{velocityLimitReference}/velocity-limit-overrides

POST /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/velocity-limits/{velocityLimitReference}/velocity-limit-overrides

Example to override the Velocity Limit relating to the e-Commerce, regarding the maximum amount, 
identified by the "velocityLimitReference" “VELOCITY_LIMIT_ECOM”, with "maximumAmountCheck" true, 
setting the override "maximumAmount" to 0 EUR to decline all new e-commerce authorizations in EURO. 

POST /api/v2/issuers/98003/accounts/468762732120914/velocity-limits /VELOCITY_LIMIT_ECOM/velocity-limit-overrides' \
    --header 'WL-Correlation-ID: 430d0f91-a958-4dda-858e-c9e1595422eb' \
    --header 'Content-Type: application/json' \
    --data-raw '{"maximumAmount": {"value": 0, "exponent": 2, "isoCode": "EUR"}}’

Retrieve a Velocity Limit Override

Operation to fetch an existing Velocity Limit Override, identified by its "velocityLimitOverrideReference". 
NB It will also provide the information for a "deleted" override. 

A (success) response will provide properties as for a "VelocityLimitOverride" object 
(cf. “List the Velocity Limit Overrides”). 

API links

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/velocity-limits/{velocityLimitReference}/velocity-limit-overrides/{velocityLimitOverrideReference}

GET /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/velocity-limits/{velocityLimitReference}/velocity-limit-overrides/{velocityLimitOverrideReference}

Update a Velocity Limit Override

Operation to update an existing Velocity Limit Override, identified by its "velocityLimitOverrideReference". 

Any of the following properties can (optionally) be updated: 
    w  "activationStartTime"; 
    w  "activationEndTime"; 
    w  "maximumAmountCheck"; 
    w  "maximumAmount" if "maximumAmountCheck" is true; 
    w  "maximumCountCheck"; 
    w  "maximumCount" if "maximumCountCheck" is true; 
    w  "priority". 

API links

PUT /api/v2/issuers/{issuerId}/accounts/{accountReference}/velocity-limits/{velocityLimitReference}/velocity-limit-overrides/{velocityLimitOverrideReference}

PUT /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/velocity-limits/{velocityLimitReference}/velocity-limit-overrides/{velocityLimitOverrideReference}

Enable "on this page" menu on doc section
On

Card Controls-Authorization Restrictions

Authorization Restrictions

Authorization Restrictions

Authorization Restrictions define blocking conditions that may apply to decline transactions on an Account.  
When an Account is created, the default Authorization Restrictions defined at the Product level are applied: 
the product initial setup defines the applicable restrictions and whether they are, by default, checked or not.  
Each applicable Authorization Restriction is identified by a specific "authorizationRestrictionReference".  

Standard Authorization Restrictions can be configured to decline (i.e. block) following use conditions: 
    w  acceptance channels: ATM / cash, POS, Card Not Present (e-Commerce, MOTO), recurring); 
    w  entry modes: contactless online, magnetic stripe; 
    w  business types (Merchant Category Code [MCC]); 
    w  countries or regions (geo-blocking).  
(NB this enumeration is informative, not normative, not exhaustive.)  

The "AuthorizationRestriction" objects contain the following properties: 
    w  "authorizationRestrictionReference", descriptive identification string; 
        (NB it is embedded in the "authorizationRestrictionIdentifier" object) 
        (used as parameter in the path of the operations related to the restriction) 
    w  "name", a (brief but hopefully meaningful) textual description for the restriction; 
    w  "conditionCheck", indicating if the condition is to be checked so the restriction applies; 
        (value as effective at operation execution time, esp. possibly changed via restriction override); 
    w  "conditionCheckOrigin", indicating from which level the "conditionCheck" has been taken; 
        esp. it will indicate whether the restriction has been overridden after the product initial setup; 
        (possible values as defined by enumeration: “Default”, “Exception”, “Override”, “Other”) 
    w  "conditionParameters", providing attributes, if any applicable, relating to the restriction; 
        (restriction criteria if relevant, merchant category code[s], country code[s], region code[s]) 
        (present if the "conditionCheck" is true, and if applicable to the condition to be checked) 
    w  "conditionParametersOrigin", indicating the level of the "conditionParameters" (if any); 
        (possible values as defined by enumeration: “Default”, “Exception”, “Override”, “Other”) 
        (present if the "conditionCheck" is true, and if the "conditionParameters" are present).  

Operations on Authorization Restrictions: 
("tags":["Account - Authorization Restriction"]) 
    w  List the Authorization Restrictions (for an account), 
    w  Retrieve an Authorization Restriction (by reference).  

Authorization Restriction Overrides

Authorization Restrictions can be changed by creating or updating Authorization Restriction Overrides.  
An Authorization Restriction Override is identified by its "authorizationRestrictionOverrideReference".  

The "authorizationRestrictionOverride" objects contain the following properties: 
    w  "authorizationRestrictionOverrideReference", its identification string; 
       (embedded in the "authorizationRestrictionOverrideIdentifier" object) 
       generated by Worldline at the Authorization Restriction Override creation; 
       (used as parameter in the path of the operations related to the override) 
    w  "authorizationRestrictionReference", overridden restriction identification; 
       (embedded in the "defaultAuthorizationRestrictionReference" object) 
       (used as parameter in the path of the operations related to its override[s]) 
    w  "deleted", indicating whether the override has been deleted or is still present; 
       remark: all of the properties hereafter are absent if the override is "deleted"; 
    w  "activationStartTime", the (first) point in time to start applying the override; 
       optional (if not provided, no delay to start: the override applies immediately) 
       must be before "activationEndTime" if any (can be present without an end time)
    w  "activationEndTime", the (last) point in time to stop applying the override; 
       optional (if not provided, no stop scheduled: the override applies endlessly) 
       must be after "activationStartTime" if any (can be present without a start time)
    w  "conditionCheck", indicating if the condition is to be checked so the override applies; 
       overrides the default configured on higher levels for the initial authorization restriction; 
       if set to “null”, the default value configured for the authorization restriction is effective; 
    w  "conditionParameters", providing attributes, if any applicable, relating to the override; 
       override the default configured on higher levels for the initial authorization restriction; 
       if set to “null”, the default values configured for the authorization restriction are effective; 
    w  "priority", used to apply overrides in ascending order of "priority" (from lowest to highest) 
       in case of different overrides - on a same restriction - whose effective timespans overlap; 
       must be different for all co-occurring overrides (not if they are never effective simultaneously) 
       (if not provided, will be set to 0).  

Operations on Authorization Restriction Overrides: 
("tags":["Account - Authorization Restriction"]) 
    w  List the Authorization Restriction Overrides (for an account), 
    w  Create an Authorization Restriction Override (for an account), 
    w  Retrieve an Authorization Restriction Override (by reference), 
    w  Update an Authorization Restriction Override (for an account), 
    w  Delete an Authorization Restriction Override (for an account).  
. 

List the Authorization Restrictions

Operation to get the list of Authorization Restrictions on an Account.  

A (success) response will provide an array of "AuthorizationRestriction" objects.  
The main properties replied (if success), per Authorization Restriction, are: 
NB values currently in effect at the time the operation is performed
    w  "authorizationRestrictionReference", 
    w  "name", 
    w  "conditionCheck", (as effective at operation execution time) 
    w  "conditionCheckOrigin" (as effective at operation execution time).  

API Links

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/authorization-restrictions

GET /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/authorization-restrictions

 Example 
the replied Authorization Restriction relating to the geographical EURO Europe area is not in effect, 
restriction identified by the "authorizationRestrictionReference": RESTRICTION_EURO_EUROPE_OFF, 
with its "conditionCheck": false (the “Default”); no restriction for authorizations from outside this area.  

GET /api/v2/issuers/98003/accounts/468762732120914/authorization-restrictions' \
--header 'WL-Correlation-ID: cf355a3c-c932-4c74-8f66-98318c024018' \
        {   "issuerId": "98003",
            "authorizationRestrictionIdentifier": {
                "authorizationRestrictionReference": "RESTRICTION_EURO_EUROPE_OFF"},
            "conditionCheck": false,
            "conditionCheckOrigin": "Default",
            "name": "Euro European countries off"}
/* and other existing restrictions */

Retrieve an Authorization Restriction

Operation to fetch an existing Authorization Restriction, 
identified by its "authorizationRestrictionReference".   

A (success) response will provide the following information: 
NB values currently in effect at the time the operation is performed
    w  "authorizationRestrictionReference", 
    w  "name", 
    w  "conditionCheck", (as effective at operation execution time) 
    w  "conditionCheckOrigin", 
    w  "conditionParameters", (as effective at operation execution time) 
    w  "conditionParametersOrigin".  

API Links

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/authorization-restrictions/{authorizationRestrictionReference}

List the Authorization Restriction Overrides

Operation to get the list of overrides on an Authorization Restriction, 
identified by its "authorizationRestrictionReference".  
NB It includes the "deleted" overrides (if any).  

A (success) response will provide an array of "authorizationRestrictionOverride" objects.  
The main properties replied (if success), per Authorization Restriction Override, are: 
    w  "authorizationRestrictionOverrideReference", 
    w  "authorizationRestrictionReference", 
    w  "deleted".   

API Links

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/authorization-restrictions/{authorizationRestrictionReference}/authorization-restriction-overrides

GET /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/authorization-restrictions/{authorizationRestrictionReference}/authorization-restriction-overrides

Create an Authorization Restriction Override

Operation to override an Authorization Restriction, 
identified by its "authorizationRestrictionReference".  

The following properties can be provided: 
    w  "activationStartTime", (optional) 
    w  "activationEndTime", (optional) 
    w  "conditionCheck", 
    w  "conditionParameters", (conditional) 
    w  "priority". 

A (success) response will return the generated: 
    w  "authorizationRestrictionOverrideReference".  

API Links

POST /api/v2/issuers/{issuerId}/accounts/{accountReference}/authorization-restrictions/{authorizationRestrictionReference}/authorization-restriction-overrides

POST /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/authorization-restrictions/{authorizationRestrictionReference}/authorization-restriction-overrides

Example 
To override the Authorization Restriction relating to the geographical EURO Europe area, 
as identified by its "authorizationRestrictionReference" set to RESTRICTION_EURO_EUROPE_OFF, 
setting the override "conditionCheck" to “true” to decline all new authorizations from outside this area.  

"curl --location --request POST ""https://issuing-solutions.eae.apis.svc.as8677.net/issbox-test/api/v2/issuers/98003/accounts/468762732120914/authorization-restrictions/RESTRICTION_EURO_EUROPE_OFF/authorization-restriction-overrides"" \\
--header ""WL-Correlation-ID: 4996c9f9-4345-469d-8680-90bfda021b5e"" \\ 
--header ""Content-Type: application/json"" \\ 
--data-raw ""{\"conditionCheck\" : true }"

Retrieve an Authorization Restriction Override

Operation to fetch an existing Authorization Restriction Override, 
identified by its "authorizationRestrictionOverrideReference".  
NB It may also provide the information for a "deleted" override.  

A (success) response will provide the following information: 
    w  "authorizationRestrictionOverrideReference", 
    w  "authorizationRestrictionReference", 
    w  "deleted", 
    w  "activationStartTime", (if any) 
    w  "activationEndTime", (if any) 
    w  "conditionCheck", 
    w  "conditionParameters", (if any) 
    w  "priority".  
NB the last 5 properties are absent if "deleted" is “true”.  

API Links

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/authorization-restrictions/{authorizationRestrictionReference}/authorization-restriction-overrides/{authorizationRestrictionOverrideReference}

GET /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/authorization-restrictions/{authorizationRestrictionReference}/authorization-restriction-overrides/{authorizationRestrictionOverrideReference}

Update an Authorization Restriction Override

Operation to update an existing Authorization Restriction Override, 
identified by its "authorizationRestrictionOverrideReference".  

Any of the following properties can (optionally) be updated: 
    w  "activationStartTime", 
    w  "activationEndTime", 
    w  "conditionCheck", 
    w  "conditionParameters", 
    w  "priority".  

API Links

PUT /api/v2/issuers/{issuerId}/accounts/{accountReference}/authorization-restrictions/{authorizationRestrictionReference}/authorization-restriction-overrides/{authorizationRestrictionOverrideReference}

PUT /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/authorization-restrictions/{authorizationRestrictionReference}/authorization-restriction-overrides/{authorizationRestrictionOverrideReference}

Enable "on this page" menu on doc section
On

Account Operation And Authorization

Account Operation And Authorization

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

GET /api/V2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/operations

GET/api/V2/issuers/{issuerId}/accounts/{accountReference}/operations

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

GET /api/V2/issuers/{issuerId}/accounts/{accountReference}/operations/{operationId}

GET /api/V2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/operations/{operationId}

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

POST /api/V2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/post-fee-operation

POST /api/V2/issuers/{issuerId}/accounts/{accountReference}/post-fee-operation

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

POST /api/V2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/reverse-fee-operation

POST /api/V2/issuers/{issuerId}/accounts/{accountReference}/reverse-fee-operation

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

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/authorizations

GET /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/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

GET /api/v2/issuers/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/authorizations/{authorizationId}

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/authorizations/{authorizationId}

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

GET /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/authorization-business-cases/{businessCaseId}

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/authorization-business-cases/{businessCaseId}

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

GET /apiv2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/authorization-business-cases

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/authorization-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

POST /apiv2/issuers/{issuerId}/accounts/{accountReference}/post-bonus-operation

POST /apiv2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}post-bonus-operation

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 /apiv2/issuers/{issuerId}/accounts/{accountReference}/reverse-bonus-operation

POST /apiv2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}reverse-bonus-operation

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

POST /apiv2/issuers/{issuerId}/accounts/{accountReference}/post-interest-operation

POST /apiv2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}post-interest-operation

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

POST /apiv2/issuers/{issuerId}/accounts/{accountReference}/reverse-interest-operation

POST /apiv2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}reverse-interest-operation

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
    • PAN
    • Operation Identifier
  • 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 not mandatory to provide criteria from 2nd group if operation identifier is the criteria chosen for the 1st group. Otherwise, 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

POST /apiv2/issuers/{issuerId}/search-operations

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

POST /apiv2/issuers/{issuerId}/accounts/{accountReference}/inquire-operation

POST /apiv2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/inquire-operation

Enable "on this page" menu on doc section
On
Subscribe to