swagger: '2.0'
info:
description: 'The current set of APIs will be available in Q2 2026 on Worldline Global Issuing Platforms.
Additional APIs are under construction and planned to be available in 2026.'
version: 2.41.1
title: Worldline Card Issuing Account - AccountState Contract API
contact: {}
host: sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/card-issuing
basePath: /api/v2
schemes:
- https
tags:
- name: Contract
description: Contract Api Controller
paths:
/issuers/{issuerId}/contracts/brand-advice:
post:
tags:
- Contract
summary: Get a brand selection advice (beta)
operationId: getBrandAdvice
description: "This API allows getting an advice on which brand to select for a card creation (either first card along new contract, additional card or replacement card). This is applicable for products on which brand selection is configured. \nThe API returns the product extension for the advised card brand"
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- in: body
name: body
required: true
schema:
$ref: '#/definitions/BrandAdviceRequest'
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityBrandAdvice'
security:
- basic: []
deprecated: true
/issuers/{issuerId}/contracts/advise-product-extension:
post:
tags:
- Contract
summary: Advice a product extension (beta)
operationId: adviceProductExtension
description: "This API is used to get the product extension for a card creation depending on the configured algorithm. It can be used for the first card or additional card. \nThe main input fields are:\n- The issuer ID\n- The issuer product external reference for which the advice is requested.\nThe API returns the product extension advised for the card creation."
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- in: body
name: body
required: true
schema:
$ref: '#/definitions/AdviceProductExtensionRequest'
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityAdviceProductExtensionResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/contracts/brand-advice-config/{issuerProductExternalReference}:
get:
tags:
- Contract
summary: Retrieve brand advice algorithm configuration by issuer product external reference (beta)
operationId: retrieveBrandAdviceConfigByIssuerProductExtRef
description: 'The API allows the brand advice configuration to be retrieved.
The main input fields are:
- The issuer ID
- The issuer product external reference for which the configuration details are requested.'
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: issuerProductExternalReference
in: path
description: Issuer Product External Reference
required: true
type: string
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityBrandAdviceConfig'
security:
- basic: []
deprecated: true
patch:
tags:
- Contract
summary: Update brand advice algorithm configuration by issuer product external reference (beta)
operationId: modifyBrandAdviceConfigByIssuerProductExtRef
description: 'The API allows a list of pre-defined parameters (attributes) of a brand advice configuration to be updated.
The main input fields are:
- The issuer ID
- The issuer product external reference for which configuration updates are required.
- Parameters to be updated
The brand advice configuration parameters can be retrieved using the Retrieve brand advice detail API.
The updated parameters should be consistent with the initial product configuration defined in the system (e.g., the profiles to be updated must exist in the system to be found).'
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: issuerProductExternalReference
in: path
description: Issuer Product External Reference
required: true
type: string
- in: body
name: body
required: false
schema:
$ref: '#/definitions/ModifyBrandAdviceConfigRequest'
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityModifyBrandAdviceConfigResponse'
security:
- basic: []
deprecated: true
/issuers/{issuerId}/contracts/create-consumer-contract:
post:
x-wl-idempotent: true
x-wl-lra-operation: true
x-wl-lra-interface: true
tags:
- Contract
summary: Create consumer contract
description: "The Create Consumer Contract API allows the creation of a new consumer contract already signed by the customer or not, and its first card(s), either with physical support (plastic) or not (virtual card).\n\nPre-conditions: \n- The request correlation ID, if provided by the issuer, must be unique. \nIn case of re-use of a request correlation ID from an existing contract, the system will return the data from the existing contract (e.g., if the API call returns a \"time-out“ response, the same request correlation ID can be provided to retrieve contract data from WL system for further checks).\n 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.\n- An active consumer product exists with a physical or pure virtual card.\n\nThe issuer can request the creation of a new consumer contract from the provided active consumer product with additional information such as\n- the contract is already signed (status as \"SIGNED\") by the customer or not (status as \"AWAITING_SIGNATURE\")\n- The issuer can provide a list of new customers or the references to existing customers in Worldline system\n\nAs a result, the contract is created\n- with the provided status by the issuer: either the contract is already signed (its account hierarchy is immediately in \"ACTIVE\" status) or not (its account hierarchy is in \"AWAITING_SIGNATURE\" status)\n- with each card and its status set to created or active, depending on the card product configuration \n- with related card order to produce the physical card, if plastic required and the pin mailer order if required. \n\nThe API response returns newly created contract information such as\n- the new contract itself\n- the different identifiers such as the contract reference, contract owner, account owner, add-on, card contract, card and cardholder. Each identifier is composed of the Worldline internal reference and the external reference (is not present if not provided by the issuer and not generated by any algorithm) \n\nThe references are used to: retrieve/update/close contracts, list accounts for a contract, retrieve the contract owner for a contract, retrieve/update legitimacy documents, etc.. "
operationId: createConsumerContract
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- in: body
name: body
required: false
schema:
$ref: '#/definitions/CreateConsumerContractRequest'
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityCreateConsumerContractResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/contracts/{contractReference}/sign:
post:
x-wl-idempotent: true
x-wl-lra-operation: true
tags:
- Contract
summary: Sign Contract
description: "The API allows to \n- sign a contract, identified by the Issuer Contract external reference or the Contract reference (the contract must be in \"awaiting signature\" status)\n- request to activate all cards within this contract simultaneously\n\nAs a result :\n- the contract is signed\n- the accounts within the contract are activated\n- the cards within the contract are activated if requested\n- the contract can be updated"
operationId: signContract
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: contractReference
in: path
description: Contract Reference
required: true
type: string
- in: body
name: body
required: false
schema:
$ref: '#/definitions/SignContractRequest'
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntitySignContractResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/sign:
post:
x-wl-idempotent: true
x-wl-lra-operation: true
tags:
- Contract
summary: Sign Contract by external reference
description: "The API allows to \n- sign a contract, identified by the Issuer Contract external reference or the Contract reference (the contract must be in \"awaiting signature\" status)\n- request to activate all cards within this contract simultaneously\n\nAs a result :\n- the contract is signed\n- the accounts within the contract are activated\n- the cards within the contract are activated if requested\n- the contract can be updated"
operationId: signExternalContract
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: issuerContractExternalReference
in: path
description: Issuer Contract External Reference
required: true
type: string
- in: body
name: body
required: false
schema:
$ref: '#/definitions/SignContractRequest'
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntitySignContractResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}:
get:
tags:
- Contract
summary: Retrieve contract by external reference
operationId: retrieveContractByIssuerExtRef
description: 'This API allows retrieving a particular 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'
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: relatedResourceIdentifiersOnly
in: query
description: "If relatedResourceIdentifiersOnly is true, the API returns only identifiers related to the embedded resources (for example, if embedded fields cardContracts.cards are requested and relatedResourceIdentifiersOnly is true, only cardContractIdentifier in CardContract and cardIdentifier in Card will be returned). \nIf relatedResourceIdentifiersOnly is false, the API returns all resource information (for example, if embedded fields cardContracts.cards are requested and relatedResourceIdentifiersOnly is false, all information in CardContract and all information in Card will be returned).\nBy default, relatedResourceIdentifiersOnly is false."
required: false
default: false
type: boolean
- name: relatedResourceBaseInfoOnly
in: query
description: 'relatedResourceBaseInfoOnly (cannot be used with relatedResourceIdentifiersOnly):<br/><br/>If relatedResourceBaseInfoOnly is true, the API returns only main information related to the embedded resources (for example, if embedded fields accounts and cardContracts are requested and relatedResourceBaseInfoOnly is true, only main information of Account and Card Contract will be returned).<br/><br/>The main information is as follows :<br/><br/>- For Account: accountIdentifier, root, status, accountOwnerIdentifier and accountGuarantorIdentifier<br/>- For Card Contract: cardContractIdentifier, cardHolderIdentifier and status<br/>- For Card: cardIdentifier, pan, maskedPan, expiryDate, panSequenceNumber, status, externalStatus, panReference and blockingReason<br/>- For Customer: customerIdentifier, courtesyTitle, firstName and lastName<br/><br/>If relatedResourceBaseInfoOnly is false, the API returns all resource information (for example, if embedded fields accounts and cardContracts are requested and relatedResourceBaseInfoOnly is false, all information in Account and all information in CardContract will be returned).<br/><br/>By default, relatedResourceBaseInfoOnly is false.'
required: false
default: false
type: boolean
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: issuerContractExternalReference
in: path
description: Issuer Contract External Reference
required: true
type: string
- name: embed
in: query
description: Embedded Fields
required: false
type: array
items:
type: string
enum:
- advertisementFlags
- deliveryChannel
- legitimacyDocuments
- contractFees
- accountIdentifiers
- accounts
- cardContractIdentifiers
- cardContracts
- dataAnalysisFlags
- contractCustomerIdentifiers
- contractCustomers
- addonSubscriptions
collectionFormat: multi
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityContract'
security:
- basic: []
deprecated: false
patch:
tags:
- Contract
summary: Update contract by external reference
operationId: modifyContractByIssuerExtRef
description: 'The API allows to update certain data of an existing consumer contract, identified by the Issuer Contract external reference or the Contract reference :
- allowed advertisement channels (flags)
- allowed data analysis
- the issuer branch code (e.g. bank agency in charge of this contract)
- allowed delivery channel for possible letters
- if the membership fee should be reimbursed when a card contract is closed
- how many cards should free of membership fee and/or account setup fee
- if the primary card should be considered as the first to be free for membership/account setup fees or if only additional cards should be considered
- if both membership and account setup fees should be waived during contract lifecycle (can be changed at any moment)
- the membership fee anniversary date can be changed
- pass-through data can be updated (specificFields)
As a result the contract is immediately updated with provided data in our system.'
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: issuerContractExternalReference
in: path
description: Issuer Contract External Reference
required: true
type: string
- in: body
name: body
required: false
schema:
$ref: '#/definitions/ModifyContractRequest'
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityModifyContractResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/accounts:
get:
tags:
- Contract
summary: List accounts for contract by external reference
operationId: listAccountsForContractByIssuerExtRef
description: 'The API allows the list of accounts for a contract, identified by the Issuer Contract external reference or the Contract reference, to be retrieved. '
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: embed
in: query
description: Embedded Fields
required: false
type: array
items:
type: string
enum:
- hierarchyOperationStatusHistory
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: issuerContractExternalReference
in: path
description: Issuer Contract External Reference
required: true
type: string
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityListAccount'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/addon-subscriptions:
get:
tags:
- Contract
summary: Retrieve the list of add-on services by external reference
operationId: listAddonsSubscriptionsForContractByIssuerExtRef
description: "The API allows the list of additional service subscriptions (e.g. new letter, travel insurance) for the contract to be retrieved.\n\nThe main input fields requested by the API are:\n• The issuer ID\n• The contract for which the add-on subscriptions are requested: It can be provided by using the contract reference or the issuer external contract reference\n\nThe API response contains add-on subscription information such as:\n•\tThe reference of the additional service subscription\n•\tThe service type reference\n•\tThe card contract or the account on which the subscription has been done\n•\tThe date of subscription to the add-on service\n•\tThe list of add-on service parameters if any"
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: issuerContractExternalReference
in: path
description: Issuer Contract External Reference
required: true
type: string
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
# --- truncated at 32 KB (591 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wordline/refs/heads/main/openapi/wordline-contract-api-openapi.yml