Technical Concepts

Worldline Card Issuing Processing provides end-to-end and real time processing by managing debit, credit and prepaid cards. The core services allow you to launch your card product quickly and easily. The Worldline Card Issuing Processing API has been designed as a REST API. Each resource is accessible under a clearly named URL and the HTTP response codes are used to relay status. HTTP Verbs like GET and POST are used to interact with the resources. To ease the integration with clients, main resources are identified either using issuer references either internal references generated on Worldline systems. JSON is used for all payloads, including metadata information.

Authentification

Worldline Card Issuing Processing API uses a secure authentication mechanism keeping the data and the interaction between the issuer and Worldline secure and reliable. In order to authenticate on the API via Oauth2, you first need to get provided with a Consumer Key and Consumer Secret to retrieve by calling our Oauth2 Authentication server and then try out the APIs via the developer portal or your app.

Request

`curl --location --request POST 'https://issuing-solutions.eae.apis.svc.as8677.net/oauth/accesstoken' \ 
--header 'Authorization: Basic {{Consumer Key and Consumer Secret}}' \ 
--header 'Content-Type: application/x-www-form-urlencoded' \
 --data-urlencode 'grant_type=client_credentials'

Response

                { ... "access_token": {{access_token}}", ... }

Response codes

Our API uses basic HTTP response codes to indicate the resulting status of each request.

Codes in the 2xx range indicate success
Codes in the 4xx range indicate an error
Codes in the 5xx range indicate a server error

HTTP code	Meaning	Contexte of use
200	OK	The request was successfully completed. For APIs that deal with list of resources, this code may also be returned in case no results are available after applying input criteria, or if there were no items in the list from the beginning, as long as the path in the URL is valid. For example, let's suppose the issuer "123456" ewists in the system, when trying to get list of customers according to a last name "GET/issuers/132456/customers?lastName=unknown" the API will respond 200 in case there are not results. Indeed, the url path"/issuers/132456/customers" is valid, it's the list of customers for issuer "123456", and the request was executed successfully.
400	Bad request	The request was invalid. It can be related to the query params in URL or invalid/malformed request body. Here are some examples of the issues that may cause an invalid request : Missing required property Property value contains a reference not known in the system Invalid value format Current state of the resource is not compatible with the requested operation (e.g. attempt to activate an already activated card)
401	Unauthorized	The request did not include an authentification token or the authentication token was expired
403	Forbidden	The client did not have permission to access or perform specific action on the resource.
404	Not fund	The requested resource was not found. This error code indicates that the requested resource could not be located on the server, typically due to an issue with the provided URL. This may occur due to invalid identifiers in the dynamic parts of the URL path, or errors in the static parts of the endpoint. For instance, if a client sends a request with the URL "issuers/12356/crds/external-cards/200005/block" instead of "/issuers/12356/cards/external-cards/200005/block", the server may return a 404 error, since the endpoint URL does not exist. If a request is made with an unknown issuer ID or card reference in the example above, or if the card reference is not related the issuer ID, the server will also return a 404 error.
500	Internal Server error	The request was not completed due to an internal error on the server side.
502	Bad Gateway	The server acting as gateway received invalid response from the upstream server.

Our API Responses contain two separate part :

responseMetadata is containing technical information about the execution of the request.
data the functional and business data.

The responseMetadata is formatted as shown hereafter and contains the following information

correlationId : WL-Correlation-Id from the headers
statusMessage : Message about Execution Status
statusCode : HTTP Response Code (same than Response one)
responseDateTime : when response is received
timeTakenMs : elapsed ms time on server time (for 200 OK cases)

Block card – unknown card (http 404)


                {
                    "responseMetadata": {
                        "statusMessage": "UNKNOWN_CARD: Error occurred while blocking the card
                       : [2000000033334867] is null in BlockCardOutput blockCard()",
                        "statusCode": 404,
                        "responseDateTime": "2023-03-15T13:59:17.231+0100",
                        "timeTakenMs": 20
                    }
                }

Block card – bad request - invalid data request (http 400)


                {
                    "responseMetadata": {
                        "statusMessage": "INVALID_BLOCKING_REASON: Error occurred while block the card by input:  
                        [fae96f4c-1697-4b18-98ae-6b84c355776d] during 
                        BlockCardOutput blockCard() call:   [CARD_INVALID_BLOCKING_REASON]",            
                        "statusCode": 400,
                        "responseDateTime": "2023-03-15T14:02:20.446+0100",
                        "timeTakenMs": 26
                    }
                }

Block card – bad request – mandatory field missing (http 400)


                {
                    "responseMetadata": {
                        "statusMessage": "REQUEST_VALIDATION_ERROR: [blockingReason - must not be null]",
                        "statusCode": 400,
                        "responseDateTime": "2023-03-15T14:04:58.955+0100",
                        "timeTakenMs": 16
                    }
                }

Block card – bad request – mandatory field missing (http 400)


                            {
                            "responseMetadata": {
                            "statusMessage": "REQUEST_VALIDATION_ERROR: [blockingReason - must not be null]",
                            "statusCode": 400,
                            "responseDateTime": "2023-03-15T14:04:58.955+0100",
                            "timeTakenMs": 16
                            }
                            }

Block card – forbidden (http 403)


            {
            "responseMetadata": {
            "correlationId": "af5c01bc-18de-4918-98df-74af278b7849",
            "statusMessage": "The current user is not allowed to do the action! Category: 
             ISSUER, Resource: 1234, Action: access",
            "statusCode": 403,
            "responseDateTime": "2023-03-15T14:11:22.111+0100",
            "timeTakenMs": 18
            }
            }

Metadata

Worldline Card Issuing Processing API Responses contains two separate part :

responseMetadata is containing technical information about the execution of the request.
data the functional and business data.

The responseMetadata is formatted as shown hereafter and contains the following information

correlationId : WL-Correlation-Id from the headers
statusMessage : Message about Execution Status
statusCode : HTTP Response Code (same than Response one)
responseDateTime : when response is received
timeTakenMs : elapsed ms time on server time (for 200 OK cases)

Response

              
{
    "responseMetadata": {
        "correlationId": "8f7cb0d5-3f5b-4935-bc10-e2c45b46b5df",
        "statusMessage": "Executed successfully",
        "statusCode": 200,
        "responseDateTime": "2021-10-13T15:59:50.302+0200",
        "timeTakenMs": 129
    },
    "data": {
        ...
    }
}

Request correlation identifier

Each API request has an associated correlation identifier. This correlation identifier can be found metadata information and in WL-Correlation-ID Request headers. This correlation identifier can be set in WL-Correlation-ID Request headers and is used to provide support about a specific request. If not provided, it's generated by Worldline system as an UUID.

Pagination

All of the APIs that could return a huge list of resources are supporting pagination using the page and offset parameters in the request formatted on with the following way : ?page={{page}}&offset={{offset}}

Request with default offset

{{baseUrl}}/issuers/{{issuerId}}/accounts/{{accountReference}}/operations?page=5

Response with default offset

{{baseUrl}}/issuers/{{issuerId}}/accounts/{{accountReference}}/operations?page=5&offset=100

Field expansion

Some of the fields can be expanded in order to retrieve additional information when retrieving the detail of one resource within the same request by using the embed request parameter. Multiple fields can be provided and should be separated by a comma (,). By default fields that can be expanded are not provided in the response

Request

{{baseUrl}}/issuers/{{issuerId}}/cards/{{cardReference}}?embed=cardContract

Field filtering

In order to retrieve only the attributes that are relevant in the response of the APIs, the filter parameter can be used in the request. The name of the fields to be retrieved should be provided and you can filter recursively by specifying nested fields after a dot(.). Multiple fields can be provided and should be separated by a comma (,)

Request

{{baseUrl}}/issuers/{{issuerId}}/contracts/create-consumer-contract?filter=contract.contractIdentifier,contract.cardContracts.card.cardIdentifier

Versionning

The major versions of the Wordline Card Issuing Processing APIs are distinguished by the version indicator in the URLs (currently the V2 /api/v2/ ). Minor version updates will not result in a new version indicator in the API URLs. All minor updates are considered to be backwards compatible. Only when changes are not backwards compatible, will we issue a new major version of the API.