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 request correlation ID, if provided by the issuer, must be unique. In case of re-use of a request 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 request correlation ID can be provided to retrieve corporate contract data from Worldline system for further checks).
Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once. The response will be retrieved directly from our system.
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
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
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.
Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once. The response will be retrieved directly from our system.
API links
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.
Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once. The response will be retrieved directly from our system.
API links
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
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
Update corporate employee account
The API allows to update certain data of an existing corporate employee account or Virtual Card 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
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 (limited to 100), list of all customers (limited to 100), list of all companies (limited to 100), list of corporate employee accounts (limited to 100) linked to this corporate contract
API links
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 or Virtual Card Account to be retrieved from its reference or its issuer external reference.
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 contract(s) linked to this corporate employee account
API links
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
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
Refund fee on demand for corporate contract
The API is used to trigger an on demand pro rata refund of Account Setup (AS) fee or Membership fee (MS) for the unutilized period.
Pre Conditions:
- In case refund for Account Setup fee is requested then card contract closure date should be less than card contract creation date + 1 year
- In case refund for Membership fee is requested, then the Membership fee should already be posted
- Account setup fee refund on demand can be received only once during contract lifecycle
- Membership fee refund on demand can be received only once between Membership fee anniversary dates
The issuer can request the refund by AS or MS fee by providing:
- The fee type: Either Account Setup fee or Membership Fee
- Card Contract Reference
As a Result:
- For Account Setup fee:
- If account is in closed status (BEING_CLOSED), the pro rata refund will be calculated and posted with the following logic: Posted AS fee amount * (Number of days from contract cancellation till (card contract creation + 1 year) / number of days in the year),
- In other cases, it will be calculated in the following logic:,Posted AS fee amount * (Number of days from the date when demand for refund is received till (card contract creation + 1 year) / number of days in the year)
- For Membership Fee:
- If account is in closed status (BEING_CLOSED), the pro rata refund will be calculated and posted with the following logic: MS fee posted on last MS fee anniversary date * (Number of days from contract cancellation till next MS Fee Anniversary date / number of days in the year)
- In other cases, it will be calculated in the following logic: MS fee posted on last MS fee anniversary date * (Number of days from the date when demand for refund is received till next MS Fee Anniversary date / number of days in the year).
Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once. The response will be retrieved directly from our system.
API links
Reallocate employee within the same/different corporate contract(s)
The API can be used to reallocate an employee (i.e., an employee card contract) within the same or different corporate contract(s).
This reallocation
- must be allowed by the configuration (e.g. original employee product shall be in the list of allowed employee products for the new corporate contract)
- is performed immediately
As a result, when employee reallocation is performed
- the employee new account is created under the given parent account (can be within the same or different corporate contract)
- the employee card contract is reallocated
- the employee new account becomes the posting account for reallocated employee/card contract
- data such as IBAN are transferred to the employee new account
- the employee old account is closed according to standard business rules
- account set-up and membership pending fees are transferred from the employee old account to the employee new account and paid, i.e., periodic fees on the employee new account are normally continued.
Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once. The response will be retrieved directly from our system.
API links
Add Corporate VCA Service Cards and Accounts to a corporate contract
This endpoint can be used to create Virtual Card Account (VCA). This is a specific service offered by MCI, VISA and Wordline service (VCE). The VCA is not used to pay transactions, instead a token is requested from MCI, VISA, Worldline service (depends on the Issuer), to fund the transactions.
It is possible to request creation of several VCA Service Cards and Accounts at the same time.
Pre Conditions
- Card Profile related to Virtual Card account should exist
The Issuer can request adding VCA Servive cards and accounts to the corporate contract, by providing:
- 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)
As a result
- Dedicated account to the Virtual Card Account is created
- Card Contract and card is created related to VCA Service
The API response returns the extended corporate contract with information related to newly created VCA Service account(s), card contract(s) and card(s).
Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once. The response will be retrieved directly from our system.
API links
Retrieve Contract Owner For A Corporate Contract
This API allows the contract owner for a corporate contract identified by the Issuer Contract external reference or the Contract reference, to be retrieved.
The API response contains :
- either customer information if the contract owner is a person
- or company information if the contract owner is a company
API links
Subscribe To Add-On For Corporate Contract
The API allows a cardholder to subscribe to an additional service (e.g. new letter, travel insurance) for the corporate contract during all contract life cycle.
The list of allowed additional services are defined on the product (e.g. PORTAL_ACCESS, ALERT, NOTIFICATION).
The main input fields requested by the API are:
- The issuer ID
- The corporate contract for which the add-on subscription is requested: It can be provided by using the contract reference or the issuer external contract reference
- The identifier of the entity for which the add-on subscription is requested: Either the card contract by providing the card contract reference or the issuer external card contract reference, OR the account by providing the account reference or the issuer external account reference
- The corresponding reference of the additional service
- The service type reference defined at product level
Depending on the service type, the issuer can add additional parameters to the add-on service.
As a result:
- The new add-on subscription for the corporate contract is available and can be unsubscribed during all contract life cycle
- A fee can be generated and posted to the cardholder account if required for the product.
API links
Unsubscribe To Add-On For Corporate Contract
The API allows a cardholder to unsubscribe from an additional service (e.g. new letter, travel insurance) for the corporate contract during all contract life cycle.
The main input fields requested by the API are:
- The issuer ID
- The corporate contract for which the add-on unsubscription is requested: It can be provided by using the contract reference or the issuer external contract reference
- The identifier of the entity for which the add-on subscription is requested: Either the card contract by providing the card contract reference or the issuer external card contract reference, OR the account by providing the account reference or the issuer external account reference
- The reference of the additional service
- The service type reference
As a result, the existing add-on subscription for the corporate contract is no longer available.
API links
Retrieve The List Of Add-On Services For Corporate Contract
The API allows the list of additional service subscriptions (e.g. new letter, travel insurance) for the corporate contract to be retrieved.
The main input fields requested by the API are:
- The issuer ID
- The corporate contract for which the add-on subscriptions are requested: It can be provided by using the contract reference or the issuer external contract reference
The API response contains add-on subscription information such as:
- The reference of the additional service subscription
- The service type reference
- The card contract or the account on which the subscription has been done
- The date of subscription to the add-on service
- The list of add-on service parameters if any
API links
Search Corporate Contract (Global)
The API provides possibility to retrieve a list of corporate contracts, based on certain criteria.
Only one of the following criteria for searching must be provided:
- the corporate name and optionally company postal address information (street name, building number, zip code)
- or the reference of the company : it can be provided by using the customer reference or the issuer customer external reference.
If requested, the API input parameters allows also to:
- search from an issuer and optionally with sub-issuers OR search from a list of issuers (by default, the search is performed on all issuers allowed for the user depending on its rights)
- retrieve contract owner information
- request to enrich the response with additional data relative to the root account, the companies, the current addresses of the companies, the corporate contract entities and the corporate employee accounts by using embedded fields
The API response contains all matched corporate contracts and for each returned corporate contract some information is provided such as :
- contract identifier with the contract reference, the issuer external contract reference if originally provided
- embedded fields if requested such as root account, list of all companies (limited to 100) with their addresses linked to this corporate contract, corporate contract entities (limited to 100), corporate employee accounts (limited to 100).
API links