ob-p-a2a-step1

Step 1 Payment Preparation

As part of this step, you will determine payment details such as payment amount, payment product (e.g. SEPA Credit, SEPA Instant credit, domestic or cross-border payments), whether  it is a single or bulk payment etc. Typically, this will be done as part of shopper’s check out or in context of invoice payment and will be handled by your software.  

You will need to let the payer choose their bank out of the list returned by the Reach Directory. We recommend refreshing the list of banks and their attributes once a day. Please note that some of the banks require additional information such as payer’s IBAN to be collected in advance.  You will find this information under the bank details provided by the Reach API. In addition, you can determine the preferred payment authorisation flow out of the ones supported by the bank (redirect / embedded / decoupled). 

As there is a lot of complexity related to the implementation of different payment flows and handling bank specific information, we recommend using our Bank Selection Interface for single payments – this is a set of predefined screens that can be customised to match your branding. As they are already integrated with the Reach API and Payment API, you only need to embed them as part of the user flow in your system. This will simplify the integration effort but its usage is optional.

In case you decided to not use the Bank selection interface, once you gathered all the necessary details, you can move to Step 2 - payment initiation.

Enable "on this page" menu on doc section
On

ob-p-a2a-flow

Payment Flows

There are 3 main types of payment flows:

1. Redirect

In the Redirect Approach the browser session of the payer is redirected from your software to payer's bank. In that case the bank provides all the pages required for Strong Customer Authentication (SCA). Once the authorisation is complete, the payer is being redirected back to your software.

2. Decoupled

In the Decoupled Approach no redirection takes place. Instead the payer's bank notifies the payer, for example using mobile banking app. The authentication is executed by the app. Since this approach is asynchronous, you need to check payment status to know when the authentication process has been finished. 

3. Embedded

In the Embedded Approach you have to provide all the screens required for the authentication process and to communicate all necessary steps over the API of the Open Banking Service to the ASPSP. 

 

Authorization Steps

Depending on the payment flow you will need to implement a different sequence of API call. Please check below sequence diagrams to understand each flow.

You can indicate your preferred SCA method by using PreferredScaMethod (Embedded, Decoupled, Redirect) parameter, but there is no guarantee that the bank will actually use it to authenticate the payer. You can check what payment method is supported by each bank from Reach API.

For faster integration and better user experience we offer the Bank Selection Interface, it will then always become a redirect flow from you to this interface. This interface can be customised with your branding allowing to choose the payer's bank and handling the complexity of different PSD2 authorization flows, so that you will be able to focus on your product and leave the boring stuff to us. 

The selected flow with which authentication will go through, is being identified by the name of a hyperlink, provided in the response.

 

Redirect Flow 

Below is a sequence diagram showing a typical redirection payment flow. Depending on the individual implementation of the bank, the actual flow may differ slightly. The green vertical bars indicates who is responsible for the interaction with the payer (PSU).

Redirect back to the Initiating Party

Once the PSU has interacted with the ASPSP, the session will be redirected back to the Initiating Party. Here, the Open Banking Service appends the Initiating Party Return URL with the Service Name and the payment ID so that the session can be recognised. This enables the Initiating Party to display the correct screen to the PSU.
An example of a return URL is as follows: https://www.example.org/?scope=UElTOjE1NjQzMTYw
The Initiating Party would need to base64 decode this string : UElTOjE1NjQzMTYw
The example above results in: {ServiceName}:{paymentId}, i.e. PIS:15643160

Sequence diagram PIS redirect

Decoupled Flow 

Below is a sequence diagram showing a typical decoupled payment flow. Depending on the individual implementation of the bank, the actual flow may differ slightly. The green vertical bars indicates who is responsible for the interaction with the payer (PSU).

sequence diagrams PIS decoupled

Embedded Flow

Below is a sequence diagram showing a typical embedded payment flow. Depending on the individual implementation of the bank, the actual flow may differ slightly. The green vertical bars indicates who is responsible for the interaction with the payer (PSU).

Sequence diagram PIS embedded

 

Flow steering by links

