Citi Webhooks API

openapi: 3.2.0
info:
  description: The Wallets API allows client to check the eligibility, request for tokenization through manual and push-provisioning, OTP based step-up authentication and webhook notifications.
  version: ''
  title: Grace Wallet Marqeta Webhooks API
servers:
- url: https://tts.apib2b.citi.com/tts/cards
  description: production gateway URL
- url: https://tts.sandbox.apib2b.citi.com/tts/cards
  description: sandbox URL
security:
- clientCredentials: []
tags:
- name: Webhooks
  description: Operation related to webhook requests.
paths:
  /digitalwalletwebhooks/v1/digitalwallettoken:
    post:
      tags:
      - Webhooks
      summary: Digital Wallet Token
      description: ''
      operationId: digitalWalletToken
      parameters:
      - name: client_id
        in: query
        required: true
        description: This is your unique identifier shared during your CitiConnect API onboarding. This is the same `client_id` used for oauth token generation
        schema:
          type: string
      - name: Content-Type
        in: header
        description: Supports application/json.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: 'Request should contain OAuth Authorization header <br> **OAuth:** <br> Request contains a header parameter in the form of Authorization: Bearer (access_token), where access_token is generated using the OAuth url<br>  `Example` : Bearer AAIkMjU2OTI4OGQtODY5Ny00ZjgzLTg0NzEtY2QyZWYwZjM5ZjJk_m3yqnGAbxR_ovVx5bs9OUfF0dd52qHadLtw2ARkwCw2BJcwg1zHsTOuvjPtsW5ioxxd2xXXjlDDCKLuvg15Ce1gzGxTu17xEvLOzSECLIdU_02JbpS3h9ee9GzB-u_MPfKseOiACXYAh_7AVWQhtRMLDKd8RgCUsNzTGXXBeE4'
        required: true
        schema:
          type: string
      - name: Accept
        in: header
        description: Content-Types that are acceptable for the response. Always pass application/json or don't pass this header.
        required: false
        schema:
          type: string
          default: application/json
      - name: Accept-Language
        in: header
        description: List of acceptable human languages for response.
        required: false
        schema:
          type: string
      - name: Content-Type
        in: header
        description: The MIME type of the body of the request (POST). Always pass application/json.
        required: true
        schema:
          type: string
          default: application/json
      - name: Req-Sys-Id
        in: header
        description: 'Client unique ID to identify the particular request. <br> `Format`: UUID <br>`Example`: 123d837e-958a-4e9f-bc97-4843ec948123'
        required: true
        schema:
          type: string
      - name: Country
        in: header
        description: 'Country Code in alpha-2 format. <br>`Example`: US'
        required: true
        schema:
          type: string
      - name: Region
        in: header
        description: 'Country Region. <br> `Example`: NAM'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success Response after Webhook Token Event
          headers:
            Api-Sys-Id:
              description: Citi Commercial Cards API Tracking ID
              schema:
                type: string
        '400':
          description: Missing or invalid request parameter <table><tr><td>Error Code</td><td>Error Description</td></tr> <tr><td>WWAA0001</td><td>Marqeta FPAN ID is invalid</td></tr> <tr><td>WWAA0003</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>WWAA0004</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>WWAA0005</td><td>Event Type is invalid</td></tr> <tr><td>WWAA0006</td><td>Fulfilment status is invalid</td></tr> <tr><td>WWAA0007</td><td>Marqeta DPAN Reference Id is empty</td></tr> <tr><td>WWAA0008</td><td>Notification ID is invalid</td></tr> <tr><td>WWAA0009</td><td>Marqeta DPAN Reference Id is invalid</td></tr> <tr><td>WWAA0010</td><td>Number of notification in array is invalid</td></tr> <tr><td>WWAA0011</td><td>DPAN number is invalid</td></tr> <tr><td>WWAA0012</td><td>Token Requestor Id is invalid</td></tr> <tr><td>WWAA0013</td><td>FPAN is invalid</td></tr><br><tr><td>GRC0002</td><td>Client ID is missing in the request header</td></tr> <tr><td>GRC0003</td><td>Invalid JSON Input</td></tr> <tr><td>GRC0004</td><td>Region ID is not available in the request</td></tr> <tr><td>GRC0005</td><td>Client Tracking ID is missing in the request header</td></tr> <tr><td>GRC0007</td><td>Client requested MediaType is not supported.</td></tr> <tr><td>GRC0008</td><td>Invalid request. Unable to bind incoming request</td></tr> <tr><td>GRC0010</td><td>Client Tracking ID length should contain a min of 1 character and a max of 36 characters</td></tr> <tr><td>GRC0016</td><td>Country code is not available in the request</td></tr> <tr><td>WEIM0001</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>WEIM0005</td><td>Encrypted data is null/empty. Please try again, or contact Citi support if you have any further questions or comments.</td></tr> <tr><td>WEIC0001</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> </table>
          headers:
            Api-Sys-Id:
              description: Citi Commercial Cards API Tracking ID
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookErrorResponse'
        '401':
          description: UnAuthorized request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnAuthorizedResponse'
        '405':
          description: Method Not Allowed.
          headers:
            Api-Sys-Id:
              description: Citi Commercial Cards API Tracking ID
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowedResponse'
        '500':
          description: Internal server error. <table><tr><td>Error Code</td><td>Error Description</td></tr> <tr><td>WWAA0002</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>WWAM0014</td><td>webhooks notification should have min and max of 1 item in an array</td></tr><br><tr><td>GRC0001</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>GRC0009</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>GRC0014</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>GRC0015</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>GRVL0001</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>GRVL0002</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>GRVL0003</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>GRVL0004</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>GRVL0005</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>GRVL0006</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>GRVL0021</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>WEIM0002</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>WEIM0004</td><td>We have encountered error during Marqeta JWE Decryption. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>WEIC0002</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>WEIC0003</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>WEUL0002</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>ECSA0002</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>ECSA0007</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> </table>
          headers:
            Api-Sys-Id:
              description: Citi Commercial Cards API Tracking ID
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Webhook%5fDigitalWalletToken%5fArray%5fType'
        description: Webhook token event Request Body
        required: true
  /digitalwalletwebhooks/v1/digitalwallettokentransition:
    post:
      tags:
      - Webhooks
      summary: Digital Wallet Token Transition
      description: ''
      operationId: digitalWalletTokenTransition
      parameters:
      - name: client_id
        in: query
        required: true
        description: This is your unique identifier shared during your CitiConnect API onboarding. This is the same `client_id` used for oauth token generation
        schema:
          type: string
      - name: Content-Type
        in: header
        description: Supports application/json.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: 'Request should contain OAuth Authorization header <br> **OAuth:** <br> Request contains a header parameter in the form of Authorization: Bearer (access_token), where access_token is generated using the OAuth url<br>  `Example` : Bearer AAIkMjU2OTI4OGQtODY5Ny00ZjgzLTg0NzEtY2QyZWYwZjM5ZjJk_m3yqnGAbxR_ovVx5bs9OUfF0dd52qHadLtw2ARkwCw2BJcwg1zHsTOuvjPtsW5ioxxd2xXXjlDDCKLuvg15Ce1gzGxTu17xEvLOzSECLIdU_02JbpS3h9ee9GzB-u_MPfKseOiACXYAh_7AVWQhtRMLDKd8RgCUsNzTGXXBeE4'
        required: true
        schema:
          type: string
      - name: Accept
        in: header
        description: Content-Types that are acceptable for the response. Always pass application/json or dont pass this header.
        required: false
        schema:
          type: string
          default: application/json
      - name: Accept-Language
        in: header
        description: List of acceptable human languages for response.
        required: false
        schema:
          type: string
      - name: Content-Type
        in: header
        description: The MIME type of the body of the request (POST). Always pass application/json.
        required: true
        schema:
          type: string
          default: application/json
      - name: Req-Sys-Id
        in: header
        description: 'Client unique ID to identify the particular request. <br> `Format`: UUID <br>`Example`: 123d837e-958a-4e9f-bc97-4843ec948123'
        required: true
        schema:
          type: string
      - name: Country
        in: header
        description: 'Country Code in alpha-2 format. <br>`Example`: US'
        required: true
        schema:
          type: string
      - name: Region
        in: header
        description: 'Country Region. <br> `Example`: NAM'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success Response after Webhook Token Transition
          headers:
            Api-Sys-Id:
              description: Citi Commercial Cards API Tracking ID
              schema:
                type: string
        '400':
          description: Missing or invalid request parameter <table><tr><td>Error Code</td><td>Error Description</td></tr> <tr><td>WWTA0001</td><td>Event Type is invalid</td></tr> <tr><td>WWTA0003</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>WWTA0004</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>WWTA0005</td><td>Fulfilment status is invalid</td></tr> <tr><td>WWTA0006</td><td>Token state is invalid</td></tr> <tr><td>WWTA0007</td><td>Notification ID is invalid</td></tr> <tr><td>WWTA0008</td><td>Marqeta DPAN Reference Id is invalid</td></tr> <tr><td>WWTA0009</td><td>Marqeta DPAN Reference Id is empty</td></tr> <tr><td>WWTA0010</td><td>Transition channel is invalid</td></tr> <tr><td>WWTA0011</td><td>Webhook creation timestamp is invalid</td></tr> <tr><td>WWTA0012</td><td>Number of notifications in array is invalid</td></tr> <tr><td>WWTA0013</td><td>Token requestor Id is invalid</td></tr> <tr><td>WWTA0014</td><td>FPAN is invalid</td></tr><br><tr><td>GRC0002</td><td>Client ID is missing in the request header</td></tr> <tr><td>GRC0003</td><td>Invalid JSON Input</td></tr> <tr><td>GRC0004</td><td>Region ID is not available in the request</td></tr> <tr><td>GRC0005</td><td>Client Tracking ID is missing in the request header</td></tr> <tr><td>GRC0007</td><td>Client requested MediaType is not supported.</td></tr> <tr><td>GRC0008</td><td>Invalid request. Unable to bind incoming request</td></tr> <tr><td>GRC0010</td><td>Client Tracking ID length should contain a min of 1 character and a max of 36 characters</td></tr> <tr><td>GRC0016</td><td>Country code is not available in the request</td></tr> <tr><td>WEIM0001</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>WEIC0001</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> </table>
          headers:
            Api-Sys-Id:
              description: Citi Commercial Cards API Tracking ID
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookErrorResponse'
        '401':
          description: UnAuthorized request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnAuthorizedResponse'
        '405':
          description: Method Not Allowed.
          headers:
            Api-Sys-Id:
              description: Citi Commercial Cards API Tracking ID
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowedResponse'
        '500':
          description: Internal server error. <table><tr><td>Error Code</td><td>Error Description</td></tr> <tr><td>WWTA0002</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>WWTA0015</td><td>webhooks notification should have min and max of 1 item in an array</td></tr><br><tr><td>GRC0001</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>GRC0009</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>GRC0014</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>GRC0015</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>GRVL0001</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>GRVL0002</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>GRVL0003</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>GRVL0004</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>GRVL0005</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>GRVL0006</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>GRVL0021</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>WEIM0002</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>WEIC0002</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>WEIC0003</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>WEUL0002</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>ECSA0002</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> <tr><td>ECSA0007</td><td>We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments</td></tr> </table>
          headers:
            Api-Sys-Id:
              description: Citi Commercial Cards API Tracking ID
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Webhook%5fDigitalWalletTokenTransition%5fArray%5fType'
        description: Webhook token event Request Body
        required: true
