Release Notes: REST API V2 - 2.8.0

Read more about Release Notes: REST API V2 - 2.8.0

REST API V2 - 2.8.0

Version 2.7.1 to 2.8.0
What's New
What's Changed
What's Deleted
What's Deprecated

What's New

Retrieve turnover information for an account

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/turnover-information

The API is used to get the turnover information for an account

Retrieve turnover information for an account

GET /issuers/{issuerId}/accounts/{accountReference}/turnover-information

The API is used to get the turnover information for an account

Retrieve company's information

GET /issuers/{issuerId}/companies/{customerReference}

Update company

PATCH/issuers/{issuerId}/companies/{customerReference}

The "update company" 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.

Update company partially

PATCH/issuers/{issuerId}/companies/{customerReference}

The "Update company 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.

Retrieve company information by external reference

GET /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}

Update Company

PUT /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}

The "Update Company" 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

Update Company partially

PATCH /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}

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.

Retrieve list of company's information

GET /issuers/{issuerId}/companies

Create company

POST /issuers/{issuerId}/companies

Retrieve company's Address information list

GET /issuers/{issuerId}/companies/{customerReference}/addresses

Create address for a company customer

POST /issuers/{issuerId}/companies/{customerReference}/addresses

The API creates an 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.

For information, the main postal address is mandatory.

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

Retrieve company's address information by address ref

GET /issuers/{issuerId}/companies/{customerReference}/addresses/{addressReference}

Update company address

PUT /issuers/{issuerId}/companies/{customerReference}/addresses/{addressReference}

The API updates all the attributes of a customer's address identified with the reference of the customer and the reference of the address. All the attributes must be provided even those unchanged. The identifiers stay unchanged.

Retrieve company's address information by externalAddress

GET /issuers/{issuerId}/companies/{customerReference}/addresses/external-addresses/{issuerAddressExternalReference}

Update company address

PUT /issuers/{issuerId}/companies/{customerReference}/addresses/external-addresses/{issuerAddressExternalReference}

Retrieve company's Address information list by external reference

GET /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/addresses

The API is used to get the turnover information for an account

Create address for a company

POST /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/addresses

The "update customer partially"The API creates an 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.

For information, the main postal address is mandatory.

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

Retrieve address information by company external reference and address reference

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

Update company address

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

Retrieve address information by company external reference and address external reference

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

Update company address

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

Activate address of a company

POST /issuers/{issuerId}/companies/{customerReference}/addresses/{addressReference}/activate

Activate address of a company

POST /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/addresses/{addressReference}/activate

Activate address of a company

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/turnover-information

Activate address of a company

POST /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/addresses/external-addresses/{issuerAddressExternalReference}/activate

Deactivate address of a company

POST /issuers/{issuerId}/companies/{customerReference}/addresses/{addressReference}/deactivate

Deactivate address of a company

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

Deactivate address of a company

POST /issuers/{issuerId}/companies/{customerReference}/addresses/external-addresses/{issuerAddressExternalReference}/deactivate

Deactivate address of a company

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

Create an address usage for a company

POST /issuers/{issuerId}/companies/{customerReference}/addresses/{addressReference}/address-usages

This API allows to link a usage determined by its name (e.g. STATEMENT_SENDING), its entity reference (e.g. card contract reference) and its service code (e.g. ACCOUNT_SERVICE) and the address (identified with its internal reference) of a company (identified with its external reference).

Remove an address usage of a company

DELETE /issuers/{issuerId}/companies/{customerReference}/addresses/{addressReference}/address-usages

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.

Create an address usage for a company

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

The address usage describes for which business case the address will be used (e.g., statement sending, card delivery, ...). The complete authorized values list is shared during the product configuration between the issuer and WL. This API allows a usage determined by its name (e.g. STATEMENT_SENDING) to be linked to the entity reference of the address (e.g. card contract reference) and the service code (e.g. ACCOUNT_SERVICE)

Remove an address usage of a company

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

Create an address usage for a company

POST /issuers/{issuerId}/companies/{customerReference}/addresses/external-addresses/{issuerAddressExternalReference}/address-usages

Remove an address usage of a company

DELETE /issuers/{issuerId}/companies/{customerReference}/addresses/external-addresses/{issuerAddressExternalReference}/address-usages

Create an address usage for a company

POST /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/addresses/external-addresses/{issuerAddressExternalReference}/address-usages

This API allows to link a usage determined by its name (e.g. STATEMENT_SENDING), its entity reference (e.g. card contract reference) and its service code (e.g. ACCOUNT_SERVICE) and the address (identified with its external reference) of a company (identified with its external reference).

Remove an address usage of a company

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

Retrieve corporate employee Accounts

GET /issuers/{issuerId}/corporate-contracts/{contractReference}/corporate-employee-accounts/{accountReference}

This API allows retrieving a particular corporate employee accounts from its reference or its issuer external reference

Update Corporate employee account

PATCH /issuers/{issuerId}/corporate-contracts/{contractReference}/corporate-employee-accounts/{accountReference}

The API allows to update a corporate Employee account

Retrieve corporate employee Accounts With External Account Ref

GET /issuers/{issuerId}/corporate-contracts/{contractReference}/corporate-employee-accounts/external-accounts/{issuerAccountExternalReference}

This API allows retrieving a particular corporate employee accounts from its reference or its issuer external reference

Update Corporate employee account by external account

PATCH /issuers/{issuerId}/corporate-contracts/{contractReference}/corporate-employee-accounts/external-accounts/{issuerAccountExternalReference}

The API allows to update a corporate Employee account

Retrieve corporate employee Accounts With External Contract Ref And External Account Ref

GET /issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/corporate-employee-accounts/external-accounts/{issuerAccountExternalReference}

This API allows retrieving a particular corporate employee accounts from its reference or its issuer external reference

Update Corporate employee account by external contract and account

PATCH /issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/corporate-employee-accounts/external-accounts/{issuerAccountExternalReference}

The API allows to update a corporate Employee account

Retrieve corporate employee Accounts With External Contract Ref

GET /issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/corporate-employee-accounts/{accountReference}

This API allows retrieving a particular corporate employee accounts from its reference or its issuer external reference

Update Corporate employee account By external contract

PATCH /issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/corporate-employee-accounts/{accountReference}

The API allows to update a corporate Employee account

Retrieve corporate contract

GET /issuers/{issuerId}/corporate-contracts/{contractReference}

This API allows retrieving a particular corporate contract from its reference or its issuer external reference. The API response contains contract information such as:

contract identifier with the contract reference and the issuer external contract reference if previously provided
product change information if any, such as its current status (scheduled, done, cancelled), new product, new contract if it exists
embedded fields if requested such as list of all customers or identifiers linked to this contract (e.g. contract owner, root account owner, cardholder(s)), card contracts, cards

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.

Close Corporate contract

POST /issuers/{issuerId}/corporate-contracts/{contractReference}/close

The API allows to close a corporate contract identified by the Contract reference. The contract can be closed immediately or in the future at a date provided by the issuer or at the card expiry date.

As result, For immediate closure : The contract is closed, the cards within the contract are deactivated, the closing is triggered for the accounts.

For scheduled closure : The contract is not changed until the closing date is reached. Once the closing date is reached, the contract is closed, the cards within the contract are deactivated, the closing is triggered for the accounts.

Close Corporate contract

POST /issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/close

The API allows to close a Corporate contract identified by the Issuer Contract external reference or the Contract reference. The contract can be closed immediately or in the future at a date provided by the issuer or at the card expiry date.

As result, For immediate closure : The contract is closed, the cards within the contract are deactivated, the closing is triggered for the accounts.

Declare counterfeit card