The table below includes every possible step with the corresponding approach. In the response of each request the named link informs about the next request to be sent according to the actual state in the flow.

SCA approach Hyperlink name Hyperlink URL API Description

Redirect

RedirectUrl

Redirect link

Can be white labeled in case Worldline Bank Selection Interface is used

URL of PSU’s authentication or authorisation on APSPS side, or towards the Initiation Service

Redirect/Embedded/Decoupled

ConfirmationRequired

POST /confirmation

Confirmation of the transaction after authorisation is being done or being exempted.

Redirect/Embedded

PostAuthorisationForExplicit

POST /authorisation

Mostly is being used when multi-sca should be done with Redirect Approach. Nobody required in the request.

Decoupled

PostIdentificationForDecoupled

POST /identification

Requires PSU’s identification at ASPSP for Decoupled Approach.

Embedded

PreAuthenticationForEmbedded

POST /pre-auth

Pre-Authentication is required and will be made with Embedded Approach.

Embedded

PostAuthorisationForEmbedded

POST /authorisation

Start of Authentication with PSU’s credentials at ASPSP.

Embedded

SelectAuthenticationMethod

PUT /authorisation

The update of the authorisation resource where selected SCA method should be provided

Embedded

AuthorizeTransaction

PUT /authorisation

The update of the authorisation resource where challenge response (OTP) should be provided.

Embedded

PutAuthorisationForEmbedded

PUT /authorisation

The update of the authorisation resource with PSU’s credentials, when some other authorisation steps have been done before.
Enable "on this page" menu on doc section
On

Release Notes: REST API V2 - 2.16.2

REST API V2 - 2.16.2

Version 2.16.1 to 2.16.2

What's New

POST /api/v2/issuers/{issuerId}/cards/{cardReference}/create-apple-tokenized-card

Create Apple Tokenized Card

The following web service generates the complete Payment Data Payload for ApplePay

POST /api/v2/issuers/{issuerId}/cards/{cardReference}/create-mdes-tokenized-card

Create Mdes Tokenized Card

This service enables generates the complete google Payment Data Payload for MDES

POST /api/v2/issuers/{issuerId}/cards/{cardReference}/create-vts-tokenized-card

Create Vts Tokenized Card

Generates the complete Payment Data Payload for VTS

GET /api/v2/issuers/{issuerId}/tokens/{tokenReference}/card-reference{?provider}

Get Card Id For Token

This webservice allows local lookup for card identifier (issuerCardId) on a specific Token

POST /api/v2/issuers/{issuerId}/cards/{cardReference}/generate-crypto-otp

Generate Crypto OTP For Card Reference

This service computes OTP, according to either VTS or MDES App to App authentication

POST /api/v2/issuers/{issuerId}/tokens/{tokenReference}/generate-crypto-otp

Generate Crypto OTP For Token

This service computes OTP, according to either VTS or MDES App to App authentication

GET /api/v2/issuers/{issuerId}/cards/{cardReference}/token-list

Get Token By Card Reference

This service returns a token list attached to a given card. The data are the current G-itsp data and could face a desynchronization with scheme referential

 

What's Changed

No API changed.

What's Deleted

No API deleted.

What's Deprecated

No API deprecated.

Enable "on this page" menu on doc section
On

Release Notes: REST API V2 - 2.16.1

REST API V2 - 2.16.1

Version 2.15.1 to 2.16.1

What's New

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

List card contracts (beta)

The API allows the list of card contracts to be retrieved which have the same card contract group reference. The main input fields are:

  • The issuer ID
  • The group reference of the card contract for which the detail is requested:

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

What's Changed

GET /issuers/{issuerId}/corporate-contracts/{contractReference}/corporate-employee-accounts/{accountReference}
Response:
  • Changed property data (object CorporateEmployeeAccount)

    • Added property contractFee (object)
    • Deleted property contractFees (object)
GET /issuers/{issuerId}/corporate-contracts/{contractReference}/corporate-employee-accounts/external-accounts/{issuerAccountExternalReference}
Response:
  • Changed property data (object CorporateEmployeeAccount)

    • Added property contractFee (object)
    • Deleted property contractFees (object)
