Customer

Customer

A customer is a person who has subscribed to services offered by the issuer

A customer can have multiple roles and can be:

  • the owner of the contract
  • the Cardholder,
  • the owner of the account

Note that only relevant client information necessary for our processing, and customer communication on behalf of the issuer, is managed.

  • Customer data (last name, first name, etc) related to a person or to a company
  • Multiple addresses management
    • including temporarily address management
    • Address usage : card and PIN delivery, statement, client communication (letters, calls/ customer services

Several APIS are provided in order to manage the customer and their addresses as illustrated below:

     API Reference
Enable "on this page" menu on doc section
On

Account Insurance Contract

Account Insurance Contract

Insurance attached to an account can be managed within our system.

Example of insurance can be Payment protection insurance.

Several insurance packages can be configured in order to describe the insurance fee calculation and the usage rules.

The list of authorized insurance events and their codes are also part of an insurance package.

As an example:

 
 
 
 
 
 

Event code 

 
 
 
 
 

Description/Comment 

 
 
 
 
 

RSV 

 
 
 
 

Payment protection insurance is active 

 
 
 
 
 

RAL 

 
 
 
 

Ensured event "UNEMPLOYMENT" 

 
 
 
 
 

RAU 

 
 
 
 

Ensured event "INCAPACITY FOR WORK" 

 
 
 
 
 

RTD 

 
 
 
 

Ensured event "DEATH" 

 
 
 
 
 

RSS 

 
 
 
 

Reversal of insurance 

 
 
 
 
 

RKK 

 
 
 
 

Insurance Cancellation by the customer 

 
 
 
 
 

RKB 

 
 
 
 

Insurance Cancellation by the bank 

 
 
 
 
 

RKA 

 
 
 
 

Insurance Cancellation by the bank, automatically (maximum age reached) 

 

List Insurance Contracts For An Account

The API allows the list of insurance contracts for an account to be retrieved.

The main input fields requested by the API are:

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

In return, the list of insurance contracts is provided with the subscribed insurance package, the insurance events, the latest occurring events and the status for each contract.

The list of insurance events and their codes are pre-defined and configured in the insurance package.

The contracts with a closed status are not provided back.

The possible statuses of insurance contracts are:

  • ACTIVE,
  • INTERRUPTED,
  • DISABLED,
  • CLOSED

The statuses depends on the insurance events configuration.

API links

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

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/insurance-contracts

Retrieve An Insurance Contract For An Account

The API allows an insurance contract for an account to be retrieved.

The main input fields requested by the API are:

  • The issuer ID
  • The account for which info is requested: It can be provided by using the account reference or the issuer external account reference
  • The insurance package reference

In return, the insured events and the latest occurring events for the account and insurance package reference are returned.

The list of insurance events and their codes are a pre-defined and configured in the insurance package.

The contracts with a closed status are not provided back.

The possible status of insurance contracts are:

  • ACTIVE
  • INTERRUPTED
  • DISABLED
  • CLOSED

The statuses depends on the insurance events configuration.

API links

GET /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/insurance-contracts/{insurancePackageReference}

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/insurance-contracts/{insurancePackageReference}

Create An Insurance Contract For An Account

The API allows an insurance contract for an account to be activated if the activation was not requested at the contract creation.

The main input fields requested by the API are:

  • The issuer ID
  • The account for which info is requested: It can be provided by using the account reference or the issuer external account reference
  • The insurance package reference
  • The insurance event code for activation if the activation by default is not defined in the product setup

Controls are performed in our system in order to check that:

  • The insurance package is authorized
  • The event exists for the insurance package
  • The event is associated to an event with “Activate Insurance” action
  • If insurance Minimum eligible age is configured, account owner age should be >= Minimum eligible age
  • If insurance Maximum eligible age is configured, account owner age should be <= Maximum eligible age

API links

POST /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/insurance-contracts

POST /api/v2/issuers/{issuerId}/accounts/{accountReference}/insurance-contracts

Close An Insurance Contract

The API allows an insurance contract for an account to be closed.

The main input fields requested by the API are:

  • The issuer ID
  • The account for which info is requested: It can be provided by using the account reference or the issuer external account reference
  • The insurance package identifier

API links

DELETE /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/insurance-contracts/{insurancePackageReference}

DELETE /api/v2/issuers/{issuerId}/accounts/{accountReference}/insurance-contracts/{insurancePackageReference}

Add An Insurance Event To Insurance Contract

The API is used to post some events to an insurance contract.

The complete list of event is defined in the product setup.

The actions linked to the event can be:

  • activate insurance
  • deactivate insurance
  • stop the fee calculation

The main input fields requested by the API are:

  • The issuer ID
  • The account for which info is requested: It can be provided by using the account reference or the issuer external account reference
  • The insurance package identifier

API links

POST /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/insurance-contracts/{insurancePackageReference}/insurance-events

POST /api/v2/issuers/{issuerId}/accounts/{accountReference}/insurance-contracts/{insurancePackageReference}/insurance-events

Enable "on this page" menu on doc section
On

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.

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.

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

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

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

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.

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.

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.

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.

 

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

 

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.

 

API Links

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

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

 

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.

 

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.

 

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.

 

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.

 

API Links

POST /api/v2/issuers/{issuerId}/disputes/{disputeFolderReference}/documents

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

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.

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

The purpose of a Velocity Limit is to limit transactions in terms of amount and/or frequency, e.g., it might be allowed to withdraw a maximum of 2,500€ per day on POS terminals in Europe.

These rules are implemented with an initial customer-specific product setup which determines whether they are set as blocked or unblocked by default.

Standard Velocity Limits can be changed by creating Velocity Limit Overrides

The standard Velocity Limits for Card Control are:

  • Cash (ATM, branch, POS)
  • eCommerce
  • POS
  • NFC

Each standard Velocity Limits are set with 

  • a minimum amount and a flag, if this amount should be checked
  • a maximum amount and a flag, if this amount should be checked
  • a maximum counter and a flag, if this counter should be checked

A default velocity limit can further be combined with a country or a region, e.g.

  • ATM daily limit in Italy
  • ATM daily limit in the European Economic Area (w/o Italy)
  • ATM daily limit worldwide (w/o the EEA)

When an account is created, the default Velocity Limits defined at the Product level are applied.

In order to list velocity limits for account, the API GET /issuers/{issuerId}/accounts/{accountReference}/velocity-limits should be used by providing the issuerId of the Issuer and accountReference identifying the Account.

Each Velocity Limit is identified by a velocityLimitReference.

A default Velocity Limit could be overridden by Velocity Limit Overrides. The Velocity Limit Override can be set to apply for a specific period, using the attributes activationStartTime and activationEndTime.

A Velocity Limit Override could change the following attributes of the Velocity Limit:

  • maximumAmount : Allowed maximum cumulated authorization amount
  • maximumAmountCheck : Switch indicating whether the cumulated authorization amount of the time period is compared to a maximum or not
  • maximumCount : Allowed maximum number of authorizations in the time period
  • maximumCountCheck : Switch indicating whether the number of authorizations in the time period is compared to a maximum or not

Each Velocity Limit Override is identified by a velocityLimitOverrideReference

It is possible to use this reference in order to 

  • Retrieve velocity limit overrides
  • Update velocity limit overrides
  • Delete velocity limit overrides

All the Velocity Limit Overrides which are applied on a Velocity Limit can be retrieved by the API that lists velocity limit overrides for a velocity limit.

List velocity limits for an account

The different velocity limits are configured during the product and authorization process workflow set-up.

The API enables the list of velocity limits associated with a given card account to be retrieved.

The current velocity limits are returned and for each velocity limit the following information can be found:

  • Velocity limit reference (e.g VELOCITY_LIMIT_ECOM for e-commerce velocity limits)
  • The max amount control flag and the corresponding amount authorized
  • The minimum amount control flag and the corresponding amount authorized
  • The max counter authorized

The origin of the velocity limit configuration is also indicated for both maximum amount, minimum amount and maximum counter, which enables the detection of velocity limit overrides after the initial product set-up.

API links

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

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

 

The following example illustrates how the list of velocity limits associated to the card account ‘468762732120914’ can be retrieved.

Request data:

 
        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"
    },
    "maximumAmount": {
    "value": 250000,
    "exponent": 2,
    "isoCode": "EUR"
    },
    "maximumAmountOrigin": "Default",
    "maximumAmountCheck": true,
    "maximumAmountCheckOrigin": "Default",
    "maximumCountCheck": false,
    "maximumCountCheckOrigin": "Default",
    "minimumAmountCheck": false,
    "minimumAmountCheckOrigin": "Default",
    "name": "E-commerce"
}

        + other existing velocity limits

