{
  "openapi": "3.1.0",
  "info": {
    "title": "Tokenization API",
    "version": "draft",
    "description": "Shared API for tokenization payment handlers. Tokenizer services implement these endpoints to enable secure credential exchange. See the Tokenization Guide for implementation details."
  },
  "paths": {
    "/tokenize": {
      "post": {
        "operationId": "tokenize",
        "summary": "Tokenize Credential",
        "description": "Convert a credential into a token bound to a specific capability resource. Handlers define accepted credential schemas and their own authentication requirements.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["credential", "binding"],
                "properties": {
                  "credential": {
                    "$ref": "../../schemas/common/types/payment_credential.json",
                    "description": "Credential to tokenize. Handlers define accepted credential types in their specification."
                  },
                  "binding": {
                    "$ref": "../../schemas/common/types/binding.json",
                    "description": "Resource this token is bound to. Ties the token to a specific capability resource."
                  },
                  "identity": {
                    "$ref": "../../schemas/common/types/payment_identity.json",
                    "description": "The participant this token is issued to. Required when acting on behalf of another participant, for example an agent tokenizing for a business. Omit when the authenticated caller is that participant."
                  }
                }
              },
              "examples": {
                "pan_credential_agent": {
                  "summary": "Agent tokenizing a PAN credential on behalf of merchant",
                  "value": {
                    "credential": {
                      "type": "pan",
                      "number": "4111111111111111",
                      "expiry_month": 12,
                      "expiry_year": 2026,
                      "cvc": "123",
                      "name": "Jane Doe"
                    },
                    "binding": {
                      "type": "dev.ucp.shopping.checkout",
                      "id": "abc123"
                    },
                    "identity": {
                      "access_token": "merchant_abc123"
                    }
                  }
                },
                "pan_credential_merchant": {
                  "summary": "Merchant tokenizing a PAN credential for themselves",
                  "value": {
                    "credential": {
                      "type": "pan",
                      "number": "4111111111111111",
                      "expiry_month": 12,
                      "expiry_year": 2026,
                      "cvc": "123",
                      "name": "Jane Doe"
                    },
                    "binding": {
                      "type": "dev.ucp.shopping.checkout",
                      "id": "xyz789"
                    }
                  }
                },
                "network_token_credential_agent": {
                  "summary": "Agent tokenizing a network token credential",
                  "value": {
                    "credential": {
                      "type": "network_token",
                      "number": "5204240000004242",
                      "expiry_month": 12,
                      "expiry_year": 2026,
                      "cryptogram": "gXc5UCLnM6ckD7pjM1TdPA==",
                      "eci_value": "07",
                      "token_requestor_id": "12345678901",
                      "name": "Jane Doe"
                    },
                    "binding": {
                      "type": "dev.ucp.shopping.checkout",
                      "id": "abc123"
                    },
                    "identity": {
                      "access_token": "merchant_abc123"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["token"],
                  "properties": {
                    "token": {
                      "type": "string",
                      "description": "The token value."
                    }
                  }
                },
                "examples": {
                  "token_response": {
                    "summary": "Token response",
                    "value": {
                      "token": "tok_abc123xyz789"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/detokenize": {
      "post": {
        "operationId": "detokenize",
        "summary": "Detokenize",
        "description": "Retrieve the original credential. The binding must match what was provided during tokenization. Handlers define their own authentication and response schemas.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["token", "binding"],
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "The token value."
                  },
                  "binding": {
                    "$ref": "../../schemas/common/types/binding.json",
                    "description": "Resource binding that must match the original tokenization request."
                  },
                  "identity": {
                    "$ref": "../../schemas/common/types/payment_identity.json",
                    "description": "Participant whose token is being retrieved. Required when the caller acts on behalf of another participant; omit when the authenticated caller is that participant."
                  }
                }
              },
              "examples": {
                "detokenize_by_merchant": {
                  "summary": "Merchant detokenizing their own token",
                  "value": {
                    "token": "tok_abc123xyz789",
                    "binding": {
                      "type": "dev.ucp.shopping.checkout",
                      "id": "xyz789"
                    }
                  }
                },
                "detokenize_by_psp": {
                  "summary": "PSP detokenizing on behalf of merchant",
                  "value": {
                    "token": "tok_abc123xyz789",
                    "binding": {
                      "type": "dev.ucp.shopping.checkout",
                      "id": "abc123"
                    },
                    "identity": {
                      "access_token": "merchant_abc123"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Credential retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "../../schemas/common/types/payment_credential.json"
                },
                "examples": {
                  "pan_credential": {
                    "summary": "PAN credential",
                    "value": {
                      "type": "pan",
                      "number": "4111111111111111",
                      "expiry_month": 12,
                      "expiry_year": 2026,
                      "cvc": "123",
                      "name": "Jane Doe"
                    }
                  },
                  "network_token_credential": {
                    "summary": "Network token credential",
                    "value": {
                      "type": "network_token",
                      "number": "5204240000004242",
                      "expiry_month": 12,
                      "expiry_year": 2026,
                      "cryptogram": "gXc5UCLnM6ckD7pjM1TdPA==",
                      "eci_value": "07",
                      "token_requestor_id": "12345678901",
                      "name": "Jane Doe"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}