POST /issuers/{issuerId}/cards/declare-counterfeit-card

What's Changed

POST /issuers/{issuerId}/cards/pin-state

Response:

Changed property data (object CardStates)
- Added property expiryDate (string)
- Added property status (string)
- Added property blockingReason (string)

POST /issuers/{issuerId}/contracts/{contractReference}/force-product-change

Response:

Changed property data (object ForceProductChangeResponse)
- Added property originalContract (object)
- Added property changedContract (object)
- Added property productChangeInformation (object)
- Deleted property oldContract (object)
- Deleted property newContract (object)

POST /issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/force-product-change

Response:

Changed property data (object ForceProductChangeResponse)
- Added property originalContract (object)
- Added property changedContract (object)
- Added property productChangeInformation (object)
- Deleted property oldContract (object)
- Deleted property newContract (object)

GET /issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}

Response:

Changed property data (object Card)
- Added property logoReference (string)
- Added property dispatchCode (string)
- Added property automaticDeactivationDate (string)
- Deleted property replacementForAutomaticDeactivationDate (string)
- Changed property cardContract (object CardContract)
  - Changed property cards (array)
    - Changed items (object Card)
      - Added property logoReference (string)
      - Added property dispatchCode (string)
      - Added property automaticDeactivationDate (string)
      - Deleted property replacementForAutomaticDeactivationDate (string)

POST /issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/block-and-replace

Request body:

Changed property replaceCardRequest (object ReplaceCardRequest)
- Added property forceNewPIN (boolean)

Response:

Changed property data (object BlockAndReplaceCardResponse)
- Changed property replaceCardResponse (object ReplaceCardResponse)
  - Added property originalContract (object)
  - Added property changedContract (object)
  - Added property productChangeInformation (object)
  - Changed property card (object ReplaceCardResponse.Card)
    - Added property automaticDeactivationDate (string)
    - Deleted property replacementForAutomaticDeactivationDate (string)
  - Changed property newRelatedCardList (array)
    - Changed items (object ReplaceCardResponse)
      - Added property originalContract (object)
      - Added property changedContract (object)
      - Added property productChangeInformation (object)
      - Changed property card (object ReplaceCardResponse.Card)
        Added property automaticDeactivationDate (string)
        
        Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/orders/{orderReference}

Response:

Changed property data (object Order)
- Changed property card (object Card)
  - Added property logoReference (string)
  - Added property dispatchCode (string)
  - Added property automaticDeactivationDate (string)
  - Deleted property replacementForAutomaticDeactivationDate (string)
  - Changed property cardContract (object CardContract)
    - Changed property cards (array)
      - Changed items (object Card)
        Added property logoReference (string)
        
        Added property dispatchCode (string)
        
        Added property automaticDeactivationDate (string)
        
        Deleted property replacementForAutomaticDeactivationDate (string)

POST /issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/replace

Request body:

Added property forceNewPIN (boolean)

Response:

Changed property data (object ReplaceCardResponse)
- Added property originalContract (object)
- Added property changedContract (object)
- Added property productChangeInformation (object)
- Changed property card (object ReplaceCardResponse.Card)
  - Added property automaticDeactivationDate (string)
  - Deleted property replacementForAutomaticDeactivationDate (string)
- Changed property newRelatedCardList (array)
  - Changed items (object ReplaceCardResponse)
    - Added property originalContract (object)
    - Added property changedContract (object)
    - Added property productChangeInformation (object)
    - Changed property card (object ReplaceCardResponse.Card)
      - Added property automaticDeactivationDate (string)
      - Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/cards/{cardReference}

Response:

Changed property data (object Card)
- Added property logoReference (string)
- Added property dispatchCode (string)
- Added property automaticDeactivationDate (string)
- Deleted property replacementForAutomaticDeactivationDate (string)
- Changed property cardContract (object CardContract)
  - Changed property cards (array)
    - Changed items (object Card)
      - Added property logoReference(string)
      - Added property dispatchCode (string)
      - Added property automaticDeactivationDate (string)
      - Deleted property replacementForAutomaticDeactivationDate (string)

POST /issuers/{issuerId}/cards/{cardReference}/block-and-replace

Request body:

Changed property replaceCardRequest (object ReplaceCardRequest)
- Added property forceNewPIN (boolean)

Response:

Changed property data (object BlockAndReplaceCardResponse)
- Changed property replaceCardResponse (object ReplaceCardResponse)
  - Added property originalContract (object)
  - Added property changedContract (object)
  - Added property productChangeInformation (object)
  - Changed property card (object ReplaceCardResponse.Card)
    - Added property automaticDeactivationDate (string)
    - Deleted property replacementForAutomaticDeactivationDate (string)
  - Changed property newRelatedCardList (array)
    - Changed items (object ReplaceCardResponse)
      - Added property originalContract (object)
      - Added property changedContract (object)
      - Added property productChangeInformation (object)
      - Changed property card (object ReplaceCardResponse.Card)
        Added property automaticDeactivationDate (string)
        
        Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/cards/{cardReference}/orders/{orderReference}

Response:

Changed property data (object Order)
- Changed property card (object Card)
  - Added property logoReference (string)
  - Added property dispatchCode (string)
  - Added property automaticDeactivationDate (string)
  - Deleted property replacementForAutomaticDeactivationDate (string)
  - Changed property cardContract (object CardContract)
    - Changed property cards (array)
      - Changed items (object Card)
        Added property logoReference (string)
        
        Added property dispatchCode (string)
        
        Added property automaticDeactivationDate (string)
        
        Deleted property replacementForAutomaticDeactivationDate (string)

POST /issuers/{issuerId}/cards/{cardReference}/replace

Request body:

Added property forceNewPIN (boolean)

Response:

Changed property data (object ReplaceCardResponse)
- Added property originalContract (object)
- Added property changedContract (object)
- Added property productChangeInformation (object)
- Changed property card (object ReplaceCardResponse.Card)
  - Added property automaticDeactivationDate (string)
  - Deleted property replacementForAutomaticDeactivationDate (string)
- Changed property newRelatedCardList (array)
  - Changed items (object ReplaceCardResponse)
    - Added property originalContract (object)
    - Added property changedContract (object)
    - Added property productChangeInformation (object)
    - Changed property card (object ReplaceCardResponse.Card)
      - Added property automaticDeactivationDate (string)
      - Deleted property replacementForAutomaticDeactivationDate (string)

POST /issuers/{issuerId}/contracts/{contractReference}/change-product

Response:

Changed property data (object ChangeProductResponse)
- Added property originalContract (object)
- Added property changedContract (object)
- Added property productChangeInformation (object)
- Deleted property oldContract (object)
- Deleted property newContract (object)

POST /issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/change-product

Response:

Changed property data (object ChangeProductResponse)
- Added property originalContract (object)
- Added property changedContract (object)
- Added property productChangeInformation (object)
- Deleted property oldContract (object)
- Deleted property newContract (object)

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

Response:

Changed property data (object CreditTransfer)
- Added property cancellationDate (string)

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

Response:

Changed property data (object DirectDebit)
- Added property cancellationDate (string)

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}

Response:

Changed property data (object Account)
- Added property companyEntityExternalReference (string)
- Deleted property companyAccountExternalReference (string)

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

Response:

Changed property data (object GetAuthorizationResponse)
- Changed property velocityLimitChecks (array)
  - Changed items (object VelocityLimitCheck)
    - Deleted property name (string)

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

Response:

Changed property data (array)
- Changed items (object CreditTransfer)
  - Added property cancellationDate (string)

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

Response:

Changed property data (array)
- Changed items (object DirectDebit)
  - Added property cancellationDate (string)

GET /issuers/{issuerId}/accounts/{accountReference}

