---
updatedAt: 2026-04-21T09:29:18.000Z
agentTools:
  projectIndex: https://partner.getpliant.com/llms.txt
---

# Callback: Add/Update

> 🔒 **Required scope:** `callbacks.setup:write`
>
> The API credential calling this endpoint must be granted the `callbacks.setup` category with `read & write` access.
> Scopes are assigned to the credential when it is created or edited in Pliant, not requested when obtaining the access token.
> A credential without this scope receives `403 Forbidden` with the error code `INSUFFICIENT_PERMISSION`.

Subscribe to callbacks for this entity or change an existing callback.


# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "contact": {
      "name": "API Support",
      "email": "support@getpliant.com",
      "url": "https://www.getpliant.com"
    },
    "title": "Pliant Partner API",
    "description": "Pliant Partner API",
    "version": "2.1.0",
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/license/MIT"
    }
  },
  "servers": [
    {
      "url": "https://partner-api.getpliant.com/api",
      "description": "Pliant Production Server"
    },
    {
      "url": "https://sandbox.partner-api.getpliant.com/api",
      "description": "Pliant Sandbox Server"
    },
    {
      "url": "https://pci-api.getpliant.com",
      "description": "PCI Vault Production Server"
    },
    {
      "url": "https://pci-sandbox.partner-api.getpliant.com",
      "description": "PCI Vault Sandbox Server"
    }
  ],
  "x-readme": {
    "explorer-enabled": false,
    "samples-languages": [
      "curl",
      "java",
      "kotlin"
    ],
    "headers": [
      {
        "key": "Pliant-API-Version",
        "value": "2.1.0"
      }
    ]
  },
  "tags": [
    {
      "name": "Mobile Wallet Tokenization",
      "description": "This tag is for operations related to mobile wallet tokenization"
    }
  ],
  "paths": {
    "/mobile-wallet-tokenizations/subscription": {
      "post": {
        "summary": "Callback: Add/Update",
        "description": "> 🔒 **Required scope:** `callbacks.setup:write`\n>\n> The API credential calling this endpoint must be granted the `callbacks.setup` category with `read & write` access.\n> Scopes are assigned to the credential when it is created or edited in Pliant, not requested when obtaining the access token.\n> A credential without this scope receives `403 Forbidden` with the error code `INSUFFICIENT_PERMISSION`.\n\nSubscribe to callbacks for this entity or change an existing callback.\n",
        "x-required-scopes": [
          "callbacks.setup:write"
        ],
        "tags": [
          "Mobile Wallet Tokenization"
        ],
        "operationId": "create-mobile-wallet-tokenization-subscription",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "callbackUrl": {
                    "type": "string",
                    "format": "uri",
                    "example": "https://myserver.com/send/callback/here",
                    "description": "The URL to send the callback to. Must be a valid and reachable URL. We do some basic validation to ensure the URL is syntactically correct and reachable for Pliant. Only HTTPS URLs are supported."
                  },
                  "eventTypes": {
                    "type": "array",
                    "description": "The event types to subscribe to.",
                    "items": {
                      "type": "string",
                      "enum": [
                        "CARD_TOKENIZATION_OTP",
                        "CARD_TOKENIZATION_STATUS_CHANGE"
                      ]
                    }
                  }
                },
                "required": [
                  "callbackUrl",
                  "eventTypes"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "500": {
            "description": "Internal Server Error"
          }
        },
        "callbacks": {
          "cardTokenizationOTP": {
            "{$request.body#/callbackUrl}": {
              "post": {
                "parameters": [
                  {
                    "in": "header",
                    "name": "X-Organization-Id",
                    "schema": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Referencing the organization this callback was sent for. See [guides](/docs/callbacks) for more details. Example value: `54e6e7e7-0c23-4a54-bccb-2d3ff2fd02df`."
                    }
                  },
                  {
                    "in": "header",
                    "name": "X-Partner-Organization-Id",
                    "schema": {
                      "type": "string",
                      "description": "Filled, if the value `partnerOrganizationId` is [set](/reference/update-organization) by the partner on the organization itself. Referencing the organization identifier of the partner. Example value: `abc123`."
                    }
                  },
                  {
                    "in": "header",
                    "name": "X-Payment-Program-Id",
                    "schema": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Referencing the payment program this callback was sent for. See [guides](/docs/callbacks) for more details. Example value: `54e6e7e7-0c23-4a54-bccb-2d3ff2fd02df`."
                    }
                  },
                  {
                    "in": "header",
                    "name": "X-Callback-Id",
                    "schema": {
                      "type": "string",
                      "format": "uuid",
                      "description": "A unique identifier for this callback. Can be used to deduplicate callbacks to achieve idempotent behavior. See [guides](/docs/callbacks) for more details. Example value: `12a03093-eaad-4ae5-9d8d-42e7f6f8b7c6`."
                    }
                  },
                  {
                    "in": "header",
                    "name": "X-Callback-Created-At",
                    "schema": {
                      "type": "string",
                      "format": "date-time",
                      "description": "The date and time when the callback was created. Can be used to reorder callbacks. See [guides](/docs/callbacks) for more details. Example value: `2024-03-15T15:55:58.623375258Z`."
                    }
                  }
                ],
                "requestBody": {
                  "$ref": "#/components/requestBodies/TokenizationOTPCallback"
                },
                "responses": {
                  "200": {
                    "description": "We expect the partner to return a HTTP 200 status code if the callback was successfully received. On 4xx and 5xx status codes, we will [retry](/docs/callbacks#retries) the callback."
                  }
                }
              }
            }
          },
          "cardTokenizationStatusChange": {
            "{$request.body#/callbackUrl}": {
              "post": {
                "parameters": [
                  {
                    "in": "header",
                    "name": "X-Organization-Id",
                    "schema": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Referencing the organization this callback was sent for. See [guides](/docs/callbacks) for more details. Example value: `54e6e7e7-0c23-4a54-bccb-2d3ff2fd02df`."
                    }
                  },
                  {
                    "in": "header",
                    "name": "X-Partner-Organization-Id",
                    "schema": {
                      "type": "string",
                      "description": "Filled, if the value `partnerOrganizationId` is [set](/reference/update-organization) by the partner on the organization itself. Referencing the organization identifier of the partner. Example value: `abc123`."
                    }
                  },
                  {
                    "in": "header",
                    "name": "X-Payment-Program-Id",
                    "schema": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Referencing the payment program this callback was sent for. See [guides](/docs/callbacks) for more details. Example value: `54e6e7e7-0c23-4a54-bccb-2d3ff2fd02df`."
                    }
                  },
                  {
                    "in": "header",
                    "name": "X-Callback-Id",
                    "schema": {
                      "type": "string",
                      "format": "uuid",
                      "description": "A unique identifier for this callback. Can be used to deduplicate callbacks to achieve idempotent behavior. See [guides](/docs/callbacks) for more details. Example value: `12a03093-eaad-4ae5-9d8d-42e7f6f8b7c6`."
                    }
                  },
                  {
                    "in": "header",
                    "name": "X-Callback-Created-At",
                    "schema": {
                      "type": "string",
                      "format": "date-time",
                      "description": "The date and time when the callback was created. Can be used to reorder callbacks. See [guides](/docs/callbacks) for more details. Example value: `2024-03-15T15:55:58.623375258Z`."
                    }
                  }
                ],
                "requestBody": {
                  "$ref": "#/components/requestBodies/TokenizationStatusCallback"
                },
                "responses": {
                  "200": {
                    "description": "We expect the partner to return a HTTP 200 status code if the callback was successfully received. On 4xx and 5xx status codes, we will [retry](/docs/callbacks#retries) the callback."
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "This API uses oAuth2 with client credentials flow to [obtain the Bearer Token](/docs/authenticated-api-usage).",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "TokenizationOTPCallback": {
        "properties": {
          "organizationId": {
            "type": "string",
            "format": "uuid",
            "description": "The organization ID."
          },
          "cardId": {
            "type": "string",
            "format": "uuid",
            "description": "The card ID."
          },
          "cardAccountId": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "The unique identifier of the card account this card belongs to."
          },
          "tokenizationId": {
            "type": "string",
            "format": "uuid",
            "description": "The tokenization ID."
          },
          "otp": {
            "type": "string",
            "description": "The OTP for this tokenization process."
          },
          "activationMethod": {
            "type": "string",
            "enum": [
              "EMAIL",
              "SMS",
              "OTHER"
            ],
            "description": "The activation method for the tokenization process, meaning how the OTP should be transferred to the cardholder. Valid values are `EMAIL`, `SMS` and `OTHER`. If `EMAIL`, the OTP should be send via email by the partner to the cardholder. If `SMS`, the OTP is send via SMS to the cardholder directly by Thredd (Pliant's credit card processor). The partner can omit this callback basically, or add additional logic if relevant. `OTHER` acts as a fallback if the activation method is not properly defined, it is up to the partner to decide the method then."
          }
        }
      },
      "TokenizationStatusCallback": {
        "properties": {
          "organizationId": {
            "type": "string",
            "format": "uuid"
          },
          "cardId": {
            "type": "string",
            "format": "uuid"
          },
          "cardAccountId": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "The unique identifier of the card account this card belongs to."
          },
          "tokenizationId": {
            "type": "string",
            "format": "uuid"
          },
          "provisioningStatus": {
            "type": "string",
            "description": "The status of the provisioning flow overall. It can be used to determine if the cardholder has successfully tokenized a card in a mobile wallet. Details about the order of status can be found in our guides section about the [green](/docs/apple-pay-google-pay-integration#green-flow-status-changes) and [yellow](/docs/apple-pay-google-pay-integration#yellow-flow-status-changes) flow.",
            "enum": [
              "TOKEN_CREATED",
              "PASSCODE_SENT",
              "TOKEN_PROVISIONED",
              "TOKEN_ACTIVATED",
              "TOKEN_ACTIVATION_FAILED"
            ]
          },
          "tokenStatus": {
            "type": "string",
            "description": "The status of the provisioned token itself. So after the provisioning flow finishes (see `provisioningStatus`) the token becomes `ACTIVE` and can then change status depending on how the user acts with the credit card in his mobile wallet.",
            "enum": [
              "ACTIVE",
              "DEACTIVATED",
              "DELETED",
              "INACTIVE",
              "SUSPENDED",
              "UNKNOWN"
            ]
          },
          "deviceId": {
            "type": "string",
            "description": "A technical identification of the device that is carrying the mobile wallet.",
            "nullable": true
          },
          "wallet": {
            "type": "string",
            "description": "The type of wallet that is used. For now the only valid values are `APPLE` and `ANDROID`.",
            "enum": [
              "APPLE",
              "ANDROID"
            ]
          }
        }
      },
      "Event": {
        "type": "object",
        "properties": {
          "eventType": {
            "type": "string",
            "description": "The type of event."
          }
        }
      }
    },
    "requestBodies": {
      "TokenizationOTPCallback": {
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Event"
                },
                {
                  "$ref": "#/components/schemas/TokenizationOTPCallback"
                }
              ]
            }
          }
        }
      },
      "TokenizationStatusCallback": {
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Event"
                },
                {
                  "$ref": "#/components/schemas/TokenizationStatusCallback"
                }
              ]
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ]
}
```