GET /issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/corporate-employee-accounts/external-accounts/{issuerAccountExternalReference}
Response:
  • Changed property data (object CorporateEmployeeAccount)

    • Added property contractFee (object)
    • Deleted property contractFees (object)
GET /issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/corporate-employee-accounts/{accountReference}
Response:
  • Changed property data (object CorporateEmployeeAccount)

    • Added property contractFee (object)
    • Deleted property contractFees (object)
GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/account-history
Response:
  • Changed property data (array)

    • Changed items (object AccountHistory)

      • Added property sepaMandateUmr (string)
      • Added property sepaCreditorId (string)
GET /issuers/{issuerId}/accounts/{accountReference}/account-history
Response:
  • Changed property data (array)

    • Changed items (object AccountHistory)

      • Added property sepaMandateUmr (string)
      • Added property sepaCreditorId (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)

        • Changed property card (object CreateConsumerContractRequest.Card)

          • Added property brandChangePreviousCardReference (string)
          • Added property brandChangeReplacementReason (string)
POST /issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/add-cards-accounts
Request body :
  • Changed property cardContracts (array)

    • Changed items (object CreateConsumerContractRequest.CardContract)

      • Changed property card (object CreateConsumerContractRequest.Card)

        • Added property brandChangePreviousCardReference (string)
        • Added property brandChangeReplacementReason (string)
POST /issuers/{issuerId}/contracts/{contractReference}/add-cards-accounts
Request body :
  • Changed property cardContracts (array)

    • Changed items (object CreateConsumerContractRequest.CardContract)

      • Changed property card (object CreateConsumerContractRequest.Card)

        • Added property brandChangePreviousCardReference (string)
        • Added property brandChangeReplacementReason (string)

What's Deleted

No API deleted.

What's Deprecated

No API deprecated.

Enable "on this page" menu on doc section
On

Corporate Cards

Corporate Cards

Our solution enables to represent and manage any company with its original hierarchy structure, where the company representation key elements are the following:

  • Corporate contract

    • An agreement between the issuer and the company
    • Corporate contract owner is the company itself, with its proper address management (statement delivery address, etc.)
  • Corporate organization
    • Corporate organization represents the company
    • Can fully correspond to the company original organization
    • Can be represented by a simple 2-level organization or a complex one (where multilevel organization structure applies)
  • Corporate account organization/corporate account
    • Account organization is a mirror of corporate organization, where each corporate entity has its own account
    • For simple 2-level account hierarchy these are the company account and employee card accounts
    • For multilevel complex account hierarchy structure these are the intermediate accounts in between the company account and employee card accounts, where it is possible to have an employee entity attached to any level within the corporate organization
  • Corporate card
    • Can be a physical or a virtual one
    • Corporate card owner is the employee itself or the organization (e.g., lodged cards)
      • In general, the same person can represent an employee within corporate cards structure or an individual within consumer cards’ structure, where different addresses can be managed for the same person within corporate or consumer cards (E.g., for the same cardholder (person) a corporate and consumer card statement delivery addresses can be different, card delivery addresses can be different, etc.)