Response:

Changed property data (object Account)
- Added property companyEntityExternalReference (string)
- Deleted property companyAccountExternalReference (string)

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

Response:

Changed property data (object GetAuthorizationResponse)
- Changed property velocityLimitChecks (array)
  - Changed items (object VelocityLimitCheck)
    - Deleted property name (string)

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

Response:

Changed property data (array)
- Changed items (object CreditTransfer)
  - Added property cancellationDate (string)

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

Response:

Changed property data (array)
- Changed items (object DirectDebit)
  - Added property cancellationDate (string)

GET /issuers/{issuerId}/card-contracts/external-card-contracts/{issuerCardContractExternalReference}

Response:

Changed property data (object CardContract)
- Changed property cards (array)
  - Changed items (object Card)
    - Added property logoReference (string)
    - Added property dispatchCode (string)
    - Added property automaticDeactivationDate (string)
    - Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/card-contracts/external-card-contracts/{issuerCardContractExternalReference}/cards

Response:

Changed property data (array)
- Changed items (object Card)
  - Added property logoReference (string)
  - Added property dispatchCode (string)
  - Added property automaticDeactivationDate (string)
  - Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/card-contracts/{cardContractReference}

Response:

Changed property data (object CardContract)
- Changed property cards (array)
  - Changed items (object Card)
    - Added property logoReference (string)
    - Added property dispatchCode (string)
    - Added property automaticDeactivationDate (string)
    - Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/card-contracts/{cardContractReference}/cards

Response:

Changed property data (array)
- Changed items (object Card)
  - Added property logoReference (string)
  - Added property dispatchCode (string)
  - Added property automaticDeactivationDate (string)
  - Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/card-contract

Response:

Changed property data (object CardContract)
- Changed property cards (array)
  - Changed items (object Card)
    - Added property logoReference (string)
    - Added property dispatchCode (string)
    - Added property automaticDeactivationDate (string)
    - Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/orders

Response:

Changed property data (array)
- Changed items (object Order)
  - Changed property card (object Card)
    - Added property logoReference (string)
    - Added property dispatchCode (string)
    - Added property automaticDeactivationDate (string)
    - Deleted property replacementForAutomaticDeactivationDate (string)
    - Changed property cardContract (object CardContract)
      - Changed property cards (array)
        Changed items (object Card)
        Added property logoReference (string)
        
        Added property dispatchCode (string)
        
        Added property automaticDeactivationDate (string)
        
        Deleted property replacementForAutomaticDeactivationDate (string)

POST /issuers/{issuerId}/cards/search

Response:

Changed property data (array)
- Changed items (object Card)
  - Added property logoReference (string)
  - Added property dispatchCode (string)
  - Added property automaticDeactivationDate (string)
  - Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/cards/{cardReference}/card-contract

Response:

Changed property data (object CardContract)
- Changed property cards (array)
  - Changed items (object Card)
    - Added property logoReference (string)
    - Added property dispatchCode (string)
    - Added property automaticDeactivationDate (string)
    - Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/cards/{cardReference}/orders

Response:

Changed property data (array)
- Changed items (object Order)
  - Changed property card (object Card)
    - Added property logoReference (string)
    - Added property dispatchCode (string)
    - Added property automaticDeactivationDate (string)
    - Deleted property replacementForAutomaticDeactivationDate (string)
    - Changed property cardContract (object CardContract)
      - Changed property cards (array)
        Changed items (object Card)
        Added property logoReference (string)
        
        Added property dispatchCode (string)
        
        Added property automaticDeactivationDate (string)
        
        Deleted property replacementForAutomaticDeactivationDate (string)

POST /issuers/{issuerId}/cards/update-all-blocking-information

Response:

Changed property data (array)
- Changed items (object Card)
  - Added property logoReference (string)
  - Added property dispatchCode (string)
  - Added property automaticDeactivationDate (string)
  - Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/authorizations

Response:

Changed property data (array)
- Changed items (object Authorization)
  - Changed property velocityLimitChecks (array)
    - Changed items (object VelocityLimitCheck)
      - Deleted property name (string)

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/contract

Response:

Changed property data (object Contract)
- Added property contractClosedByProductChange (object)
- Added property contractCreatedFromProductChange (object)
- Deleted property productChangeInformation (object)
- Changed property accounts (array)
  - Changed items (object Account)
    - Added property companyEntityExternalReference (string)
    - Deleted property companyAccountExternalReference (string)
- Changed property cardContracts (array)
  - Changed items (object CardContract)
    - Changed property cards (array)
      - Changed items (object Card)
        Added property logoReference (string)
        
        Added property dispatchCode (string)
        
        Added property automaticDeactivationDate (string)
        
        Deleted property replacementForAutomaticDeactivationDate (string)

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

Response:

Changed property data (array)
- Changed items (object Authorization)
  - Changed property velocityLimitChecks (array)
    - Changed items (object VelocityLimitCheck)
      - Deleted property name (string)

GET /issuers/{issuerId}/accounts/{accountReference}/contract

Response:

Changed property data (object Contract)
- Added property contractClosedByProductChange (object)
- Added property contractCreatedFromProductChange (object)
- Deleted property productChangeInformation (object)
- Changed property accounts (array)
  - Changed items (object Account)
    - Added property companyEntityExternalReference (string)
    - Deleted property companyAccountExternalReference (string)
- Changed property cardContracts (array)
  - Changed items (object CardContract)
    - Changed property cards (array)
      - Changed items (object Card)
        Added property logoReference (string)
        
        Added property dispatchCode (string)
        
        Added property automaticDeactivationDate (string)
        
        Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/card-contracts/external-card-contracts/{issuerCardContractExternalReference}/contract

Response:

Changed property data (object Contract)
- Added property contractClosedByProductChange (object)
- Added property contractCreatedFromProductChange (object)
- Deleted property productChangeInformation (object)
- Changed property accounts (array)
  - Changed items (object Account)
    - Added property companyEntityExternalReference (string)
    - Deleted property companyAccountExternalReference (string)
- Changed property cardContracts (array)
  - Changed items (object CardContract)
    - Changed property cards (array)
      - Changed items (object Card)
        Added property logoReference (string)
        
        Added property dispatchCode (string)
        
        Added property automaticDeactivationDate (string)
        
        Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/card-contracts/{cardContractReference}/contract

Response:

Changed property data (object Contract)
- Added property contractClosedByProductChange (object)
- Added property contractCreatedFromProductChange (object)
- Deleted property productChangeInformation (object)
- Changed property accounts (array)
  - Changed items (object Account)
    - Added property companyEntityExternalReference (string)
    - Deleted property companyAccountExternalReference (string)
- Changed property cardContracts (array)
  - Changed items (object CardContract)
    - Changed property cards (array)
      - Changed items (object Card)
        Added property logoReference (string)
        
        Added property dispatchCode (string)
        
        Added property automaticDeactivationDate (string)
        
        Deleted property replacementForAutomaticDeactivationDate (string)

POST /issuers/{issuerId}/contracts/{contractReference}/sign

Response:

Changed property data (object SignContractResponse)
- Changed property contract (object SignContractResponse.Contract)
  - New optional properties:
    - contractOwnerIdentifier
    - creationDate
    - productIdentifier
  - Deleted property creationDate (string)
  - Deleted property signatureDate (string)
  - Deleted property issuerBranchCode (string)
  - Deleted property cardReleaseOrder (string)
  - Deleted property productIdentifier (object)
  - Deleted property contractOwnerIdentifier (object)
  - Changed property accounts (array)
    - Changed items (object SignContractResponse.Account)
      - New optional properties:
        
        accountGuarantorIdentifier
        
        accountOwnerIdentifier
      - Deleted property accountOwnerIdentifier (object)
      - Deleted property accountGuarantorIdentifier (object)
  - Changed property cardContracts (array)
    - Changed items (object SignContractResponse.CardContract)
      - New required properties:
        
        cardContractIdentifier
        
        cards
        
        status
      - New optional properties:
        
        principalSupplementaryCardIndicator
        
        relatedAccounts
      - Added property cards (array)
      - Deleted property cardHolderIdentifier (object)
      - Deleted property principalSupplementaryCardIndicator (string)
      - Deleted property card (object)
      - Deleted property relatedAccounts (array)
      - Deleted property externalCobadgedCardNumber (string)
      - Deleted property externalCobadgedSequenceNumber (string)
      - Deleted property externalCobadgedExpiryDate (string)

POST /issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/sign

Response:

Changed property data (object SignContractResponse)
- Changed property contract (object SignContractResponse.Contract)
  - New optional properties:
    - contractOwnerIdentifier
    - creationDate
    - productIdentifier
  - Deleted property creationDate (string)
  - Deleted property signatureDate (string)
  - Deleted property issuerBranchCode (string)
  - Deleted property cardReleaseOrder (string)
  - Deleted property productIdentifier (object)
  - Deleted property contractOwnerIdentifier (object)
  - Changed property accounts (array)
    - Changed items (object SignContractResponse.Account)
      - New optional properties:
        
        accountGuarantorIdentifier
        
        accountOwnerIdentifier
      - Deleted property accountOwnerIdentifier (object)
      - Deleted property accountGuarantorIdentifier (object)
  - Changed property cardContracts (array)
    - Changed items (object SignContractResponse.CardContract)
      - New required properties:
        
        cardContractIdentifier
        
        cards
        
        status
      - New optional properties:
        
        principalSupplementaryCardIndicator
        
        relatedAccounts
      - Added property cards (array)
      - Deleted property cardHolderIdentifier (object)
      - Deleted property principalSupplementaryCardIndicator (string)
      - Deleted property card (object)
      - Deleted property relatedAccounts (array)
      - Deleted property externalCobadgedCardNumber (string)
      - Deleted property externalCobadgedSequenceNumber (string)
      - Deleted property externalCobadgedExpiryDate (string)

GET /issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}

Response:

Changed property data (object Contract)
- Added property contractClosedByProductChange (object)
- Added property contractCreatedFromProductChange (object)
- Deleted property productChangeInformation (object)
- Changed property accounts (array)
  - Changed items (object Account)
    - Added property companyEntityExternalReference (string)
    - Deleted property companyAccountExternalReference (string)
- Changed property cardContracts (array)
  - Changed items (object CardContract)
    - Changed property cards (array)
      - Changed items (object Card)
        Added property logoReference (string)
        
        Added property dispatchCode (string)
        
        Added property automaticDeactivationDate (string)
        
        Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/accounts

Response:

Changed property data (array)
- Changed items (object Account)
  - Added property companyEntityExternalReference (string)
  - Deleted property companyAccountExternalReference (string)

GET /issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/card-contracts

Response:

Changed property data (array)
- Changed items (object CardContract)
  - Changed property cards (array)
    - Changed items (object Card)
      - Added property logoReference (string)
      - Added property dispatchCode (string)
      - Added property automaticDeactivationDate (string)
      - Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/contracts/{contractReference}

Response:

Changed property data (object Contract)
- Added property contractClosedByProductChange (object)
- Added property contractCreatedFromProductChange (object)
- Deleted property productChangeInformation (object)
- Changed property accounts (array)
  - Changed items (object Account)
    - Added property companyEntityExternalReference (string)
    - Deleted property companyAccountExternalReference (string)
- Changed property cardContracts (array)
  - Changed items (object CardContract)
    - Changed property cards (array)
      - Changed items (object Card)
        Added property logoReference (string)
        
        Added property dispatchCode (string)
        
        Added property automaticDeactivationDate (string)
        
        Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/contracts/{contractReference}/accounts

Response:

Changed property data (array)
- Changed items (object Account)
  - Added property companyEntityExternalReference (string)
  - Deleted property companyAccountExternalReference (string)

GET /issuers/{issuerId}/contracts/{contractReference}/card-contracts

Response:

Changed property data (array)
- Changed items (object CardContract)
  - Changed property cards (array)
    - Changed items (object Card)
      - Added property logoReference (string)
      - Added property dispatchCode (string)
      - Added property automaticDeactivationDate (string)
      - Deleted property replacementForAutomaticDeactivationDate (string)

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

Response:

Changed property data (array)
- Changed items (object Account)
  - Added property companyEntityExternalReference (string)
  - Deleted property companyAccountExternalReference (string)

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

Response:

Changed property data (array)
- Changed items (object CardContract)
  - Changed property cards (array)
    - Changed items (object Card)
      - Added property logoReference (string)
      - Added property dispatchCode (string)
      - Added property automaticDeactivationDate (string)
      - Deleted property replacementForAutomaticDeactivationDate (string)

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

Response:

Changed property data (array)
- Changed items (object Account)
  - Added property companyEntityExternalReference (string)
  - Deleted property companyAccountExternalReference (string)

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

Response:

Changed property data (array)
- Changed items (object CardContract)
  - Changed property cards (array)
    - Changed items (object Card)
      - Added property logoReference (string)
      - Added property dispatchCode (string)
      - Added property automaticDeactivationDate (string)
      - Deleted property replacementForAutomaticDeactivationDate (string)

POST /issuers/{issuerId}/contracts/search

Response:

Changed property data (array)
- Changed items (object Contract)
  - Added property contractClosedByProductChange (object)
  - Added property contractCreatedFromProductChange (object)
  - Deleted property productChangeInformation (object)
  - Changed property accounts (array)
    - Changed items (object Account)
      - Added property companyEntityExternalReference (string)
      - Deleted property companyAccountExternalReference (string)
  - Changed property cardContracts (array)
    - Changed items (object CardContract)
      - Changed property cards (array)
        Changed items (object Card)
        Added property logoReference (string)
        
        Added property dispatchCode (string)
        
        Added property automaticDeactivationDate (string)
        
        Deleted property replacementForAutomaticDeactivationDate (string)

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

Response:

Changed property data (array)
- Changed items (object Contract)
  - Added property contractClosedByProductChange (object)
  - Added property contractCreatedFromProductChange (object)
  - Deleted property productChangeInformation (object)
  - Changed property accounts (array)
    - Changed items (object Account)
      - Added property companyEntityExternalReference (string)
      - Deleted property companyAccountExternalReference (string)
  - Changed property cardContracts (array)
    - Changed items (object CardContract)
      - Changed property cards (array)
        Changed items (object Card)
        Added property logoReference (string)
        
        Added property dispatchCode (string)
        
        Added property automaticDeactivationDate (string)
        
        Deleted property replacementForAutomaticDeactivationDate (string)

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

Response:

Changed property data (array)
- Changed items (object Contract)
  - Added property contractClosedByProductChange (object)
  - Added property contractCreatedFromProductChange (object)
  - Deleted property productChangeInformation (object)
  - Changed property accounts (array)
    - Changed items (object Account)
      - Added property companyEntityExternalReference (string)
      - Deleted property companyAccountExternalReference (string)
  - Changed property cardContracts (array)
    - Changed items (object CardContract)
      - Changed property cards (array)
        Changed items (object Card)
        Added property logoReference (string)
        
        Added property dispatchCode (string)
        
        Added property automaticDeactivationDate (string)
        
        Deleted property replacementForAutomaticDeactivationDate (string)

POST /issuers/{issuerId}/contracts/create-consumer-contract

Request body:

Changed property addCardsAccounts (object CreateConsumerContractRequest.AddCardsAccounts)
- Changed property cardContracts (array)
  - Changed items (object CreateConsumerContractRequest.CardContract)
    - Added property techAndAppModelReference (string)
Changed property contract (object CreateConsumerContractRequest.Contract)
- Changed property cardContracts (array)
  - Changed items (object CreateConsumerContractRequest.CardContract)
    - Added property techAndAppModelReference (string)

Response:

Changed property data (object CreateConsumerContractResponse)
- Changed property contract (object CreateConsumerContractResponse.Contract)
  - Changed property cardContracts (array)
    - Changed items (object CreateConsumerContractResponse.CardContract)
      - Added property originalCardContractIdentifier (object)
      - Added property changedCardContractIdentifier (object)

POST /issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/add-cards-accounts

Request body:

Changed property cardContracts (array)
- Changed items (object CreateConsumerContractRequest.CardContract)
  - Added property techAndAppModelReference (string)

Response:

Changed property data (object AddCardsAccountsResponse)
- Changed property contract (object CreateConsumerContractResponse.Contract)
  - Changed property cardContracts (array)
    - Changed items (object CreateConsumerContractResponse.CardContract)
      - Added property originalCardContractIdentifier (object)
      - Added property changedCardContractIdentifier (object)

POST /issuers/{issuerId}/contracts/{contractReference}/add-cards-accounts

Request body:

Changed property cardContracts (array)
- Changed items (object CreateConsumerContractRequest.CardContract)
  - Added property techAndAppModelReference (string)

Response:

Changed property data (object AddCardsAccountsResponse)
- Changed property contract (object CreateConsumerContractResponse.Contract)
  - Changed property cardContracts (array)
    - Changed items (object CreateConsumerContractResponse.CardContract)
      - Added property originalCardContractIdentifier (object)
      - Added property changedCardContractIdentifier (object)

What's Deleted

No API deleted.

What's Deprecated

No API deprecated.

ob-p-a2a-sand

Read more about ob-p-a2a-sand

List of Payment Initiation Service Scenarios

Below you'll find a list of Payment Initiation Service (PIS) scenarios. Each scenario includes a separate page including a step by step description of the steps to complete the scenario. You can choose a scenario by providing the corresponding ASPSP ID in the request, which initiates the payment.

To simplify the interaction, these scenario's work with a static token which doesn't expire. This sandbox token is supplied in the API reference.

You can use the sandbox:

On the API reference page (only for registered users, look for the 'try' button)
With a tool like Postman

Sr. No.	Scenario Name	ASPSP ID	Scenario Guideline
01.	Payment with Redirect Authorisation	20100	Read More
02.	Payment Confirmation with Redirect Authorisation	20110	Read More
03.	PreAuth Payment with Redirect Authorisation	20115	Read More
04.	Periodic Payment with Redirect Authorisation	20220	Read More
05.	Scheduled Payment with Redirect Authorisation	20111	Read More
06.	Bulk Payment with Redirect Authorisation	20210	Read More
07.	Payment with Decoupled Authorisation	20200	Read More
08.	Payment with Embedded Authorisation	20105	Read More
09.	Explicit PreAuth (in Embedded) Payment with Embedded Authorisation	20120	Read More
10.	Payment with Redirect and Embedded - Hybrid Authorisation	20121	Read More
11.	Cancel Payment	20114	Read More

API Version 2.8.1

View Documentation

Read more about API Version 2.8.1

API version 2.8.0

View Documentation

Read more about API version 2.8.0

ob-p-ideal

Read more about ob-p-ideal

iDEAL 2.0

These pages describe the components from the Open Banking API version 3 which are used to initiate an iDEAL 2.0 payment. Some sections are based on the iDEAL 2.0 implementation guide from Currence, the iDEAL scheme holder.

Terminology

The terminology used in this document is based on the Payment Service Directive 2.

Term	Equivalent iDEAL term	Description
iDEAL HUB	iDEAL HUB	The iDEAL hub is a solution owned by Currence which provides a unified iDEAL experience. It's connected to the ASPSP's which provide the iDEAL 2.0 product.
Debtor token	iDEAL User Token	The token as provided by Currence to an Initiating Party to identify an iDEAL Profile, which is linked to an iDEAL Profile of the PSU on the iDEAL Hub and which is used to exchange the PSU's preferences (i.e. preferred IBAN) for the iDEAL Transactions with the Initiating Party.
PSU	Consumer	The Payment Service User (PSU) is account holder by one or more ASPSPs and allows other parties to initiate payments requests.
TPP	Acquirer	The Third Party Provider (TPP) is an intermediate between multiple Initiating Parties and ASPSPs and provides an interface used by the Initiating Party. The 'Open Banking Service' refers to the Worldline provided software, which handles the routing of the iDEAL payments.
Initiating Party	Merchant / cPSP	The Initiating Party contracts the TPP for the iDEAL service, and sends an iDEAL payment request to the Open Banking Service on behalf of a PSU.
ASPSP	Issuer	The Account Servicing Payment Service Provider (ASPSP); the Issuer bank which is responsible for the Consumer's account.

Open Banking API features for iDEAL payments

Standard iDEAL payments:

Payment without profile recognition enables PSUs to pay with iDEAL without the need of a registered profile, by means of a manual bank selection or QR code, offered on an iDEAL payment page. See: sequence diagram: example of a flow without profile recognition. On the Transaction Flow page.
Prefill preferred bank and IBAN for iDEAL payments: The PSU's iDEAL profile can be recognized by using the PsuId which the Open Banking Service can match to iDEAL debtor token, this allows the Initiating Party to immediately present the PSU with his preferred IBAN, and redirect the PSU to his preferred ASPSP (with preferred IBAN pre-selected). Upon future visits, the Initiating Party can retrieve and/or make use of the PSU’s payment preferences in the iDEAL transaction. See: sequence diagram: example of a flow with profile recognition. On the Transaction Flow page.

Fast Checkout iDEAL payment:

Prefill address and contact details for iDEAL payments: The iDEAL Fast Checkout function allows the PSU to share his centrally stored address and contact details with Initiating Party upon request. This means that PSUs, for example, do not have to enter their address details each time they shop at a different Initiating Party. See: sequence diagram: Fast Checkout. On the Transaction Flow page.

Ecosystem Overview

The Open Banking Services, marked in green, is provided by Worldline

ob-p-a2a

Read more about ob-p-a2a

Account-to-Account Payments

Payment processing consists of several main steps, visible in the diagram and explained in dedicated chapters:

Payment Preparation
Payment Initiation
Payment Authorisation
Payment Execution

Worldline prepared a set of functions supporting these steps (the white boxes in the diagram). Each of those functions have a page with more explanation. You can choose how to integrate:

Using Worldline Open Banking functions directly. This allows you to control the user experience, but will require more integration effort due to various combinations of payment flows.
Using ready-to-go components (Bank Selection Interface and Push Notification). This will provide you with a streamlined integration due to a set of (white labeled) screens which support Bank selection and guides users through the payment steps and push notifications that you will receive whenever payment status changes.

Both integration options can also be combined.

Once you finished your implementation we recommend to go through the list of suggested testing scenarios

ob-gs-initservice

Read more about ob-gs-initservice

Bank Selection Interface

for Payment

API Reference Live Demonstration

The Bank Selection Interface provides a set of white-labeled screens that support the payer's bank selection and the interactions required for certain authorization flows. It can be used by setting the field 'UseAuthorisationLandingPages=true' in the Payment Initiation Request. The Bank Selection Interface simplifies the integration effort.

Screen examples

The screens below provide an impression of a possible payment flow supported by the Bank Selection Interface, with screens 2, 3, and 6 supplied by the Bank Selection Interface. It is a white-labeled solution, and the style of the pages can be customized.

