> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/3d-secure/integrate-d1-api/d1-api-reference/outbound-api-from-d1/consumer-api.md).
# Consumer API
## Get Consumer Information
> This request is used by the D1 backend to request the details of an end user (consumer) from the issuer backend.\
\
> \
> \If the end user information is associated with the card, it is possible to activate "cardId" query parameter via an onboarding flag.\
```json
{"openapi":"3.0.0","info":{"title":"D1 Services API - BankBackend API","version":"1.0"},"servers":[{"url":"https://YOUR_DOMAIN_NAME","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"A JWT generated by the [Get Authorization Token API](oauth2-api).
The server checks the validity of the provided token to control access to this protected resource. Please refer to [Get OAuth 2.0 access token](../../../integrate-the-d1-api/get-oauth-2.0-access-token) for more details on the flow and on how to get this JWT.","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"consumerInfo":{"type":"object","title":"ConsumerInfo","description":"The following objects represent the personal information of the end user (consumer).","properties":{"language":{"type":"string","description":"Language of the end user (consumer). Based on ISO format for language (ISO 639–1) and an alpha-2 country code (ISO 3166–1 alpha-2). The language must be lowercase, and the country must be uppercase ideally. The language and country should be separated using a minus character \"-\".
**Note**: This field is mandatory for Click to Pay.","minLength":5,"maxLength":5,"pattern":"^[a-z]{2}-[a-zA-Z]{2}$"},"firstName":{"type":"string","description":"First name of the end user (consumer).
**Note**: This field is mandatory for Click to Pay.","minLength":1,"maxLength":128,"pattern":"^[\\p{L}\\p{N}\\u0600-\\u06FF ,.'_#;:\\/-]{1,128}$"},"middleName":{"type":"string","description":"Middle name of the end user (consumer).","minLength":1,"maxLength":128,"pattern":"^[\\p{L}\\p{N}\\u0600-\\u06FF ,.'_#;:\\/-]{1,128}$"},"lastName":{"type":"string","description":"Last name of the end user (consumer).
**Note**: This field is mandatory for Click to Pay.","minLength":1,"maxLength":128,"pattern":"^[\\p{L}\\p{N}\\u0600-\\u06FF ,.'_#;:\\/-]{1,128}$"},"dateOfBirth":{"type":"string","description":"Date of Birth.","pattern":"^\\d{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[0-1])$"},"title":{"type":"string","description":"Title of the end user (consumer).","minLength":1,"maxLength":40,"pattern":"^[\\p{L}\\p{N}\\u0600-\\u06FF ,.'_#;:\\/-]{1,40}$"},"email":{"type":"string","description":"Email of the end user (consumer).
**Note**: This field is mandatory for Click to Pay (Mastercard).","pattern":"^[a-zA-Z0-9_+&*-]+(?:\\.[a-zA-Z0-9_+&*-]+)*@(?:[a-zA-Z0-9-]+\\.)+[a-zA-Z]{2,15}$"},"mobilePhoneNumber":{"type":"object","description":"Phonenumber of the end user (consumer).
**Note**: This field is mandatory for Click to Pay.","properties":{"countryCode":{"type":"string","description":"International country code for \"phoneNumber\".","minLength":1,"maxLength":10,"pattern":"^\\+[0-9]{1,10}$"},"phoneNumber":{"type":"string","description":"Phone number.","minLength":1,"maxLength":14,"pattern":"^[0-9]{1,14}$"}},"required":["countryCode","phoneNumber"]},"residencyAddress":{"type":"object","description":"Residency address.
**Note**: This field is mandatory for Click to Pay.","properties":{"line1":{"type":"string","description":"First line of the address.","minLength":1,"maxLength":256,"pattern":"^[\\p{L}\\p{N}\\u0600-\\u06FF ,.'_#;:\\/-]{1,256}$"},"line2":{"type":"string","description":"Second line of the address.","minLength":1,"maxLength":256,"pattern":"^[\\p{L}\\p{N}\\u0600-\\u06FF ,.'_#;:\\/-]{1,256}$"},"city":{"type":"string","description":"City.","minLength":1,"maxLength":128,"pattern":"^[\\p{L}\\p{N}\\u0600-\\u06FF ,.'_#;:\\/-]{1,128}$"},"state":{"type":"string","description":"State.","minLength":1,"maxLength":128,"pattern":"^[\\p{L}\\p{N}\\u0600-\\u06FF ,.'_#;:\\/-]{1,128}$"},"zipCode":{"type":"string","description":"Zip Code.","minLength":1,"maxLength":10,"pattern":"^[0-9a-zA-Z ]{1,10}$"},"countryCode":{"type":"string","description":"Country code. Based on ISO 3166-1 alpha-2 format.
**Note**: This field is mandatory for Click to Pay.","minLength":2,"maxLength":2,"pattern":"^[A-Z]{2}$"}},"required":["line1","zipCode","countryCode"]}},"required":["firstName","lastName"]},"error":{"title":"error","type":"object","description":"An error occured","properties":{"error":{"type":"string","description":"Detailed description of the error occured."}}},"issuerId":{"maxLength":10,"minLength":10,"type":"string"},"consumerId":{"type":"string","description":"Unique identifier of the consumer. ","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]{1,64}$"},"cardId":{"type":"string","description":"Unique identifier of the card.","minLength":1,"maxLength":48,"pattern":"^[A-Za-z0-9_-]{1,48}$"}},"parameters":{"issuer-id-path":{"description":"The id of the issuer","in":"path","name":"issuerId","required":true,"schema":{"$ref":"#/components/schemas/issuerId"}},"consumer-id-path":{"description":"The id of the consumer","in":"path","name":"consumerId","required":true,"schema":{"$ref":"#/components/schemas/consumerId"}}}},"paths":{"/banking/d1/v1/issuers/{issuerId}/consumers/{consumerId}?cardId=":{"get":{"description":"This request is used by the D1 backend to request the details of an end user (consumer) from the issuer backend.
\n\nIf the end user information is associated with the card, it is possible to activate \"cardId\" query parameter via an onboarding flag.","responses":{"200":{"description":"All needed information related to the requested end user (consumer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/consumerInfo"}}}},"403":{"description":"Forbidden (Invalid state)"},"404":{"description":"End user (consumer) was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}},"summary":"Get Consumer Information","operationId":"getConsumerInfo","parameters":[{"$ref":"#/components/parameters/issuer-id-path"},{"$ref":"#/components/parameters/consumer-id-path"},{"$ref":"#/components/parameters/x-correlation-id"},{"schema":{"$ref":"#/components/schemas/cardId"},"in":"query","name":"cardId"}]}}}}
```
## Authenticate
> This request is sent by D1 to request an end user authentication.
```json
{"openapi":"3.0.0","info":{"title":"D1 Services API - BankBackend API","version":"1.0"},"servers":[{"url":"https://YOUR_DOMAIN_NAME","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"A JWT generated by the [Get Authorization Token API](oauth2-api).
The server checks the validity of the provided token to control access to this protected resource. Please refer to [Get OAuth 2.0 access token](../../../integrate-the-d1-api/get-oauth-2.0-access-token) for more details on the flow and on how to get this JWT.","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"cardId":{"type":"string","description":"Unique identifier of the card.","minLength":1,"maxLength":48,"pattern":"^[A-Za-z0-9_-]{1,48}$"},"error":{"title":"error","type":"object","description":"An error occured","properties":{"error":{"type":"string","description":"Detailed description of the error occured."}}}}},"paths":{"/banking/d1/v1/issuers/{issuerId}/consumers/{consumerId}/authentication":{"post":{"summary":"Authenticate","operationId":"authenticate-consumer","description":"This request is sent by D1 to request an end user authentication.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["authenticationId","operation"],"properties":{"authenticationId":{"type":"string","description":"The authentication request identifier. For 3DS, the value is the same as the 'acsTransactionId'."},"operation":{"type":"string","description":"The operation type.","enum":["3DS_CHALLENGE_OOB_ISSUER"]},"details":{"oneOf":[{"title":"3DS_CHALLENGE_OOB_ISSUER operation","description":"Details information that depends on the operation.","properties":{"cardId":{"$ref":"#/components/schemas/cardId"},"panSuffix":{"type":"string","minLength":4,"maxLength":4,"description":"Last 4 digits of the card PAN which relates to this deliverOTP operation."},"acsTransactionId":{"description":"The ACS transaction identifier.","type":"string"},"purchase":{"description":"The purchase details of the payment 3DS Authentication.
In case of non-payment authentication, 'amount' and 'currencyCode' are not present.","type":"object","properties":{"merchantName":{"description":"The merchant name.","type":"string"},"amount":{"description":"The nominal transaction amount value. Value without the decimal operator. Use the currency exponent to display amount with decimal. For example, a amount of 789.99€ Euro is sent as 78999.","type":"string"},"currencyCode":{"description":"The transaction currency code. Currency code in ISO 4217 alpha code format.","type":"string"}}}}}]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["authenticationStatus"],"properties":{"authenticationStatus":{"type":"string","description":"Status of the operation","enum":["AUTHENTICATED","PENDING","NO_AUTHENTICATOR"]}}}}}},"401":{"description":"Authorization missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"403":{"description":"Action forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}}}}}}
```
## Get Authentication Result
> Polling request to get the authentication result.
```json
{"openapi":"3.0.0","info":{"title":"D1 Services API - BankBackend API","version":"1.0"},"servers":[{"url":"https://YOUR_DOMAIN_NAME","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"A JWT generated by the [Get Authorization Token API](oauth2-api).
The server checks the validity of the provided token to control access to this protected resource. Please refer to [Get OAuth 2.0 access token](../../../integrate-the-d1-api/get-oauth-2.0-access-token) for more details on the flow and on how to get this JWT.","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"error":{"title":"error","type":"object","description":"An error occured","properties":{"error":{"type":"string","description":"Detailed description of the error occured."}}}}},"paths":{"/banking/d1/v1/issuers/{issuerId}/consumers/{consumerId}/authentication/{authenticationId}":{"get":{"description":"Polling request to get the authentication result.","summary":"Get Authentication Result","operationId":"getAuthenticationResult","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["authenticationStatus"],"properties":{"authenticationStatus":{"type":"string","description":"Status of the operation","enum":["AUTHENTICATED","PENDING","AUTHENTICATION_FAILED","TECHNICAL_ERROR"]},"reason":{"type":"string","minLength":1,"maxLength":64,"description":"The reason of the technical error. Human readable text without personal or sensitive data."}}}}}},"403":{"description":"Forbidden (Invalid state)"},"404":{"description":"End user (consumer) was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}}}}}}
```
## Notify Consumer Operation (V1)
> This request is used by D1 to notify the issuer backend about operations done on a consumer.
```json
{"openapi":"3.0.0","info":{"title":"D1 Services API - BankBackend API","version":"1.0"},"servers":[{"url":"https://YOUR_DOMAIN_NAME","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"A JWT generated by the [Get Authorization Token API](oauth2-api).
The server checks the validity of the provided token to control access to this protected resource. Please refer to [Get OAuth 2.0 access token](../../../integrate-the-d1-api/get-oauth-2.0-access-token) for more details on the flow and on how to get this JWT.","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"consumerOperationNotification":{"title":"Consumer Operation","type":"object","description":"Operation details related to a specific operationId","properties":{"operationId":{"$ref":"#/components/schemas/operationId"},"operation":{"type":"string","description":"The operation type.","enum":["ENROLL_AUTHN"]},"status":{"$ref":"#/components/schemas/operationStatusSuccessfulFailed"},"startTime":{"$ref":"#/components/schemas/operationStartTime"},"endTime":{"$ref":"#/components/schemas/operationEndTime"},"requestorType":{"type":"string","enum":["USER"]},"requestorId":{"type":"string","description":"The consumerId of the end user."},"details":{"type":"object","oneOf":[{"title":"ENROLL_AUTHN operation","properties":{"appInstanceId":{"$ref":"#/components/schemas/appInstanceId"},"authnType":{"$ref":"#/components/schemas/authnType"}}}]},"error":{"$ref":"#/components/schemas/operationError"}},"required":["operationId","operation","status","startTime","requestorId","requestorType"]},"operationId":{"type":"string","description":"Unique identifier of the operation","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]{1,64}$"},"operationStatusSuccessfulFailed":{"type":"string","description":"Status of the operation","enum":["SUCCESSFUL","FAILED"]},"operationStartTime":{"type":"string","title":"Operation Start Time","description":"The time the request has been processed.\nFormat ISO 8601 YYYY-MM-DDThh:mm:ssTZD","minLength":1,"maxLength":64},"operationEndTime":{"type":"string","title":"Operation End Time","description":"The time the operation has been completed.\nFormat ISO 8601 YYYY-MM-DDThh:mm:ssTZD\nnote: This is an optional field and might not be returned for synchronous operations.","minLength":1,"maxLength":64},"appInstanceId":{"description":"Unique identifier of the issuer application instance.","type":"string"},"authnType":{"type":"string","enum":["BIOMETRIC","PLATFORM"]},"operationError":{"type":"string","description":"Human readable string representing the error, only present in case of operation failure"},"error":{"title":"error","type":"object","description":"An error occured","properties":{"error":{"type":"string","description":"Detailed description of the error occured."}}}}},"paths":{"/banking/d1/v1/issuers/{issuerId}/consumers/{consumerId}/notifications":{"post":{"summary":"Notify Consumer Operation (V1)","operationId":"notify-consumer-operation","description":"This request is used by D1 to notify the issuer backend about operations done on a consumer.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/consumerOperationNotification"}}}},"responses":{"204":{"description":"Successful"},"400":{"description":"Bad Request, Invalid request URI or header, or unsupported nonstandard parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"401":{"description":"The provided Authorization header is missing or invalid"},"404":{"description":"Resource not found. Unknown issuerId or consumerId or accountId or cardId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}}}}}}
```
## Deliver OTP
> This request is used by D1 during the tokenization flow for a card in case it is required to send an OTP to the end user (consumer) "consumerId".\
> \
> The parameter 'threeDSDetails' is available in the scenario :\
> \* 3DS Authentication\
> \\
> \>### Note \
> \> This is applicable only if the issuer decides to rely on its own messaging system to send messages to their customers and not on the D1 platform.
```json
{"openapi":"3.0.0","info":{"title":"D1 Services API - BankBackend API","version":"1.0"},"servers":[{"url":"https://YOUR_DOMAIN_NAME","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"A JWT generated by the [Get Authorization Token API](oauth2-api).
The server checks the validity of the provided token to control access to this protected resource. Please refer to [Get OAuth 2.0 access token](../../../integrate-the-d1-api/get-oauth-2.0-access-token) for more details on the flow and on how to get this JWT.","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"error":{"title":"error","type":"object","description":"An error occured","properties":{"error":{"type":"string","description":"Detailed description of the error occured."}}},"digitalCardRequestorInformation":{"title":"digitalCardRequestorInformation","additionalProperties":false,"type":"object","description":"Provides details about the digital card requestor.","properties":{"id":{"type":"string","description":"Digital Card requestor identifier. This is provided by the TSP itself.","minLength":11,"maxLength":11},"walletId":{"type":"string","description":"MasterCard ONLY. Wallet Application identifier","maxLength":32},"name":{"type":"string","maxLength":256,"description":"Wallet or Merchant human readable name"},"tspId":{"type":"string","maxLength":11,"minLength":11,"description":"VISA only. Identifiers of the couple Token Requestor - Token Service Provider"},"originalDigitalCardRequestorId":{"type":"string","description":"Applies only to VISA in case of token for token provisioning","minLength":11,"maxLength":11}}},"deviceInformationForOTP":{"title":"deviceInformationForOTP","additionalProperties":false,"type":"object","description":"Provides details about the device that has been used to trigger the request.\n\nData availability dependes on the requestor.","properties":{"digitalCardStorageType":{"type":"string","maxLength":32,"description":"Type of the token sorage location. Following values are possible:\n- HCE\n- SPAY_PHONE\n- SPAY_TABLET\n- SPAY_WATCH\n- SPAY_TV\n- IPHONE\n- IWATCH\n- IPAD\n- MAC_BOOK\n- ANDROID_PHONE\n- ANDROID_TABLET\n- ANDROID_WATCH\n- MOBILE_PHONE\n- TABLET\n- WATCH\n- MOBILE_PHONE_OR_TABLET\n- BRACELET\n- UNKNOWN"},"phoneNumber":{"type":"string","description":"Device phone number","minLength":1,"maxLength":20},"deviceName":{"type":"string","maxLength":128,"description":"Device name set by the consumer"}}}}},"paths":{"/banking/d1/v1/issuers/{issuerId}/consumers/{consumerId}/otp":{"post":{"summary":"Deliver OTP","operationId":"deliver-otp","responses":{"204":{"description":"No Content"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"401":{"description":"Authorization missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"403":{"description":"Action forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}},"description":"This request is used by D1 during the tokenization flow for a card in case it is required to send an OTP to the end user (consumer) \"consumerId\".\n\nThe parameter 'threeDSDetails' is available in the scenario :\n * 3DS Authentication\n\n>### Note \n> This is applicable only if the issuer decides to rely on its own messaging system to send messages to their customers and not on the D1 platform.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"otp":{"type":"object","description":"The OTP value","required":["value","reason"],"properties":{"value":{"type":"string","minLength":1,"maxLength":15},"expirationDate":{"type":"string","description":"The expiration time for OTP.\nFormat shall be expressed in ISO 8601 extended format: YYYY-MM-DDThh:mm:ss[.SSS]Z\nwhere [.SSS] is optional and can be from 1 to 3 digits.\nValue will be in GMT.","minLength":4,"maxLength":32},"reason":{"type":"string","enum":["CARD-DIGITIZATION","DEVICE-BINDING","CARDHOLDER-VERIFICATION","3DS-AUTHENTICATION"]}}},"deliveryChannel":{"type":"string","enum":["SMS","EMAIL"],"description":"The channel on which the end user has decided to receive the OTP."},"digitalCardRequestor":{"$ref":"#/components/schemas/digitalCardRequestorInformation"},"deviceInformation":{"$ref":"#/components/schemas/deviceInformationForOTP"},"panSuffix":{"type":"string","minLength":4,"maxLength":4,"description":"Last 4 digits of the PAN of the card to be tokenized (digitized)"},"threeDSDetails":{"type":"object","properties":{"acsTransactionId":{"description":"The ACS transaction identifier.","type":"string"},"purchase":{"description":"The purchase details of the payment 3DS Authentication.
In case of non-payment authentication, 'amount' and 'currencyCode' are not present.","type":"object","properties":{"merchantName":{"description":"The merchant name.","type":"string"},"amount":{"description":"The nominal transaction amount value. Value without the decimal operator. Use the currency exponent to display amount with decimal. For example, a amount of 789.99€ Euro is sent as 78999.","type":"string"},"currencyCode":{"description":"The transaction currency code. Currency code in ISO 4217 numeric code format.","type":"string"}}}}}},"required":["otp","deliveryChannel","panSuffix"]}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.payments.thalescloud.io/3d-secure/integrate-d1-api/d1-api-reference/outbound-api-from-d1/consumer-api.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.