Our solution offers multiple APIs related to corporate contracts and their features such as

  • Company management (see Company’s management)

    • including company itself and all its possible entities such as countries, divisions, departments, cost centers
    • creation and update of company data such as company name, external company reference
    • possibility to manage company’s contact(s)
  • Employee management (see Customer)
    • Employee, as person, can have both consumer and corporate cards
    • Employee can have 1 or several corporate cards
    • Creation and update of employee data
  • Corporate contract management
    • Creation with company organization, employees and cards

      • Company organization can be built later at any moment
      • Employees and cards can be added later at any moment/li>
      • Possibility to e.g.
        • indicate the membership and account setup fees payer (the company, employees)
        • define default, can be changed for each corporate card, such as
          • a default logo reference (transmitted to the embosser)
          • if the company should receive a duplicate of the statement for cards paid by employees
          • the dispatch code (in order to deliver all cards for the given corporate contract to the same corporate address)/li>
          • if cards open-to-buy should be reset to their maximum credit limit, by default, at cyclic closure date (for credit cards only – e.g. credit limit of 3.000€, cardholder has spent 2.000€ then current open-to-buy of 1.000€ is reset to 3.000€ at cycle closure date even if repayment not already received).
    • Update of corporate contract data such as logo reference, membership and account setup fees payer
    • Company organization management
      • Modification of the company organization (e.g. new country and its organization)
      • Update of a certain company entity (change of delivery channels, advertisement options)
    • Close a corporate contract immediately or in the future
      • As soon as the contract is closed all cards are closed (next authorizations are declined) and related accounts start the standard account closing process
  • Add employee and its card to a certain entity of the company
    • A new or existing employee can be added with its card and related card account to an entity of the company organization
    • e.g. add employee to a cost center 123456, to division AAAA (e.g. employee is the division manager)
    • possible to e.g.
      • indicate whether the card is repaid by the employee or the company
      • indicate the repayment mode (self-payer, direct debit)
      • provide a specific credit limit value/li>
  • Possibility to change how are repaid cards for a certain contract at any moment
    • from repaid by the employee to repaid by the company/li>
    • from repaid by the company to repaid by the employee)
Enable "on this page" menu on doc section
On

Corporate Contract Management

Corporate Contract Management

Create corporate contract

The Create Corporate Contract API allows the creation of a new corporate contract with the company organization (complete or partial structure).

Pre-conditions:

The correlation ID, if provided by the issuer, must be unique. In case of re-use of a correlation ID from an existing corporate contract, the system will return the data from the existing corporate contract (e.g., if the API call returns a "time-out" response, the same correlation ID can be provided to retrieve corporate contract data from Worldline system for further checks).

During the corporate contract creation

1) The issuer can provide a list of new customers/companies, otherwise the references to existing customers/companies in Worldline system can be used

2) The issuer has the possibility to create

  • the company organization, by adding 1 or several corporate entities such as countries, divisions, departments (this is also possible afterwards with dedicated API)
  • the employees with their cards and accounts (this is also possible afterwards with dedicated API)

As a result, the contract is created:

  • with its own reference calculated by our system
  • with the status set to "Signed"
  • with entity levels of the company organization (at least the company itself)
  • with the root entity account

The API response returns

  • the different identifiers related to the corporate contract, such as the contract itself, contract owner, account owner of an entity
  • if requested identifiers of employee accounts, card contracts, cards and cardholders if any (each identifier is composed of the Worldline internal reference and, optionally, the external reference if provided by the issuer in the request)

The references are used to: retrieve/update/close corporate contracts, retrieve the list of entities for a corporate contract, retrieve the corporate employee account, etc.

API links

POST /api/v2/issuers/issuers/{issuerId}/corporate-contracts/create-corporate-contract

Close corporate contract

The API allows to close a corporate contract identified by the Issuer Contract external reference or the Contract reference.

The corporate contract can be closed immediately or in the future at a date provided by the issuer.

As a result,

  • For immediate corporate contract closing: the corporate contract is closed, the cards within the corporate contract are deactivated, the accounts closing process is started for all accounts.
  • For scheduled corporate contract closing (closing in the future): as soon as the closing date is reached then the immediate corporate contract closing process is applied.

API links

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

POST /api/v2/issuers /corporate-contracts/{contractReference}/close

Add an employee and its card(s) and account(s) to a corporate contract

This API allows an issuer to add to an existing corporate contract an employee with a new card and a new card account. Different types of card products (e.g. MCI/VISA debit, credit, prepaid) are supported.

The issuer shall provide the required data

  • employee information (new or existing one)
  • the product extension, with appropriated card and account products among those available for the corporate product used to create the contract
  • required data for card and account
  • the entity of the company organization to which the employee should be attached (e.g. employee to be attached to department A)

The issuer can replace default membership fee and/or account setup fee (contract fees) by specific ones.

The API response returns the extended corporate contract with information related to newly created employee account(s), card contract(s) and card(s) only.

API links

