Card Fulfilment APIs Lifecycle Guide

Temenos card fulfilment APIs enable two key fulfilment flows: card issuance and management, and funds authorization and clearing. This guide shows developers how they can use these APIs to create card fulfillment solutions with external systems or proxy services using the generic adapter for integrations to Temenos Exchange.

Resource: View and download the Cards Fulfilment APIs

Fulfilment Flows

The Temenos Exchange components handle cards fulfilment integration between Temenos solutions and external cards management systems. This requires two types of fulfilment flows:

• Cards issuance and management, which involves:
  • User creation and management.
  • Card product creation and management.
  • Card creation and management.

• Funds authorization and clearing, which involves:
  • Funds authorization.
  • Funds clearing.
  • Balance inquiries.

Integration Components

Cards fulfilment integration comprises two components:

• A fulfilment microservice which handles all semantic transformation and enrichment of all fulfilment requests.
• An adapter that handles syntactic transformations, external system connectivity and point-of-presence.

Important: Although the fulfilment microservice is generic for all the external systems we support, every external system within Temenos Exchange has a dedicated, specific adapter. If the external system isn't a member of Temenos Exchange, then developers can use the generic adapter from Temenos Exchange for integrations.

Solution Architectures

The following high-level architectures show you the components you'll need to create an integration solution for card fulfilment and funds fulfilment respectively.

Cards Fulfilment Flow

Tip: Click diagram to expand.

 

Cards fulfilment is requested by the Temenos Exchange adapter and fulfilled by the external cards management system. In this case, the adapter is configured with a webhook service that's hosted by the external system - or its proxy - to receive and fulfil all requests for card issuance. Typically, cards fulfilment involves creating and managing the following resources:

• Card Users
• Card Products
• Cards

Funds Fulfilment Flow

Tip: Click diagram to expand.

Funds fulfilment is requested by external cards management systems for debit card transactions and fulfilled by Transact through the Temenos Exchange adapter. In this case, the external system proxy is configured with a webhook service that's hosted by the the Temenos Exchange adapter to receive and fulfil all requests for funds. Typically, the following functions for funds fulfilment are supported through the adapter:

• Funds Authorization
• Funds Clearing
• Card Balances

Webhook Services

Generic cards and funds fulfilment adapters from Temenos Exchange use webhooks to integrate with external card management systems or their proxies.

Funds fulfilment is implemented by a webhook service that's run by the Temenos Exchange adapter. This service accepts fulfilment requests and returns responses in JSON format. In a similar way, cards fulfilment is implemented as a webhook service where the adapter sends requests and receives responses in JSON format.

Endpoints

Webhook service endpoints require the following characteristics:

Tip: Click diagram to expand.

Security

Authentication

It's important to secure the webhook service, whether it's card fulfilment hosted by external systems, or funds fulfilment hosted by Temenos Exchange. The supported authentication method is Mutual TLS (mTLS) authentication using certificates.

Message Integrity

It's important to ensure the integrity of the messages which are sent and received carrying fulfilment requests and responses. The supported message integrity method is secret key based HMAC using SHA-256 based hashing.

Failure Handling

Invalid Message Payload

Any invalid data point in message payloads results in the entire request being rejected, even before any fulfilment task is attempted. In such a failure scenario, the respective webhook services respond with http status code 400 - Bad Request with an error message payload.

Failed Fulfilment Requests

Fulfilment requests can fail if the business conditions don't support the request. For example:

Tip: Click diagram to expand.

In such a failure scenario, the respective webhook services respond with http status code 422 - Unprocessable Entity with a fulfilment failure message payload.

Re-triable Failures

It's not possible to simply retry failed requests, if the request has failed for business reasons or an invalid data point. Changes to the business conditions and/or a change to the request payload are required before the request can be sent again.

However, there are other kinds of failure where no action is required from the request client, and which require requests to be sent again, until the request is fulfilled. The following failures would be retried until they succeeded, with a configurable retry frequency and retry interval.

• Network or infrastructure failures resulting in http status code 5xx (for example, 502 - Bad Gateway).
• Configuration failures resulting in http status codes 401, 403, 404 (for example, 401 - Unauthorized).

In fact, it's essential that valid requests which are valid and complete from the requesting client point of view should succeed, wherever possible, through repeated request attempts (bearing in mind the various failure possibilities beyond request payload).

Message Payloads

This section describes the detailed message payloads that are used in fulfilment requests and responses.

Cards Fulfilment Payloads