In this example, for e-commerce velocity checks, no minimum amount control is performed.

Retrieve velocity limit for a given VL reference

Operation which provides the currently effective velocity limit counters and parameters of an account for a given VL reference.

API links

Retrieve velocity limit by reference.

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

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

Create velocity limit override for an account

The API enables a velocity limit for a given card account to be overridden. The following example illustrates for example how the current velocity limit for e-commerce authorization in a certain currency can be overridden in order to decline all new e-commerce authorizations in this currency.

API links

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

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

The following example illustrates how the list of velocity limits associated to the card account ‘468762732120914’ can be retrieved.

Request data:

 
            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"
                }
            }`
Enable "on this page" menu on doc section
On

Card Controls-Authorization Restrictions

Card Controls: Authorization Restrictions

The purpose of an Authorization Restriction is to allow or refuse a transaction on an account based on given rules.

These rules are implemented with an initial customer-specific product setup, which determines whether they are blocked or unblocked by default.

Standard Authorization Restrictions can be changed by creating Authorization Restriction Overrides.

The standard Authorization Restrictions for Card Control that can be blocked or unblocked are:

  • Channels like
    • ATM / cash
    • Card present (POS)
    • Card not present (eCommerce, telephone)
    • Card not present recurring
    • Contactless online (NFC online)
    • Magstripe
  • Single country, a list of single countries
  • Regions (Geo Blocking)
  • Merchant category codes (MCC Blocking)

When an account is created, the default Authorization Restrictions defined at the Product level are applied.

Each Authorization Restriction is identified by an authorizationRestrictionReference.     

List authorization restrictions for an account

The different authorization restrictions, such as geographical restrictions and card non present restrictions, are configured during the product and authorization process workflow set-up.

The API enables the list of authorization restrictions associated with a given card account to be retrieved.

The current authorization restrictions are provided with the following information:

  • Authorization restriction reference
  • The control flag indicating whether the control is active or not
  • The origin of the authorization restriction, which indicates for example whether the velocity limit has been overridden or not after initial product set-up

API links

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

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

Please find below an example of usage for this API

In this example, there is no restriction for authorizations received from outside euro area .;

Request data:

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\"
                    }       
        + other existing restrictions"

Get authorization restriction by reference

The API enables an authorization restriction for a given card account to be overridden. The following example illustrates for example how a current geographical restriction can be overridden in order to decline all new authorizations from outside the euro area.

API links

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

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

Request data:

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

Create authorization restriction override for an account

The API enables an authorization restriction for a given card account to be overridden.

The following example illustrates for example how a current geographical restriction can be overridden in order to decline all new authorizations from outside the euro area.

API links

create authorization restriction override

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

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

Request data:

"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  

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