POST /api/v2/issuers/{issuerId}/corporate-contracts/{contractReference}/add-corporate-employee-cards-accounts

POST /api/v2/issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/add-corporate-employee-cards-accounts

Add an entity of the company organization to a corporate contract

This API allows an issuer to add a new entity to the company organization such a new country, division or department to an existing corporate contract.

The issuer shall provide required data to create the new entity such as

  • the product extension to be used among those available for the corporate product used to create the contract
  • entity and account data
  • customer (person) or company information (new ones) or customer references (existing ones in Worldline system)

The API response returns the extended corporate contract with information related to the newly added entity to the company organization and its associated account(s)only.

API links

POST /api/v2/issuers/{issuerId}/corporate-contracts/{contractReference}/add-corporate-contract-entity

POST /api/v2/issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/add-corporate-contract-entity

Update corporate contract

The API allows to update certain data of an existing corporate contract such as

  • pass-through data (specificFields)
  • logo reference sent to the embosser (optional, and can be overridden at card level)
  • dispatch code sent to the embosser (optional)
  • if the company should receive a duplicate for statement or not
  • if the Open-to-buy should be reset to the credit limit amount at cycle closure date (credit account only)
  • if both membership fee and account setup fee are paid by the card account (usually the employee) or the root account (usually the company)
  • the description of each level of the company organization

As a result the corporate contract is immediately updated with provided data in Worldline system.

API links

PATCH /api/v2/issuers/{issuerId}/corporate-contracts/{contractReference}

PATCH /api/v2/issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}

Update corporate contract entity

The API allows certain data of an existing entity of a corporate contract to be updated such as

  • the allowed advertisement channels (flags)
  • the allowed delivery channel for possible letters

As a result the corporate contract entity is immediately updated with provided data in our system.

API links

PATCH /api/v2/issuers/{issuerId}/corporate-contracts/{contractReference}/corporate-contract-entity/{companyEntityExternalReference}

PATCH /api/v2/issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/corporate-contract-entity/{companyEntityExternalReference}

Update corporate employee account

The API allows to update certain data of an existing corporate employee account such as

  • the external reference of the employee account
  • the allowed advertisement channels (flags)
  • the allowed delivery channel for possible letters
  • if both membership and account setup fees should be waived during contract lifecycle (can be changed at any moment)
  • if both membership fee and account setup fee are paid by the card account (usually the employee) or the root account (usually the company)

As a result the corporate employee account is immediately updated with provided data in our system.

API links

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

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

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

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

Retrieve corporate contract

This API allows a particular corporate contract from its reference or its issuer external reference to be retrieved.

The API response contains corporate contract information such as:

  • contract identifier with the contract reference and the issuer external contract reference if previously provided
  • list of levels in the company organization
  • embedded fields if requested such as list of corporate contract entities, list of all customers, list of all companies, list of corporate employee accounts linked to this corporate contract

API links

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

GET /api/v2/issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}

Below an example for :

  • Corporate contract: 0a315367-efb2-4d52-8ec0-f2fd5c8cbfe8
  • Issuer: 1234

GET/api /v2/issuers/1234/corporate-contracts/0a315367-efb2-4d52-8ec0-f2fd5c8cbfe8

Response data

  {"data": { 

        "issuerId": "1234",
        "contractIdentifier": {
            "contractReference": "0a315367-efb2-4d52-8ec0-f2fd5c8cbfe8",
            "issuerContractExternalReference": "A12345"
        },
        "signatureDate": "2023-04-07T09:31:49.000+00:00",
        "specificFields": {
            "test1": "val1",
            "test2": "val3"
        },
        "status": "SIGNED",
        "statusDate": "2023-04-07T09:31:49.000+00:00",
        "rootAccountIdentifier": {
            "accountReference": "95501685952215201085",
            "issuerAccountExternalReference": "aeb9d162-d80a-4e17-bc9d-227ad9fde666"
        },
        "productIdentifier": {
            "issuerProductExternalReference": "PDT_1234_MC_CorporateWorld_FH",
            "productReference": "PDT_1234_MC_CorporateWorld_FH"
        },
        "statementDuplicatedForCompany": false,
        "hierarchyDefaultResetCreditLimit": false,
        "postingAccountForMembershipFee": "CARD_ACCOUNT",
        "postingAccountForAccountSetupFee": "CARD_ACCOUNT",
        "corporateContractLevels": [
            {
                "level": "1",
                "levelDescription": "COMPANY"
            }
        ]
    } 
}

