OpenAPI Specification
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 Customer API
contact: {}
host: sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/card-issuing
basePath: /api/v2
schemes:
- https
tags:
- name: Customer
description: Customer Api Controller
paths:
/issuers/{issuerId}/customers:
get:
tags:
- Customer
summary: Retrieve list of customer's information
operationId: listCustomers
description: "The \"list customers\" API enables to get a list of customers based on multiple criteria such as First name, Last name, Birth date,.. \n\nFor the search, the API enables exact matches values (partialSearch field set to false) or not (partialSearch set to yes). In the latter case, the search criteria should be a subset of the corresponding value stored in our system ; as an example : if we set \"JOH\" as criteria search for name, then results JOHNNY or \"LISE-JOHN\" for name would match."
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: lastName
in: query
description: Last name
required: false
type: string
- name: firstName
in: query
description: First name
required: false
type: string
- name: phoneticSearch
in: query
description: Indicate if a specific phonetic algorithm must be applied on first name and last name
default: false
type: boolean
- name: phoneticAlgorithm
in: query
description: The list of possible phonetic algorithms are determined for each issuer (configuration). If the indicator is set to true but no phonetic algorithm is provided then all configured phonetic algorithms are applied for the research.
type: array
items:
type: string
- name: birthDate
in: query
description: Birthdate
required: false
type: string
- name: postalAddress.postCode
in: query
description: Post code of the customer's address
required: false
type: string
- name: postalAddress.townName
in: query
description: Town name of the customer's address
required: false
type: string
- name: postalAddress.streetName
in: query
description: Street name of the customer's address
required: false
type: string
- name: postalAddress.buildingNumber
in: query
description: Building number of the customer's address
required: false
type: string
- name: emailAddress.email
in: query
description: Email the customer
required: false
type: string
- name: phone.localPhoneNumber
in: query
description: Local phone number of the customer
required: false
type: string
- name: partialSearch
in: query
description: 'Allow to search on partial values for the following criteria : lastName, firstName, postalAddress.streetName, postalAddress.buildingNumber, postalAddress.postCode, postalAddress.townName, emailAddress.email, phone.localPhoneNumber'
required: false
default: false
type: boolean
- name: courtesyTitle
in: query
description: Courtesy Title of Person Customer
required: false
type: string
- name: secondFirstName
in: query
description: Second First Name of Person Customer
required: false
type: string
- name: partnerExternalReference
in: query
description: External Reference provided by the issuer
required: false
type: string
- name: employee
in: query
description: Indicating if the Person Customer is an employee of the issuer
required: false
type: boolean
- name: page
in: query
description: '0'
required: false
type: integer
default: 0
format: int32
- name: offset
in: query
description: '100'
required: false
type: integer
default: 100
format: int32
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/ApiResponseEntityListCustomer'
security:
- basic: []
deprecated: false
post:
x-wl-idempotent: true
x-wl-lra-operation: true
x-wl-lra-interface: true
tags:
- Customer
summary: Create a Customer (beta)
operationId: createCustomer
description: "The API allows a new customer (as person) to be created if all the mandatory fields are provided.\nThe main input fields are:\n•\tThe issuer ID\n•\tThe first name of the customer\n•\tThe last name of the customer\n•\tThe default address of the customer : The Main postal address has to be provided because used as default address by all business processes if no address usage is defined.\nThe API returns the customer reference (as person) generated by our system.\nThe response can also be enriched (if specified as embedded fields in input) with additional data such as customer (as person) information, address identifiers linked to the customer, addresses of the customer, contacts of the customer.\n\nIdempotency 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."
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: embed
in: query
description: Embedded Fields
required: false
type: array
items:
type: string
enum:
- customer
- customer.addressIdentifiers
- customer.addresses
- customer.contacts
collectionFormat: multi
- in: body
name: body
schema:
$ref: '#/definitions/CreateCustomerRequest'
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/ApiResponseEntityCreateCustomerResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}:
get:
tags:
- Customer
summary: Retrieve customer by external reference
operationId: retrieveCustomerByIssuerExtRef
description: 'The "retrieve customer" API allows the user to get customer information from the input parameters:
- Issuer ID
- Customer reference or the issuer customer reference
In addition to the person information, it is also possible to request the list of addresses of the customer and the address usages by using the embedded fields.'
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: issuerCustomerExternalReference
in: path
description: Issuer Customer External Reference
required: true
type: string
- name: embed
in: query
description: Embedded Fields
required: false
type: array
items:
type: string
enum:
- addressIdentifiers
- addresses
- contactIdentifiers
- contacts
- addresses.addressUsages
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/ApiResponseEntityCustomer'
security:
- basic: []
deprecated: false
put:
tags:
- Customer
summary: Update customer by external reference
operationId: updateCustomerByIssuerExtRef
description: 'The "update customer" API allows the user to update the attributes of a customer.
To identify the customer, it is needed to provide:
- The issuer ID
- The customer reference (internal or external) for which updates are required
The customer reference can be retrieved by using the "list customers" API.
All the attributes must be given in input even if they remain unchanged. For that, It can be needed to use the "retrieve customer" API to get all the current attributes.'
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: issuerCustomerExternalReference
in: path
description: Issuer Customer External Reference
required: true
type: string
- in: body
name: body
required: false
schema:
$ref: '#/definitions/ModifyCustomerRequest'
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/ApiResponseEntityModifyCustomerResponse'
security:
- basic: []
deprecated: false
patch:
tags:
- Customer
summary: Update customer partially by external reference
operationId: updateCustomerPartiallyByIssuerExtRef
description: "The \"update customer partially\" API allows the user to update the attributes of a customer.\n\nTo identify the customer, it is needed to provide:\n•\tThe issuer ID\n•\tThe customer reference (internal or external) for which updates are required\nThe customer reference can be retrieved by using the \"list customers\" API. \nWith this API, only attributes that need to be updated must be given in input.\n\nIn case the property Contact (list) is provided in input then it will replace the existing list."
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: issuerCustomerExternalReference
in: path
description: Issuer Customer External Reference
required: true
type: string
- in: body
name: body
required: false
schema:
$ref: '#/definitions/ModifyCustomerRequest'
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/ApiResponseEntityModifyCustomerResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/customer-history:
get:
tags:
- Customer
summary: Retrieve list of historic updates of a customer by customer external reference (beta)
operationId: listCustomerHistoryByIssuerExtRef
description: "The API allows the customer update history of a customer to be retrieved. \nThe main input fields requested by the API are:\n•\tThe issuer ID\n•\tThe customer for which information is requested : It can be provided by using the customer reference or the issuer customer external reference. \nA start date and an end date can be provided in order to limit the search of the history. \nIn response, the interface provides a list of changes with the effective date of the update."
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: issuerCustomerExternalReference
in: path
description: Issuer Customer External Reference
required: true
type: string
- name: periodStartDateTime
in: query
required: false
type: string
description: 'Format : yyyy-MM-ddTHH:mm:ssZ'
- name: periodEndDateTime
in: query
required: false
type: string
description: 'Format : yyyy-MM-ddTHH:mm:ssZ'
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/ApiResponseEntityCustomerHistory'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addresses:
get:
tags:
- Customer
summary: List addresses for a customer by external reference
operationId: listAddressesForCustomerByIssuerExtRef
description: "This API enables all the addresses associated with a given customer, identified by his customer reference, to be retrieved. This address could be either a permanent address or a temporary address.\nSeveral address types are managed. Each address can be used for a specific usage (card delivery, statement delivery, contract letter,...). \nAddress usage is associated to a service (card service, account service, dispute service, ..) configured in our system.\nThe 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).\nIf 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.\nAddress identifiers, Address attributes and Address usages are displayed in the response."
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:
- addressUsages
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: issuerCustomerExternalReference
in: path
description: Issuer Customer External Reference
required: true
type: string
- name: serviceCode
in: query
description: 'The Service for which the address usage is defined : CARD_SERVICE, ACCOUNT_SERVICE. Conditional (must be used with addressUsageName)'
required: false
type: string
- name: entityReference
in: query
description: 'This corresponds to the application domain of the address. It can be eg a card contract reference, card account reference. It is an optional field.
It enables to have the same usage address for the same customer applied to different addresses (one cardholder with 2 card contracts: card delivery address usage is assigned to main postal address for contract A and card delivery address usage is also assigned to office postal address for contract B.'
required: false
type: string
- name: addressUsageName
in: query
description: The business process for which the address usage is defined such as CARD_DELIVERY, PIN_MAILER_DELIVERY, STATEMENT_DELIVERY.
required: false
type: string
- name: showHistory
in: query
description: 'If the showHistory indicator is set to ''true'' then the full history of the addresses are returned. If this indicator is empty (default behavior) or equals to ''false'', then only the last active addresses are returned. '
required: false
default: false
type: boolean
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/ApiResponseEntityListAddress'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/customers/{customerReference}:
get:
tags:
- Customer
summary: Retrieve customer
operationId: retrieveCustomer
description: 'The "retrieve customer" API allows the user to get customer information from the input parameters:
- Issuer ID
- Customer reference or the issuer customer reference
In addition to the person information, it is also possible to request the list of addresses of the customer and the address usages by using the embedded fields.'
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: customerReference
in: path
description: Customer Reference
required: true
type: string
- name: embed
in: query
description: Embedded Fields
required: false
type: array
items:
type: string
enum:
- addressIdentifiers
- addresses
- contactIdentifiers
- contacts
- addresses.addressUsages
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/ApiResponseEntityCustomer'
security:
- basic: []
deprecated: false
put:
tags:
- Customer
summary: Update customer
operationId: updateCustomer
description: 'The "update customer" API allows the user to update the attributes of a customer.
To identify the customer, it is needed to provide:
- The issuer ID
- The customer reference (internal or external) for which updates are required
The customer reference can be retrieved by using the "list customers" API.
All the attributes must be given in input even if they remain unchanged. For that, It can be needed to use the "retrieve customer" API to get all the current attributes.'
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: customerReference
in: path
description: Customer Reference
required: true
type: string
- in: body
name: body
required: false
schema:
$ref: '#/definitions/ModifyCustomerRequest'
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/ApiResponseEntityModifyCustomerResponse'
security:
- basic: []
deprecated: false
patch:
x-wl-lra-operation: true
tags:
- Customer
summary: Update customer partially
operationId: updateCustomerPartially
description: "The \"update customer partially\" API allows the user to update the attributes of a customer.\n\nTo identify the customer, it is needed to provide:\n•\tThe issuer ID\n•\tThe customer reference (internal or external) for which updates are required\nThe customer reference can be retrieved by using the \"list customers\" API. \nWith this API, only attributes that need to be updated must be given in input.\n\nIn case the property Contact (list) is provided in input then it will replace the existing list."
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: customerReference
in: path
description: Customer Reference
required: true
type: string
- in: body
name: body
required: false
schema:
$ref: '#/definitions/ModifyCustomerRequest'
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/ApiResponseEntityModifyCustomerResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/customers/{customerReference}/customer-history:
get:
tags:
- Customer
summary: Retrieve list
# --- truncated at 32 KB (113 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wordline/refs/heads/main/openapi/wordline-customer-api-openapi.yml