Cards fulfilment request payloads are prepared and sent by the Temenos Exchange adapter to an external system proxy service that fulfil and return the appropriate responses. If fulfilment is requested from other channels other than Temenos Infinity and completed by the external system then the adapters listen for events through which the respective resources are updated.

Card Users

Card user is a resource that represents the users who request and use the cards. Every card is always owned by a user. Every transaction that's carried out using a card has a user associated with the transaction.

Create User Request

Notes:¹userId is either generated by the fulfilment server or supplied as part of the request. If the fulfilment service is capable of using the supplied Id, this property becomes Required

Create User Response

Update User Request

Notes: ¹userId is either generated by the fulfilment server or supplied as part of the request. If the fulfilment service is capable of using the supplied Id, then this property becomes Required.

Update User Response

Card Products

Card products resources represent a higher level definition for cards which can inherit their properties and behaviour from them. Cards products can be created in the external systems directly, but still require events to update the rest of Temenos solutions. When events are received for updates from external systems, the Temenos Exchange adapter responds with an acknowledgement through the http status code 200 - OK.

Card Product Created Event

Notes:¹productId is restricted to a maximum of 4 characters in Transact. This needs to be taken into account when products are created in external systems.

Card Product Updated Event

Cards

Card resources represent the cards that are issued under a card product and used by a user. Each card transitions through various states during its lifecycle.

Create Card Request

Note: ¹cardId is either generated by the fulfilment server or supplied as part of the request. If the fulfilment service is capable of using the supplied Id, this property becomes Required.

Create Card Response

Funds Fulfilment Payloads

Funds fulfilment request payloads are prepared and sent by external system proxy services to the Temenos Exchange adapter which fulfills the requests in Transact and returns the appropriate responses.

Funds

Funds resources represent operations on funding, such as authorization, clearing and balances. Each debit card has an active account associated with it, which is acted on for every transaction.

Funds Fulfillment Request

Funds Fulfilment Success Response

Funds Fulfilment Failure Response

Funds Fulfilment Error Response

Funds Fulfilment: Sample Payloads

Sample Funds Fulfilment Request

{
 "requestId": "49db0c72-5c7f-4a34-8645-9e1cb4cc60c8",
 "requestType": "authorization",
 "cardId": "3b5d5881-5e73-414c-becb-483fefb7ac7b",
 "cardUserId": "21cbf147-43a4-41bd-8fe6-1ce0029c1140",
 "userActionTime": "2022-11-01T05:47:48.929Z",
 "processingTime": "2022-11-01T05:48:22.919Z",
 "transaction": {
 "id": "5412734920648",
 "amount": 57.23,
 "currencyCode": "USD",
 "narratives": "Restaurant Bill"
 },
 "fees": {
 "totalAmount": 5,
 "currencyCode": "USD",
 "details": [
 {
 "name": "feetype1",
 "amount": 5,
 "currencyCode": "USD"
 }
 ]
 },
 "cardAcceptor": {
 "merchantId": "F1984",
 "categoryCode": "1111",
 "name": "McDonalds SF"
 },
 "cardAcquirer": {
 "institutionId": "849411",
 "transactionReference": "c93690d5-eed0-4295-8f5d-6e35c3014838"
 }
}

 

Sample Funds Fulfilment Success Response (HTTP Status Code 200 - OK)

{
 "requestType": "authorization",
 "requestId": "49db0c72-5c7f-4a34-8645-9e1cb4cc60c8",
 "transaction": {
 "id": "5412734920648",
 "amount": 57.23,
 "narratives": "Restaurant Bill",
 "currencyCode": "USD"
 }
}

 

Sample Funds Fulfilment Failure Response (HTTP Status Code 422 - Unprocessable Entity)

{
 "requestId": "49db0c72-5c7f-4a34-8645-9e1cb4cc60c8",
 "requestType": "authorization",
 "declinedReason": "INSUFFICIENT_FUNDS"
}

 

Sample Funds Fulfilment Error Response (HTTP Status Code 400 - Bad Request)

[
 {
 "code": "400100",
 "message": "Invalid requestType. Not one of [authorization, authorization.incremental, authorization.
reversal, authorization.refund, authorization.refund.reversal, clearing, clearing.direct, clearing.refund, 
balances.inquiry]",
 "timestamp": "2022-12-05T07:45:37Z"
 }
]

View and Download the Card Fulfilment APIs

Resource: View and download the Cards Fulfilment APIs