Retrieve corporate employee account

This API allows a particular corporate employee account from its reference or its issuer external reference to be retrieved.

The API response contains corporate employee account information such as:

  • account identifier with the account reference and the issuer external account reference
  • external reference of the employee account
  • parent identifier with the account reference and the issuer external account reference
  • allowed advertisement channels (flags)
  • allowed delivery channel for possible letters
  • if both membership and account setup fees are waived during contract lifecycle
  • if both membership fee and account setup fee are paid by the account or the root
  • type of a corporate product (if the account is related to the company or an employee)
  • embedded fields if requested such as account information, card account(s), card(s) linked to this corporate employee account

API links

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

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

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

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

Change paying account

For a certain corporate contract it is possible to change the paying account type for all accounts from paid by the account itself (usually paid by the employees) to paid by the root account (usually paid by the company) or the inverse.

E.g. all card accounts are paid by employees themselves (each account is paid by itself) within a contract, then it is possible to request to switch to all accounts are paid by the company itself (e.g. root account represents the company and becomes the paying account).

API links

POST /api/v2/issuers/{issuerId}/contracts/{contractReference}/change-paying-account

POST /api/v2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/change-paying-account

Cancel scheduled change of paying account

The API enables to cancel the scheduled change of paying account type, until the scheduled date has not reached yet.

API links

POST /api/v2/issuers/{issuerId}/corporate-contracts/{contractReference}/cancel-change-paying-account

POST /api/v2/issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/cancel-change-paying-account

Enable "on this page" menu on doc section
On

Company Addresses Management

Company Addresses Management

Retrieve company address information

The API returns the current version of a company's address.

Information to be provided in input:

  • The issuer ID
  • The customer reference or the issuer customer reference (as company)
  • The address reference or the issuer address reference

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}/companies/{customerReference}/addresses/{addressReference}

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

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

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

Create address for a company

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

To identify the company, it is needed to provide:

  • The issuer ID
  • The customer reference or the issuer customer reference (as company)

An address includes the following information:

  • the issuer address external reference
  • the label (e.g. HEAD_OFFICE)
  • 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)

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 head office address is mandatory.

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

API links

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

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

Update address of a company

The API updates all the attributes of a company's address.

To identify the address of the company for which updates are required, it is needed to provide:

  • The issuer ID
  • The customer reference or the issuer customer reference (as company)
  • The address reference or the issuer address reference

All the attributes must be provided even those unchanged (except for the usages).

The API allows to validate an address ('invalid' status is set to false). But it's not possible to invalidate an address changing the value of the invalid 'flag' to true. If the user tries to do this action, an error message is returned.

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.

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

API links

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

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

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

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

Activate address of a company

The API allows to activate on demand of an address.

To activate the address of the company, it is needed to provide:

  • The issuer ID
  • The customer reference or the issuer customer reference (as company)
  • The address reference or the issuer address reference

If a temporary address exists, it becomes also active.

The address identifiers, address attributes and address usages are displayed in the response.

API links

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

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

POST /api/v2/issuers/{issuerId}/companies/{customerReference}/addresses/{issuerAddressExternalReference}/activate

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

Deactivate address of a company

The API is used to deactivate the address.

To deactivate the address of the company, it is needed to provide:

  • The issuer ID
  • The customer reference or the issuer customer reference (as company)
  • The address reference or the issuer address reference

The status becomes "INACTIVE".

This action is forbidden in case of:

  • the address label is the HEAD_OFFICE
  • an usage is linked to the address.

API links

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

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

POST /api/v2/issuers/{issuerId}/companies/{customerReference}/addresses/{issuerAddressExternalReference}/deactivate

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

Create an address usage for a company