Screen 1: Checkout page as part of your software

As part of payment preparation and depending on the payment context, you might present the shopping cart or details of the supplier invoice that needs to be paid. There should be a 'Pay' button, which, when clicked, will launch the Bank Selection Interface.

Screen 2: Bank Selection Interface - payer's bank selection

This screen becomes visible after the payer has been redirected to the Bank Selection Interface. If a bank ID was provided in the Post Payments API, the bank would have been pre-filled.

After payer's bank is selected the progress on the left bar changes. In this example, the selected bank does not require additional data to continue with the payment.

Whenever the payer's bank require additional information (e.g., the payer's IBAN) prior to payment initiation, the end user will see an additional screen where they will be prompted to provide the necessary information. This extra step is completely managed by Worldline and does not require any additional integration effort on your part.

Screen 3: Bank Selection Interface - summary page

On the summary page, the payer reviews the data and can choose to save their bank preferences in a browser cookie. The "Pay" button can be pressed to continue the flow.

Screen 4: Banking portal - payer's authentication

The payer needs to authenticate themselves with their bank and approve the payment. Here is an example of what a bank's authentication screen could look like:

Screen 5: Banking portal -payment authorization

Here is an example of what a bank's payment authorization screen could look like.

Screen 6: Bank Selection Interface - receipt page

Once the payment has been authorized by the payer, the bank will redirect them to the Bank Selection Interface. At this stage, the Bank Selection Interface checks the status of the payment and will display this screen if the payment was successful.

Customisation

Almost all elements can be customized to match your branding, including the left bar, the title, and all buttons. Here is an example of a payment summary page with customized branding:

The summary screen can also be configured to include a terms and conditions checkbox that must be checked before the 'Pay' button can be pressed.

Flow Example

The green vertical bars indicate who is responsible for the interaction with the end user (PSU), while the numbers refer to the example screens mentioned above.

Sequence diagram Bank Selection Interface

Implementation

To initiate a payment using the Bank Selection Interface, the following functions should be implemented:

Retrieve Token : An API to retrieve a token, which is used in the subsequent API requests
Single Payment : An API to initiate a single payment. Use 'UseAuthorisationLandingPages=true' in the Header
Payment Status: An API to request the status of a payment. Or Push Notification: An API that allows you to receive notifications when there is a payment status update.

ob-gs-overview

Read more about ob-gs-overview

Welcome to Open Banking

The Open Banking Section of the Developer Portal gives you all information you need to follow the steps from Onboarding to Go Live.
If you want to check out our available APIs, please browse our API Catalogue.

What is Open Banking?

Open Banking facilitates secure connectivity between banks, Third Party Providers (TPPs) and their clients. TPPs can access financial data or initiate payments from their customers’ banks via APIs after the customer grants access. Here is an overview on the Roles of the participating parties:

Open Banking APIs could be used for various purposes, such as Accounting Automation, Cash Management, Credit Scoring Decisions, personal Finance Management etc. You can learn more about Worldline Open Banking Products in section Open Banking Products.

To implement Open Banking Products you will need to check the Payments and Account Data sections.

What are the Steps from Onboarding to Go Live?

Switch to Implementation Steps in order to obtain more information on the typical implementation steps.

Glossary

Some Open Banking specific expressions sound unfamiliar to you? Please access our Glossary.

Need any help?

Do not hesitate to contact us in case you have any queries related to technical implementation or you would like to receive a quotation.

Card Contract

Read more about Card Contract

Card Contract

A card contract represents a single card owned by a cardholder and is linked to a card profile which defines all allowed business rules (e.g., replacement, renewal) and card properties required to create a card (e.g., chip data).

Subsequent cards, created by automatic renewal or card replacement, are listed under the same card contract.

Each card contract is identified by a unique cardContract Reference, generated internally, and optionally by an external reference ”issuerCardContractExternalReference” provided by the issuer, which must be unique per issuer.

The below diagram illustrates the different use cases covered by this domain.

Retrieve card contract detail

The API allows the card contract details to be retrieved.

The main input fields are:

The issuer ID
The card contract for which the detail is requested: It can be provided by using the card contract reference or the issuer card contract external reference.

It is also possible to request some additional data by using the embedded fields.

In return, the interface provides the generic information (mainly master data) relevant to the card

API links

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

GET /api/V2/issuers/{issuerId}/card-contracts/{cardContractReference}

Below is an example where the request retrieves the card contract detail for:

Card contract reference : 12342000000000374459

GET /api/v2/issuers/1234/card-contracts/12342000000000374459

Response data

"data":{
   "issuerId":"1234",
   "cardContractIdentifier":{
      "cardContractReference":"12342000000000374459"
   },
   "cardTemplateReference":"T_1234_CARD_VISA_DEBIT_CLASSIC",
   "cardTypeCode":"F",
   "status":"ACTIVE",
   "openingDate":"2022-12-05T13:13:43.165+00:00",
   "activationDate":"2022-12-05T13:13:43.177+00:00",
   "trustedAuthenticationReference":"123420221205141343905",
   "newCardRenewalAllowed":true,
   "issuerBranchCode":"NO_BRANCH",
   "artwork":"DebitClassic",
   "forcedEmbossingName":"KAISHNER",
   "schemeDeclarationOptOut":false,
   "principalSupplementaryCardIndicator":"SUPPLEMENTARY",
   "productCategory":"DEBIT",
   "productCategoryLabel":"IMMEDIATE_DEBIT_DEBIT",
   "specificFields":{
      "additionalProp1":"string",
      "additionalProp3":"string",
      "additionalProp2":"string"
   },
   "productIdentifier":{
      "issuerProductExternalReference":"PDT_1234_VISA_DEBIT_CLASSIC",
      "productReference":"PDT_1234_VISA_DEBIT_CLASSIC"
   },
   "cardHolderIdentifier":{
      "customerReference":"CUS10000346489",
      "issuerCustomerExternalReference":"HOME_ADDR_REF_PERSON-202212050001B"
   },
   "contractIdentifier":{
      "contractReference":"4459f986-5242-4202-9ed5-f652573e9f63",
      "issuerContractExternalReference":"CONTRACT-202212050001"
   },
   "cardProfileDescription":"P_1234_CARD_VISA_DEBIT_CLASSIC",
   "cardProfileReference":"P_1234_CARD_VISA_DEBIT_CLASSIC"
}
}

Retrieve cardholder for a card contract

The API allows the cardholder data linked to the card contract to be retrieved.

The main input fields are:

The issuer ID
The card contract for which the detail is requested: It can be provided by using the card contract reference or the issuer card contract external reference.

It is also possible to request some additional data by using the embedded fields.

In return, the interface provides the generic information of the customer.

API links

GET /api/V2/issuers/{issuerId}/card-contracts/external-card-contracts/{issuerCardContractExternalReference}/cardholder

GET /api/V2/issuers/{issuerId}/card-contracts/{cardContractReference}/cardholder

Below is an example where the request retrieves the cardholder for:

Card contract reference : 12342000000000374459

GET /api/v2/issuers/1234/card-contracts/12342000000000374459/cardholder

Response data

"data":{
   "issuerId":"1234",
   "customerIdentifier":{
      "customerReference":"CUS10000346489",
      "issuerCustomerExternalReference":"HOME_ADDR_REF_PERSON-202212050001B"
   },
   "active":true,
   "birthDate":"1979-02-20T00:00:00.000+00:00",
   "birthPlace":"Lorch",
   "commercialStatus":"Normal",
   "courtesyTitle":"Frau",
   "firstName":"Kristina",
   "lastName":"KAISHNER",
   "monthlySalary":"0",
   "nationality":"DE",
   "offlineRiskCategory":"Standard",
   "onlineRiskCategory":"Standard",
   "sex":"F"
}

