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 Card - Letter API
contact: {}
host: sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/card-issuing
basePath: /api/v2
schemes:
- https
tags:
- name: Card - Letter
description: Card Letter API Controller
paths:
/issuers/{issuerId}/cards/{cardReference}/letters/{letterId}:
get:
tags:
- Card - Letter
summary: Retrieve letter for the card (beta)
operationId: retrieveLetterCardRef
description: "The API allows to retreive a specific letter for a card.\nThe main input fields are:\n•\tThe issuer ID\n•\tThe card for which the letter is requested: It can be provided by using the card reference or the issuer external card reference\n•\tThe letter reference by providing the letterId\n\nIn return, the interface provides letter information for the requested card. Deleted letters are not returned by this interface."
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: letterId
in: path
description: Letter Id
required: true
type: string
- name: cardReference
in: path
description: Card 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/ApiResponseEntityRetrieveLetter'
security:
- basic: []
deprecated: false
delete:
tags:
- Card - Letter
summary: Delete a letter for a card (beta)
description: 'The API allows to delete a letter for a card.
The main input fields requested by the API are:
• The issuer ID
• The card for which the letter deletion is requested: It can be provided by using the card reference or the issuer external card reference
• The letter reference by providing the letterId
The following controls will be performed during letter deletion:
- If a cut off hour is configured the deletion is allowed if the generation and deletion occurs during the same 24 hour period between one cut-off time and the next cut off time
- if no cut off hour is configured then the letter can be deleted only on the same day it was generated'
operationId: deleteLetterCardRef
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: letterId
in: path
description: Letter ID
required: true
type: string
- name: cardReference
in: path
description: Card 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/ApiResponseEntityDeleteCardLetterResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/letters/{letterId}:
get:
tags:
- Card - Letter
summary: Retrieve letter for a card by external reference (beta)
operationId: retrieveLetterCardExtRef
description: "The API allows to retreive a specific letter for a card.\nThe main input fields are:\n•\tThe issuer ID\n•\tThe card for which the letter is requested: It can be provided by using the card reference or the issuer external card reference\n•\tThe letter reference by providing the letterId\n\nIn return, the interface provides letter information for the requested card. Deleted letters are not returned by this interface."
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: letterId
in: path
description: Letter Id
required: true
type: string
- name: issuerCardExternalReference
in: path
description: Issuer Card 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/ApiResponseEntityRetrieveLetter'
security:
- basic: []
deprecated: false
delete:
tags:
- Card - Letter
summary: Delete a letter for a card by external reference (beta)
description: 'The API allows to delete a letter for a card.
The main input fields requested by the API are:
• The issuer ID
• The card for which the letter deletion is requested: It can be provided by using the card reference or the issuer external card reference
• The letter reference by providing the letterId
The following controls will be performed during letter deletion:
- If a cut off hour is configured the deletion is allowed if the generation and deletion occurs during the same 24 hour period between one cut-off time and the next cut off time
- if no cut off hour is configured then the letter can be deleted only on the same day it was generated'
operationId: deleteLetterCardExtRef
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: letterId
in: path
description: Letter ID
required: true
type: string
- name: issuerCardExternalReference
in: path
description: Issuer Card 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/ApiResponseEntityDeleteCardLetterResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/cards/{cardReference}/letters/{letterId}/validate:
post:
tags:
- Card - Letter
summary: Validate a letter for a card (beta)
operationId: validateLetterCardRef
description: 'The API allows to validate a letter for a card.
The validation status of the letter must be VALIDATION_NEEDED.
The main input fields requested by the API are:
• The issuer ID
• The card for which the letter validation is requested: It can be provided by using the card reference or the issuer external card reference
• The letter reference by providing the letterId
As a result, the validation status of the letter is changed to VALIDATED.'
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: letterId
in: path
description: Letter Id
required: true
type: string
- name: cardReference
in: path
description: Card 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/ApiResponseEntityValidateCardLetterResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/letters/{letterId}/validate:
post:
tags:
- Card - Letter
summary: Validate a letter for a card by external reference (beta)
operationId: validateLetterCardExtRef
description: 'The API allows to validate a letter for a card.
The validation status of the letter must be VALIDATION_NEEDED.
The main input fields requested by the API are:
• The issuer ID
• The card for which the letter validation is requested: It can be provided by using the card reference or the issuer external card reference
• The letter reference by providing the letterId
As a result, the validation status of the letter is changed to VALIDATED.'
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: letterId
in: path
description: Letter Id
required: true
type: string
- name: issuerCardExternalReference
in: path
description: Issuer Card 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/ApiResponseEntityValidateCardLetterResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/cards/{cardReference}/generate-letter:
post:
x-wl-idempotent: true
tags:
- Card - Letter
summary: Generate letter for a card (beta)
operationId: generateLetterCardRef
description: "The API allows to generate a letter for a card. \nThe main input fields requested by the API are:\n• The issuer ID\n• The card for which the letter generation is requested: It can be provided by using the card reference or the issuer external card reference\n• The letter template reference which is used to generate the letter\n\nDuring letter generation following controls will be performed:\n- If the template parameter is defined with a validator, the validator will be applied on the provided value.\n- If the template parameter is a list (display type = list), the system will check that the provided value belongs to the list.\n- If the template parameter is not modifiable, the system will check that the provided value is equal to dynamically computed value.\n- If the value is defined as invalid, the system will check that the provided value is not equal to dynamically computed value.\n- If the template is configured with a validator (xsd file for instance), the validator will be applied on the generated letter.\n- If the value is not provided in input, the value dynamically computed by the system will be used.\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: issuerId
in: path
description: Issuer Id
required: true
type: string
- name: cardReference
in: path
description: Card Reference
required: true
type: string
- in: body
name: body
required: true
schema:
$ref: '#/definitions/GenerateCardLetterRequest'
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/ApiResponseEntityGenerateCardLetterResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/generate-letter:
post:
x-wl-idempotent: true
tags:
- Card - Letter
summary: Generate letter for a card by external reference (beta)
operationId: generateLetterCardExtRef
description: "The API allows to generate a letter for a card. \nThe main input fields requested by the API are:\n• The issuer ID\n• The card for which the letter generation is requested: It can be provided by using the card reference or the issuer external card reference\n• The letter template reference which is used to generate the letter\n\nDuring letter generation following controls will be performed:\n- If the template parameter is defined with a validator, the validator will be applied on the provided value.\n- If the template parameter is a list (display type = list), the system will check that the provided value belongs to the list.\n- If the template parameter is not modifiable, the system will check that the provided value is equal to dynamically computed value.\n- If the value is defined as invalid, the system will check that the provided value is not equal to dynamically computed value.\n- If the template is configured with a validator (xsd file for instance), the validator will be applied on the generated letter.\n- If the value is not provided in input, the value dynamically computed by the system will be used.\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: issuerId
in: path
description: Issuer Id
required: true
type: string
- name: issuerCardExternalReference
in: path
description: Issuer Card External Reference
required: true
type: string
- in: body
name: body
required: true
schema:
$ref: '#/definitions/GenerateCardLetterRequest'
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/ApiResponseEntityGenerateCardLetterResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/cards/{cardReference}/prefilled-letter-templates/{letterTemplateReference}:
get:
tags:
- Card - Letter
summary: Get parameters for the defined letter templates (beta)
operationId: prefillLetterTemplatesCardRef
description: "The API allows to retrieve the prefilled parameters of a letter template for a card.\nThe main input fields are:\n•\tThe issuer ID\n•\tThe card for which the template parameters are requested: It can be provided by using the card reference or the issuer external card reference\n•\tThe letter template reference\n\nAs a result, the list of the letter template parameter names with the default values assigned to them, are returned, which can be used to prefill the letter template with default values."
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: letterTemplateReference
in: path
description: Letter Template Reference
required: true
type: string
- name: issuerId
in: path
description: Issuer Id
required: true
type: string
- name: cardReference
in: path
description: Card 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/ApiResponseEntityPrefilledLetterTemplatesResponse'
security:
- basic: []
deprecated: false
? /issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/prefilled-letter-templates/{letterTemplateReference}
: get:
tags:
- Card - Letter
summary: Get parameters for the defined letter templates by external reference(beta)
operationId: prefillLetterTemplatesCardExtRef
description: "The API allows to retrieve the prefilled parameters of a letter template for a card.\nThe main input fields are:\n•\tThe issuer ID\n•\tThe card for which the template parameters are requested: It can be provided by using the card reference or the issuer external card reference\n•\tThe letter template reference\n\nAs a result, the list of the letter template parameter names with the default values assigned to them, are returned, which can be used to prefill the letter template with default values."
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: letterTemplateReference
in: path
description: Letter Template Reference
required: true
type: string
- name: issuerId
in: path
description: Issuer Id
required: true
type: string
- name: issuerCardExternalReference
in: path
description: Issuer Card 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/ApiResponseEntityPrefilledLetterTemplatesResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/cards/letter-templates:
get:
tags:
- Card - Letter
summary: List of available letter templates for cards (beta)
operationId: letterTemplateList
description: "The API allows to retrieve the list of available letter templates for an Issuer related to the cards.\nThe main input fields are:\n•\tThe issuer ID\n\nIf requested, the API allows also to\trequest to enrich the response with additional data relative to the template parameters by using embedded fields.\n\nIn return, the interface provides the list of available letter templates for the requested issuer with the related parameters if requested."
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: embed
in: query
description: Embedded Fields
required: false
type: array
items:
type: string
enum:
- parameters
collectionFormat: multi
- name: issuerId
in: path
description: Issuer Id
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/ApiResponseEntityRetrieveLetterTemplates'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/cards/letter-templates/{letterTemplateReference}:
get:
tags:
- Card - Letter
summary: Retrieve a specific letter template (beta)
operationId: retrieveLetterTemplate
description: "The API allows to retreive a specific letter template by its reference.\nThe main input fields are:\n•\tThe issuer ID\n•\tThe letter template reference for which its details is requested\n\nIf requested, the API allows also to\trequest to enrich the response with additional data relative to the template parameters by using embedded fields.\n\nIn return, the interface provides letter template information with the related parameters if requested."
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: embed
in: query
description: Embedded Fields
required: false
type: array
items:
type: string
enum:
- parameters
collectionFormat: multi
- name: letterTemplateReference
in: path
description: Letter Template 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/ApiResponseEntityRetrieveLetterTemplate'
security:
- basic: []
deprecated: false
definitions:
GenerateCardLetterRequest:
type: object
required:
- letterTemplateIdentifier
properties:
letterTemplateIdentifier:
description: Identifier of letter template which will be used to generate the letter
allOf:
- $ref: '#/definitions/LetterTemplateIdentifier'
letterTemplateParameterValues:
type: array
items:
$ref: '#/defin
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wordline/refs/heads/main/openapi/wordline-card-letter-api-openapi.yml