The address usage describes in which business case the address will be used (eg statement sending, card delivery, ...). The complete authorized values list is shared during the product configuration between the issuer and WL.

This API allows a usage determined by its name (e.g. STATEMENT_SENDING) to be linked to the entity reference of the address (e.g. card contract reference) and the service code (e.g. ACCOUNT_SERVICE).

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

  • The issuer ID
  • The customer reference or the issuer customer reference (as company)
  • The address reference or the issuer address reference

API links

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

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

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

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

Remove an address usage of a company

The API deletes the address usages linked to one address.

To identify the address of the company, it is needed to provide:

  • The issuer ID
  • The customer reference or the issuer customer reference (as company)
  • The address reference or the issuer address reference

The 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}/companies/{customerReference}/addresses/{addressReference}/address-usages

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

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

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

Enable "on this page" menu on doc section
On

Company's Management

Company's Management

Create a company

The API creates a company if all the mandatory fields are provided (see company's resource).

By default, the company is considered 'ACTIVE' if the Status field is not provided.

The default address of the company must be also configured.

The API returns a customer reference (as company).

API links

POST /api/v2/issuers/{issuerId}/companies

Retrieve company’s information

The "retrieve company's information" API allows the user to get company information.

Information to be provided in input:

  • The issuer ID
  • The customer reference or the issuer customer reference (as company)

In addition to the company information, it is also possible to request the list of addresses and contacts of the company.

API links

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

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

Update company’s information

The "update company" API allows the user to update the attributes of a customer (as company).

To identify the company, it is needed to provide:

  • The issuer ID
  • The customer reference or the issuer customer reference (as company) for which updates are required

The customer reference can be retrieved by using the "Retrieve list of company's information" API.

All the attributes must be given in input even if they remain unchanged. For that, It can be needed to use the "retrieve company's information" API to get all the current attributes.

API links

PUT /api/v2/issuers/{issuerId}/companies/{customerReference}

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

Update company’s information partially

The "update company partially" API allows the user to update the attributes of a customer (as company).

To identify the company, it is needed to provide:

  • The issuer ID
  • The customer reference or the issuer customer reference (as company) for which updates are required

The customer reference can be retrieved by using the "Retrieve list of company's information" API.

With this API, only attributes that need to be updated must be given in input.

API links

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

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

List companies for a given issuer

The "Retrieve list of company's information" API enables to get a list of customers based on multiple criteria such as corporateName, nationalFiscalNumber, address town name, address postal code.

All companies whose corporate name includes the 'corporate name' parameter are returned (e.g. 'zon' => 'amazon' + 'zon craft', ...)

API links

GET /api/v2/issuers/{issuerId}/companies

Retrieve company’s address information list

This API enables all the addresses associated with a given customer (as company), identified by customer reference or issuer customer reference to be retrieved.

To identify the company, it is needed to provide:

  • The issuer ID
  • The customer reference or the issuer customer reference (as company)

The 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}/companies/{customerReference}/addresses

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

List corporate’s contract for a company

This API enables all the contracts belonging to a given company to be retrieved.

Information to be provided in input:

  • The issuer ID
  • The customer reference or the issuer customer reference (as company)

The API response contains a list of contracts with related information.

API links

GET /api/v2/issuers/{issuerId}/companies/{customerReference}/corporate-contracts

GET /api/v2 /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/corporate-contracts

Create a contact

The API creates a contact person belonging to the company 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 (as company)

API links

POST /api/v2/issuers/{issuerId}/companies/{customerReference}/contacts

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

Update a contact

The API allows information of a contact of the company to be modified.

To update a contact, it is needed to provide:

  • The issuer ID
  • The customer reference or the issuer customer reference (as company)
  • 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}/companies/{customerReference}/contacts/{contactReference}

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

Remove a contact

The API allows a contact of the company to be deleted.

To remove a contact, it is needed to provide:

  • The issuer ID
  • The customer reference or the issuer customer reference (as company)
  • The contact reference

API links

DELETE /api/v2/issuers/{issuerId}/companies/{customerReference}/contacts/{contactReference}

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

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