List cards for a card contract

The API allows all the cards of a card contract to be retrieved.

The main input fields are:

The issuer ID
The card contract for which the cards list is requested: It can be provided by using the card contract reference or the issuer card contract external reference.

In return, the interface provides the list of all the cards linked to the card contract. Each card is provided with additional information such as card status, expiry date, embossing line, blocking reason (if in blocked status).

API links

GET /api/V2/issuers/{issuerId}/card-contracts/external-card-contracts/{issuerCardContractExternalReference}/cards

GET /api/V2/issuers/{issuerId}/card-contracts/{cardContractReference}/cards

Below is an example where the request retrieves the cardholder for:

Card contract reference : 12342000000000374459

GET /api/v2/issuers/1234/card-contracts/12342000000000374459/cardholder

Response data

{
   "data":[
      {
         "issuerId":"1234",
         "cardIdentifier":{
            "cardReference":"2000000000374460"
         },
         "pan":"4546174862942386",
         "maskedPan":"454617******2386",
         "expiryDate":"1227",
         "panSequenceNumber":"1",
         "status":"BLOCKED",
         "statusDate":"2022-12-05T16:16:19.514+00:00",
         "embossingName":"KAISHNER",
         "artwork":"DebitClassic",
         "permanentlyBlocked":true,
         "emergencyCard":false,
         "emergencyCashAdvance":false,
         "renewed":false,
         "replaced":true,
         "replacementReason":"LOST_STOLEN",
         "blockingReason":"LOST",
         "cardContractIdentifier":{
            "cardContractReference":"12342000000000374459"
         },
         "isCardDigitalizationAllowed":false,
         "panReference":"15001defb91548a045a2a67f1f5d944a0b7e",
         "cardScheme":"VISA",
         "virtual":false,
         "techAndAppModelName":"M_1234_APPTEC_EMVT0VISA"
      },
      {
         "issuerId":"1234",
         "cardIdentifier":{
            "cardReference":"2000000000374491",
            "issuerCardExternalReference":"CARD-20221119"
         },
         "pan":"4546174672045636",
         "maskedPan":"454617******5636",
         "expiryDate":"1227",
         "panSequenceNumber":"1",
         "status":"ACTIVE",
         "statusDate":"2022-12-05T16:27:57.533+00:00",
         "embossingName":"KAISHNER",
         "artwork":"DebitClassic",
         "permanentlyBlocked":false,
         "emergencyCard":false,
         "emergencyCashAdvance":false,
         "renewed":false,
         "replaced":false,
         "cardContractIdentifier":{
            "cardContractReference":"12342000000000374459"
         },
         "isCardDigitalizationAllowed":false,
         "panReference":"1500d015027a202e47b39d56e25aab9fcc1d",
         "cardScheme":"VISA",
         "virtual":false,
         "techAndAppModelName":"M_1234_APPTEC_EMVT0VISA"
      }
   ]
}

Retrieve contract for a card contract

The API allows the contract detail of a card contract to be retrieved.

The main input fields requested by the API are:

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

It is also possible to request some additional data, such as contract customers, accounts, legitimacy documents, by using the embedded fields.

In return, the interface provides the contract details.

API links

GET /api/V2/issuers/{issuerId}/card-contracts/external-card-contracts/{issuerCardContractExternalReference}/contract

GET /api/V2/issuers/{issuerId}/card-contracts/{cardContractReference}/contract

Below is an example where the request retrieves the cardholder for:

Card contract reference : 12342000000000374459

Response data

{
   "data":{
      "issuerId":"1234",
      "contractIdentifier":{
         "contractReference":"4459f986-5242-4202-9ed5-f652573e9f63",
         "issuerContractExternalReference":"CONTRACT-202212050001"
      },
      "issuerBranchCode":"NO_BRANCH",
      "cardReleaseOrder":"AUTOMATIC",
      "signatureDate":"2022-12-05T12:34:43.000+00:00",
      "status":"SIGNED",
      "statusDate":"2022-12-05T12:34:43.000+00:00",
      "contractOwnerIdentifier":{
         "customerReference":"CUS10000346472",
         "issuerCustomerExternalReference":"PERSON-202212050001"
      },
      "productIdentifier":{
         "issuerProductExternalReference":"PDT_1234_VISA_DEBIT_CLASSIC",
         "productReference":"PDT_1234_VISA_DEBIT_CLASSIC"
      },
      "rootAccountIdentifier":{
         "accountReference":"12346621070985963583",
         "issuerAccountExternalReference":"ROOT_ACCOUNT-202212050001"
      }
   }
}

Update card contract

The API allows a list of pre-defined parameters (attributes) of a card contract to be updated.

The main input fields are:

The issuer ID
The card contract for which updates are required: It can be provided by using the card contract reference or the issuer card contract external reference.
Parameters to be updated

The card contract parameters can be retrieved using the Retrieve card Contract detail API.

The updated parameters should be consistent with the initial product configuration defined in the system (e.g., a change of model is accepted only if the provided model reference is allowed in the product definition).

A typical update for the card contract is the embossing name.

API links

PATCH /api/V2/issuers/{issuerId}/card-contracts/external-card-contracts/{issuerCardContractExternalReference}

PATCH /api/V2/issuers/{issuerId}/card-contracts/{cardContractReference}

Below is an example where the request updates the embossing name and the specific fields for:

Card contract reference : 12342000000000374459

PATCH /api/v2/issuers/1234/card-contracts/12342000000000374459

Request data:

{
   "forcedEmbossingName":"Kristina KAISHNER",
   "specificFields":{
      "additionalProp1":"A14587"
   }
}

Response data:

{
   "responseMetadata":{
      "correlationId":"74c91831-9f60-4f94-90eb-dffae27af2ed",
      "statusMessage":"Executed successfully",
      "statusCode":200,
      "responseDateTime":"2022-12-19T11:20:02.972+0100",
      "timeTakenMs":570
   },
   "data":{
      "cardContractIdentifier":{
         "cardContractReference":"12342000000000374459"
      }
   }
}

Close card contract

The API allows a card contract to be closed.

The main input fields are:

The issuer ID
The card contract for which the closure is requested: It can be provided by using the card contract reference or the issuer card contract external reference.
The parameters of the closure: reason, delay, date.

A card contract can be either closed immediately or in the future (either at the card expiry date or at another scheduled date).

When the card is terminated (when the closing date is reached):

The card is immediately deactivated (next authorizations are declined).
The card cannot be renewed or replaced anymore.
Reimbursement of membership and account setup fees is possible if applicable
The card account cannot be closed:
- before X days (e.g., to take into account the latest transactions)
- if there are ongoing disputes
Once an account is closed, any incoming scheme transaction is automatically disputed.

API links

POST /api/V2/issuers/{issuerId}/card-contracts/external-card-contracts/{issuerCardContractExternalReference}/close

POST /api/V2/issuers/{issuerId}/card-contracts/{cardContractReference}/close

Technical Concepts

Read more about Technical Concepts

Technical Concepts

Worldline Card Issuing Processing provides end-to-end and real time processing by managing debit, credit and prepaid cards. The core services allow you to launch your card product quickly and easily. The Worldline Card Issuing Processing API has been designed as a REST API. Each resource is accessible under a clearly named URL and the HTTP response codes are used to relay status. HTTP Verbs like GET and POST are used to interact with the resources. To ease the integration with clients, main resources are identified either using issuer references either internal references generated on Worldline systems. JSON is used for all payloads, including metadata information.

Authentification