components:
  schemas:
    UnAuthorizedResponse:
      type: object
      required:
      - httpCode
      - httpMessage
      - moreInformation
      properties:
        httpCode:
          type: string
          example: '401'
          description: Error code to be sent to the client.
          minLength: 1
          maxLength: 10
        httpMessage:
          type: string
          example: Unauthorized
          description: Error message to be sent to the client.
          minLength: 1
          maxLength: 255
        moreInformation:
          type: string
          example: Access Denied
          description: More details related to the error to be sent to the client.
          minLength: 1
          maxLength: 255
    InternalServerErrorResponse:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorMessage'
          minItems: 1
    MethodNotAllowedResponse:
      type: object
      required:
      - httpCode
      - httpMessage
      - moreInformation
      properties:
        httpCode:
          type: string
          example: '405'
          description: Error code to be sent to the client.
          minLength: 1
          maxLength: 10
        httpMessage:
          type: string
          example: Method Not Allowed
          description: Error message to be sent to the client.
          minLength: 1
          maxLength: 255
        moreInformation:
          type: string
          example: Requested HTTP operation is not supported
          description: More details related to the error to be sent to the client.
          minLength: 1
          maxLength: 255
    ErrorMessage:
      type: object
      required:
      - errorCode
      - errorDescription
      properties:
        errorCode:
          type: string
          description: Error code to be sent to the client,
          minLength: 1
          maxLength: 10
        errorDescription:
          type: string
          description: Error description to be sent to the client.
          minLength: 1
          maxLength: 255
      description: List of error code and description to be sent to the client.
    WebhookErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/WebhookErrorType'
    WebhookErrorType:
      type: object
      required:
      - error_message
      - event_type
      - token
      properties:
        token:
          type: string
          example: 8c84fab9-889c-4cb7-a330-accac5799ea5
          description: Identifier for this particular webhook. This will typically be a GUID but is typed as a string
          minLength: 1
          maxLength: 36
        event_type:
          type: string
          example: digitalwallettoken.provisioningrequest
          description: Event type of the notification.<br><br>Possible values are <br>digitalwallettoken.provisioningrequest<br>digitalwallettoken.activation<br>
          minLength: 1
          maxLength: 255
        error_code:
          type: string
          description: Error Code
          minLength: 1
          maxLength: 75
        error_message:
          type: string
          description: Error Message
          minLength: 1
          maxLength: 255
  securitySchemes:
    clientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://tts.apib2b.citi.com/tts/cards/api/v1/oauth2/token
      description: 'All CitiConnect APIs use the oAuth2 authentication scheme, which requires a bearer token to authenticate your API call. The Token URL includes the version of authentication used by this API. See <a href="../../authentication/authentication-api-reference/" target="_blank">the Citi Authentication API reference</a> for information on requesting a token.


        '