Worldline Card Issuing Processing API uses a secure authentication mechanism keeping the data and the interaction between the issuer and Worldline secure and reliable. In order to authenticate on the API via Oauth2, you first need to get provided with a Consumer Key and Consumer Secret to retrieve by calling our Oauth2 Authentication server and then try out the APIs via the developer portal or your app.

Request

`curl --location --request POST 'https://issuing-solutions.eae.apis.svc.as8677.net/oauth/accesstoken' \ 
--header 'Authorization: Basic {{Consumer Key and Consumer Secret}}' \ 
--header 'Content-Type: application/x-www-form-urlencoded' \
 --data-urlencode 'grant_type=client_credentials'

Response

                { ... "access_token": {{access_token}}", ... }

Response codes

Our API uses basic HTTP response codes to indicate the resulting status of each request.

Codes in the 2xx range indicate success
Codes in the 4xx range indicate an error
Codes in the 5xx range indicate a server error

HTTP code	Meaning	Contexte of use
200	OK	The request was successfully completed. For APIs that deal with list of resources, this code may also be returned in case no results are available after applying input criteria, or if there were no items in the list from the beginning, as long as the path in the URL is valid. For example, let's suppose the issuer "123456" ewists in the system, when trying to get list of customers according to a last name "GET/issuers/132456/customers?lastName=unknown" the API will respond 200 in case there are not results. Indeed, the url path"/issuers/132456/customers" is valid, it's the list of customers for issuer "123456", and the request was executed successfully.
400	Bad request	The request was invalid. It can be related to the query params in URL or invalid/malformed request body. Here are some examples of the issues that may cause an invalid request : Missing required property Property value contains a reference not known in the system Invalid value format Current state of the resource is not compatible with the requested operation (e.g. attempt to activate an already activated card)
401	Unauthorized	The request did not include an authentification token or the authentication token was expired
403	Forbidden	The client did not have permission to access or perform specific action on the resource.
404	Not fund	The requested resource was not found. This error code indicates that the requested resource could not be located on the server, typically due to an issue with the provided URL. This may occur due to invalid identifiers in the dynamic parts of the URL path, or errors in the static parts of the endpoint. For instance, if a client sends a request with the URL "issuers/12356/crds/external-cards/200005/block" instead of "/issuers/12356/cards/external-cards/200005/block", the server may return a 404 error, since the endpoint URL does not exist. If a request is made with an unknown issuer ID or card reference in the example above, or if the card reference is not related the issuer ID, the server will also return a 404 error.
500	Internal Server error	The request was not completed due to an internal error on the server side.
502	Bad Gateway	The server acting as gateway received invalid response from the upstream server.

Our API Responses contain two separate part :

responseMetadata is containing technical information about the execution of the request.
data the functional and business data.

The responseMetadata is formatted as shown hereafter and contains the following information

correlationId : WL-Correlation-Id from the headers
statusMessage : Message about Execution Status
statusCode : HTTP Response Code (same than Response one)
responseDateTime : when response is received
timeTakenMs : elapsed ms time on server time (for 200 OK cases)

Block card – unknown card (http 404)


                {
                    "responseMetadata": {
                        "statusMessage": "UNKNOWN_CARD: Error occurred while blocking the card
                       : [2000000033334867] is null in BlockCardOutput blockCard()",
                        "statusCode": 404,
                        "responseDateTime": "2023-03-15T13:59:17.231+0100",
                        "timeTakenMs": 20
                    }
                }

Block card – bad request - invalid data request (http 400)


                {
                    "responseMetadata": {
                        "statusMessage": "INVALID_BLOCKING_REASON: Error occurred while block the card by input:  
                        [fae96f4c-1697-4b18-98ae-6b84c355776d] during 
                        BlockCardOutput blockCard() call:   [CARD_INVALID_BLOCKING_REASON]",            
                        "statusCode": 400,
                        "responseDateTime": "2023-03-15T14:02:20.446+0100",
                        "timeTakenMs": 26
                    }
                }

Block card – bad request – mandatory field missing (http 400)


                {
                    "responseMetadata": {
                        "statusMessage": "REQUEST_VALIDATION_ERROR: [blockingReason - must not be null]",
                        "statusCode": 400,
                        "responseDateTime": "2023-03-15T14:04:58.955+0100",
                        "timeTakenMs": 16
                    }
                }

Block card – bad request – mandatory field missing (http 400)


                            {
                            "responseMetadata": {
                            "statusMessage": "REQUEST_VALIDATION_ERROR: [blockingReason - must not be null]",
                            "statusCode": 400,
                            "responseDateTime": "2023-03-15T14:04:58.955+0100",
                            "timeTakenMs": 16
                            }
                            }

Block card – forbidden (http 403)


            {
            "responseMetadata": {
            "correlationId": "af5c01bc-18de-4918-98df-74af278b7849",
            "statusMessage": "The current user is not allowed to do the action! Category: 
             ISSUER, Resource: 1234, Action: access",
            "statusCode": 403,
            "responseDateTime": "2023-03-15T14:11:22.111+0100",
            "timeTakenMs": 18
            }
            }

Metadata

Worldline Card Issuing Processing API Responses contains two separate part :

responseMetadata is containing technical information about the execution of the request.
data the functional and business data.

The responseMetadata is formatted as shown hereafter and contains the following information

correlationId : WL-Correlation-Id from the headers
statusMessage : Message about Execution Status
statusCode : HTTP Response Code (same than Response one)
responseDateTime : when response is received
timeTakenMs : elapsed ms time on server time (for 200 OK cases)

Response

              
{
    "responseMetadata": {
        "correlationId": "8f7cb0d5-3f5b-4935-bc10-e2c45b46b5df",
        "statusMessage": "Executed successfully",
        "statusCode": 200,
        "responseDateTime": "2021-10-13T15:59:50.302+0200",
        "timeTakenMs": 129
    },
    "data": {
        ...
    }
}

Request correlation identifier

Each API request has an associated correlation identifier. This correlation identifier can be found metadata information and in WL-Correlation-ID Request headers. This correlation identifier can be set in WL-Correlation-ID Request headers and is used to provide support about a specific request. If not provided, it's generated by Worldline system as an UUID.

Pagination

All of the APIs that could return a huge list of resources are supporting pagination using the page and offset parameters in the request formatted on with the following way : ?page={{page}}&offset={{offset}}

Request with default offset

{{baseUrl}}/issuers/{{issuerId}}/accounts/{{accountReference}}/operations?page=5

Response with default offset

{{baseUrl}}/issuers/{{issuerId}}/accounts/{{accountReference}}/operations?page=5&offset=100

Field expansion

Some of the fields can be expanded in order to retrieve additional information when retrieving the detail of one resource within the same request by using the embed request parameter. Multiple fields can be provided and should be separated by a comma (,). By default fields that can be expanded are not provided in the response

Request

{{baseUrl}}/issuers/{{issuerId}}/cards/{{cardReference}}?embed=cardContract

Field filtering

In order to retrieve only the attributes that are relevant in the response of the APIs, the filter parameter can be used in the request. The name of the fields to be retrieved should be provided and you can filter recursively by specifying nested fields after a dot(.). Multiple fields can be provided and should be separated by a comma (,)

Request

{{baseUrl}}/issuers/{{issuerId}}/contracts/create-consumer-contract?filter=contract.contractIdentifier,contract.cardContracts.card.cardIdentifier

Versionning

The major versions of the Wordline Card Issuing Processing APIs are distinguished by the version indicator in the URLs (currently the V2 /api/v2/ ). Minor version updates will not result in a new version indicator in the API URLs. All minor updates are considered to be backwards compatible. Only when changes are not backwards compatible, will we issue a new major version of the API.

Subscribe to